Docs that ship.

Mint a staging key in API keys, then POST your first top-up:

curl -X POST https://aitopup.dev/api/public/v1/topup/send \
  -H "Authorization: Bearer ak_staging_..." \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "claude",
    "amount_cents": 1000,
    "recipient_email": "user@example.com",
    "model": "claude-sonnet-4",
    "idempotency_key": "order_12345"
  }'

The response envelope:

{
  "success": true,
  "code": 1001,
  "transaction_id": "txn_…",
  "status": "delivered",
  "timestamp": "2026-07-28T15:51:41.002Z",
  "data": {
    "voucher_code": "AITOPUP-XXXX-XXXX",
    "platform": "claude",
    "amount_cents": 1000,
    "wholesale_cost_cents": 850,
    "platform_fee_cents": 15,
    "new_balance_cents": 5400
  }
}

List price per platform (cents per 1M tokens). Your wholesale cost depends on your partner tier; a 1.50% platform fee is added on every /topup/send.

Partner tiers

Token-aware estimate

curl -X POST https://aitopup.dev/api/public/v1/topup/estimate \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "platform": "chatgpt", "tokens_in": 250000, "tokens_out": 80000 }'

• GET/v1/pricingList prices + your discount
• POST/v1/topup/estimateQuote from token counts
• POST/v1/topup/sendDeliver a top-up
• GET/v1/topup/balanceWallet balances
• GET/v1/topup/historyPaginated history
• POST/v1/topup/validatePre-flight check
• POST/v1/topup/cancelCancel pending
• GET/v1/topup/status/{txn}Lookup by id
• POST/v1/webhooks/registerAdd a webhook
• GET/DELETE/v1/webhooks/{id}Read or remove
• GET/v1/openapi.jsonFull OpenAPI 3.1 spec

Each delivery is signed with X-AiTopUp-Signature: HMAC-SHA256 over the raw body using your endpoint secret. Retries run 0s · 5s · 30s with exponential backoff. Replay any delivery from Settings → Webhooks.

• topup.delivered— Credit sent to recipient
• topup.failed— Delivery failed — no funds moved
• topup.cancelled— Pending top-up cancelled
• balance.low— Wallet below your threshold

Numeric codes are stable across versions. HTTP status follows the obvious mapping (401, 402, 404, 409, 429, …).