Skip to main content
Limits are enforced per API key, shared across both faces (REST and MCP calls draw from the same budgets).

​
Read window

Applies to every request on the surface, including the three preview_* operations.

​
Write window

An additional, much tighter budget on the operations that actually spend coins or publish: Counted for place_order, publish_opinion and back_opinion (REST: POST /orders, /opinions, /backs). These also consume the read window.
The three previews — preview_order, preview_opinion, preview_back — count against the read window only. They charge nothing, so pricing a few options before asking the user costs you nothing but ordinary read budget.
Windows are fixed per minute/day. Occasional 429s are expected behavior at the edges of a window — build retry logic rather than tuning to the exact numbers.

​
Response headers

Every REST response carries the state of the binding minute window (the one that would reject you first):
X-RateLimit-Reset is seconds until the window resets (not a Unix timestamp).

​
When you hit 429

The response also carries a standard Retry-After: 22 header.
  • Wait retry_after seconds, then retry. Add jitter if you run several workers on one key.
  • Prefer exponential backoff for repeated 429s.
  • Over MCP, a rate-limited call surfaces as a tool error naming the retry delay — agents should read it and pause rather than hammer.
A 429 on an execute call is ambiguous only if it arrives after a timeout: the request may have been rejected before doing anything, which is the normal case. Before retrying place_order or back_opinion, remember the same confirm_token is safe to reuse — a replay returns the original result rather than acting twice. publish_opinion is not replayable: check list_my_opinions instead of retrying blind.

​
Staying under the limits

  • Use limit (up to 100) and cursors instead of many small pages.
  • Cache stable data (categories) on your side.
  • Use list_topics for browsing; save search_topics (the tighter budget) for actual keyword lookups.
  • Don’t poll for a write to “settle” — the execute response is the outcome.