Skip to main content
The API limits requests per client in fixed one-minute windows. Anonymous requests are counted per IP address. Requests that carry an API key or a signed-in session are counted per user and per organization, with a larger allowance.

Allowances

The two anonymous allowances are separate: a client that spends its read allowance can still submit, and the reverse.

How the API identifies a client

An anonymous client is its IP address as Multiliquid’s load balancer sees it. X-Forwarded-For entries that the caller sends are ignored. An IPv6 client is counted by its /64 network, so every address in that network shares one allowance. Systems that reach the API through one egress address, such as servers behind a shared NAT gateway, also share one allowance.

A credential gives a larger allowance

A request that sends an Authorization credential, either a customer API key or a signed-in session token, is authenticated before it runs and is not counted against its IP address. It counts instead against 600 requests a minute for its user and 600 a minute for its organization. Every credentialed request from that user or organization shares these two allowances, including requests to the capital provider routes. An organization API key has no user, so its requests count against its organization’s allowance alone. If you need more than 300 anonymous requests a minute, use an API key. Authentication explains how to get one. A key that lacks a route’s scope receives 403 with INSUFFICIENT_SCOPE. A credentialed POST /v1/submissions or POST /v1/redemptions with a key that lacks trade is rejected this way rather than accepted as an anonymous request. A supplied credential never falls back to anonymous access. A credential that fails authentication receives 401, and a valid one without access receives 403. On the counted routes, each 401 for a supplied credential spends one of the client IP address’s 30 failed authentications a minute. Once they are spent, every request from that address to a counted route that carries a credential receives 429 before it is authenticated, until the window resets. The capital provider, organization, and delegate routes do not use this allowance.

Rate-limit headers

Every response to a counted request reports one allowance in three headers, computed when the response is written:
  • The response reports whichever allowance that counted or rejected the request has the fewest requests left, or on a tie the one that resets later.
  • An anonymous request is counted by the allowance of its group, reads or writes.
  • A credentialed request is counted by its user’s allowance once the credential identifies the user, so a 403 or 503 after that point reports the user’s allowance. It is counted by its organization’s allowance once access is granted. A 401 also spends the client’s failed-authentication allowance.
  • A credential that is rejected before any allowance counts it reports the client’s failed-authentication allowance, which every credential is checked against.
  • An allowance whose window has reset by the time the response is written reports all its requests and a full window, which the next request it counts starts.
  • Routes that are not counted carry none of these headers. Neither does a request rejected before it is counted, such as one that sends a body with a GET.
Browsers can read every header, including these, in cross-origin responses.

When the allowance is spent

A request over its allowance receives 429 with code RATE_LIMITED. Retry-After gives the whole seconds until the window resets, and the allowance resets when Retry-After elapses. On a counted route RateLimit-Remaining is 0; the capital provider, organization, and delegate routes send no rate-limit headers.

A busy service

A 429 whose RateLimit-Remaining is above 0 is not a rate-limit rejection, though it has the same code RATE_LIMITED: the service is busy. Swap quotes and builds, submissions, redemption preparations, and Solana batch order preparations wait up to 5 seconds for capacity before they answer this way. Redemption intake checks one new redemption at a time, so a redemption that arrives while another is being checked receives this 429 at once. The response still carries Retry-After, and its rate-limit headers show the requests the allowance has left.

Backing off

  1. On 429 with RateLimit-Remaining: 0, or without rate-limit headers, the allowance is spent. Wait the Retry-After seconds before sending the request again. Retrying sooner is rejected again and does not shorten the wait.
  2. On 429 with RateLimit-Remaining above 0, the service is busy rather than the allowance spent. Wait Retry-After before retrying.
  3. Pacing: if you send many requests, read RateLimit-Remaining and RateLimit-Reset, and wait for the reset when the remaining count reaches zero instead of running into 429.
  4. On 503 with Retry-After, wait that long. Without Retry-After, retry with exponential backoff and jitter, for example after about 1, 2, 4, and 8 seconds, up to a cap. Don’t retry a 503 with code NETWORK_NOT_ACTIVE: the API does not serve the network.
  5. On 401, fix the credential instead of retrying it. On the counted routes, repeated 401 responses spend the failed-authentication allowance and then block every credentialed request from the same IP address to those routes for the rest of the window.
  6. Retries that change state: resending the same signed transactions to POST /v1/submissions, or the same signed redemption to POST /v1/redemptions, returns the existing records with replayed: true, unless the redemption failed with failure.resubmittable: true, which restarts it instead. Resubmitting the same batch order returns DUPLICATE_ORDER with its orderId, so a retry after a timeout does not submit twice. After a 408 on any other request that changes state, read the current state before retrying. Retries and idempotency covers each route.

Counted routes

Write routes, 300 anonymous requests a minute per client:
  • POST /v1/swap/build, POST /v1/swap/decode, and POST /v1/submissions
  • POST /v1/redemptions and POST /v1/redemptions/prepare
  • POST /v1/batch-orders, POST /v1/batch-orders/prepare, POST /v1/batch-orders/{orderId}/cancel/prepare, and POST /v1/batch-orders/{orderId}/cancel
Read routes, GET and HEAD, 300 anonymous requests a minute per client:
  • /v1/info, /v1/info/evm, and /v1/info/svm
  • /v1/networks and /v1/swap/pairs
  • /v1/transactions and /v1/volume
  • /v1/swap/quote, /v1/submissions, and /v1/submissions/{submissionId}
  • /v1/redemptions and /v1/redemptions/{redemptionId}
  • /v1/batch-orders/info, /v1/batch-orders, and /v1/batch-orders/{orderId}
GET /v1/submissions lists an organization’s submissions, so it requires a credential: an anonymous request spends its client’s read allowance and then receives 401. Health, status, and documentation routes are not counted. The other routes that accept only a credential, the capital provider, organization, and delegate routes, are not counted against the anonymous or failed-authentication allowances and send no rate-limit headers, even on a 401 or 429. They count against the same 600-a-minute user and organization allowances without reporting them.

Errors

The error body and every error code.

API introduction

API keys, test networks, and the interactive reference.