Retry-After header.
Rate limits
Authenticated windows are keyed per credential — the access token’s credential, not the account it acts for. SwitchingX-Hevn-Account does not buy a second budget, and a thousand clients driven from one server share one pair of counters.
The three login windows cover
POST /auth/challenge and POST /auth/token only. POST /auth/refresh carries no
login limiter — it is an ordinary write, and it re-checks the developer key behind the session before it mints
anything.
Exceeding one answers 429 rate_limited with Retry-After in seconds. Sleep for it and retry — the helper in HTTP client does this for you.
Two consequences worth designing for: a payroll run of 500 payouts is 1,000 writes and needs pacing, and a poller that reads every client every second will exhaust the read budget long before the data changes. Poll with backoff, and batch what you can into GET /dapi/v1/transactions for the whole account.
Windows
An approval is short because it is a signed instruction to move money. Nothing in this API is designed for a human to approve a payload later: prepare, sign and confirm inside one request of your own.
Idempotency
Idempotency-Key matches ^[A-Za-z0-9._:-]{1,128}$. It is accepted on every write and required on none. Derive it from your own business id — order-A-1187, payroll-2026-09-17-contractor-41 — and never from a clock or a random value.
The key is scoped to (your account, the operation). The same string on two operations is not a replay, and two integrators using invoice-1 never collide.
Send no key and the server derives one from the request itself, echoes it as
idempotencyKey, and you can pin that value from then on. A derived key replays for 2 hours; an explicit key replays for 7 days. That is why two genuinely distinct payouts of the same amount, minutes apart, both need explicit keys.
A response that replayed a create answers 200 with Idempotency-Replayed: true instead of 201.
Pages and sizes
There is no
offset anywhere. Walk a list by passing nextCursor back as cursor until it is absent.
The two developer-key caps are the only ones you cannot raise by calling again: the allowlist and the scopes are frozen
when the key is created, so a network the allowlist does not cover needs a second key, not an edit. The publicKey cap
there is the DER-encoded public half, which is a different field from the 512-character publicKey a payout carries.
Sandbox
Every emulated credit is paid by one shared faucet account, so the sandbox caps what a single account can mint. See Sandbox.
Keep two test payouts more than
0.20 apart in amount: returned money is attributed to a refunded payout by amount, within a 0.20 tolerance, so two near-identical test payouts can end up labelled with each other’s refund.
Rate limiting is a deployment setting, and a sandbox host may run with the per-credential and per-account counters switched off. A run that never sees a
429 there is not evidence that your pacing fits the production budget — build the Retry-After path before you go live.Next: HTTP client
The whole client — key loading, login, acting as a client, signing, retries — in Python, Node and Go.