Rate Limits, Permissions and Known Limits

Rate limits

Two independent limiters apply, and a request must pass both.

Limiter	Scope	Default	Error on breach
Per API key	The credential	600 requests per minute	`429 RATE_LIMIT_EXCEEDED`
Global	Per source IP address	120 requests per minute	`429 RATE_LIMITED`
Futures orders	Per user	30 orders per minute	`429 RATE_LIMITED`

The global per-IP limit of 120 per minute is lower than the per-key limit, so it is usually the one you hit first when calling from a single server. It applies to all traffic from that address, signed or not.

Keying the main limit on the credential means a compromised key is bounded on its own. It cannot exhaust the budget of other clients behind the same network address, and spreading it across many machines does not get around the cap.

Back off before you are throttled

Every response carries the standard RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers. Read them and slow down while Remaining is still positive, rather than waiting for a 429 and reacting.

A sensible polling budget from one server: one balance check every few seconds and one order poll per open order every second or two will sit comfortably inside 120 per minute. Polling every open order once per second when you have 30 orders open will not.

Permissions

Every key is issued all four permissions automatically. They are assigned by the server, not chosen. There is no picker in the web app and no permissions field on the create request, and the set never changes for the life of the key.

Permission	Grants access to
`READ_BALANCE`	Wallet balances, and the asset and network catalogue
`READ_ORDERS`	Your spot and futures orders
`SPOT_TRADE`	Placing and cancelling spot orders
`FUTURES_TRADE`	Placing and cancelling futures orders

In practice this means 403 API_PERMISSION_DENIED is rare. If you see it, the route is probably one that API keys cannot reach at all.

An API key can never move funds off the platform
There is no withdrawal permission and no transfer permission, and one cannot be added to a key by any means. It is refused by a database constraint, not merely left unassigned.
A leaked key can lose you money through bad trades. It cannot send your money anywhere. Withdrawals and internal transfers require a logged-in browser session.

KYC applies to every signed endpoint

Several of these endpoints are reachable before verification from a browser session, where an unverified user's dashboard polls them and gets empty answers. The API is stricter. Every signed request returns 403 KYC_REQUIRED until the account's identity verification is approved. An API key is a trading credential, so there is no partial access before verification.

The check runs after signature verification, deliberately. X-MG-API-KEY is a public value, so checking earlier would let anyone holding just that key learn whether its owner is verified.

Practically: finish verification in the web app before you start integrating. Nothing in your client needs to change. The same request simply starts succeeding once verification is approved, and you should allow up to a minute for the status to propagate.

Public market data needs no key, no signature and no verification.

Things this API does not do

Not available	Why, and what to do instead
WebSocket or server-sent event streams for account data	One signature cannot vouch for a long-lived connection. Poll the list endpoints
`POST /v1/transfers`	Moves funds between your own wallets. No permission can authorize fund movement. Use the web app
`GET /v1/wallets`, `/v1/deposit/address`, `/v1/deposit/history`	Deposit addresses and history are session only
`/v1/futures/fills`, `/v1/futures/positions`	Outside the API key permission set
`/v1/withdrawals/*`	Withdrawals are never reachable with an API key
`/v1/admin/*`	An API key carries no role and can never reach the back office

Calling any of these with a valid signature returns 401, not a permission error. They do not participate in API key authentication at all, so the server finds no session and stops there.

Paging: the 200 order ceiling

Neither the spot nor the futures list endpoints offer an offset or a cursor. limit is the only control, and its maximum is 200.

You cannot read further back than your most recent 200 orders. Two things follow:

Poll often enough that 200 orders comfortably covers the interval between polls.

Store your own order history as you go. Treat the API as a live view, not an archive.

Clock accuracy

With the default 5000 ms receive window, a clock more than five seconds out fails every request as INVALID_TIMESTAMP. Run NTP on your server.

If your environment genuinely cannot hold that, raise X-MG-RECV-WINDOW, but never above 60000, and prefer fixing the clock. A wider window is a wider replay surface.

One key per account, for the life of the account

No expiry, no rotation endpoint, no self-service revocation, and never a second key. A disabled key still holds the slot.

If a key is compromised, contact support to have it disabled. Only an administrator can disable or restore it, and restoring returns the same secret rather than issuing a new one. Plan your secret storage accordingly, because you cannot rotate your way out of a leak.

Known issues at the time of writing

Issue	Impact on you
Futures list filters `symbol`, `orderType`, `startTime` and `endTime` are accepted and then ignored	Filter in your own code. A client that trusts these filters will act on the wrong orders
`GET /v1/futures/fills` returns `500` on every call	Do not use it. Read fills from `/v1/futures/orders/history`
A venue-side futures cancel failure surfaces as a generic `500 INTERNAL`	Re-read the order rather than assuming a transport fault. Spot already returns typed `409` and `503` for the same conditions

07. Rate Limits, Permissions and Known Limits

Rate Limits, Permissions and Known Limits#

Rate limits#

Back off before you are throttled#

Permissions#

An API key can never move funds off the platform#

KYC applies to every signed endpoint#

Things this API does not do#

Paging: the 200 order ceiling#

Clock accuracy#

One key per account, for the life of the account#

Known issues at the time of writing#