Docs›Getting started›Rate limits
Getting started

Rate limits

Nextbridge applies per-API-key sliding-window limits across both the MCP server and the REST API. Limits are enforced in Redis so they are correct across multiple serverless instances.

Per-key buckets

Each API key has three independent buckets. The bucket used for a given call depends on what the tool or endpoint does — see the tier table below.

Tier
Per minute
Per day
Used by
read
120
5,000
Balances, market data, transaction history, P2P listings, alert reads.
write
30
500
Spot trades, alert create/delete, withdrawals, P2P actions (initiate, mark paid, dispute, message).
admin
60
1,000
ADMIN-scoped tools at /api/mcp/admin only. Treasury, dispute resolution, platform settings.

Both windows are checked on every call. If either bucket is exhausted, the request is rejected — you do not need to hit both to be throttled.

What you get back

A throttled request returns HTTP 429 with theRATE_LIMITED error code. From an MCP tool call the same condition surfaces as a tool error your AI client will see and retry.

The message tells you whether you hit the per-minute or the per-day bucket. The counter resets at the end of the corresponding window (60 seconds, or 24 hours).

Tier classification

MCP user-scope tools are classified automatically. Anything that mutates state goes in thewrite bucket; everything else is read. ADMIN-scoped tools always use the admin bucket.

  • write: place_spot_trade, create_price_alert, delete_price_alert, request_withdrawal, initiate_p2p_trade, mark_p2p_paid, raise_p2p_dispute, send_p2p_message
  • read: everything else (portfolio, market, transactions, alerts list, P2P listings, …)

Staying under the limit

  • Cache the response of read calls inside your agent loop. Balances and prices move slowly.
  • Use get_market_top (batched) instead of looping get_market_price per coin.
  • On 429, back off for a few seconds before retrying — the bucket refills automatically.
  • If you have a legitimate use case for higher limits (production trading bot, exchange integration), email devs@nextbridge.io.