Getting started

Units and limits

There are two independent limits, and they fail in different ways. Confusing them is the usual reason an integration behaves oddly under load.

Burst rate limitMonthly quota
Counted perAPI keyAccount (all your keys together)
Unit of accountRequestsUnits — endpoints cost different amounts
Window60 seconds, rollingCalendar month, UTC
HeadersX-RateLimit-*X-Quota-*
When it trips429 — wait seconds and retry429 — wait until the 1st, or upgrade

Why units and not requests

A request is not a request. A metadata read is an in-process lookup; a charts call is a multi-query fan-out to a paid upstream that we pay for per call. Charging both the same would mean either overcharging for the cheap one or subsidising the expensive one out of everybody else’s allowance.

TierUnitsEndpoints
Metadata0/v1/chains, /v1/protocols
Detail1/v1/positions/:chainId/:protocol/:id, /v1/positions/:chainId/:protocol/:id/transactions, /v1/pools/:chainId/:protocol/:id
Detail, per position1 × positions returned/v1/positions/batch
List2/v1/positions, /v1/pools, /v1/tokens/:chainId/:address
Charts10…/charts on either resource

The live table is served from GET /v1/pricing/units and rendered on the pricing page. Read it from the API rather than hard-coding these numbers.

Fetching many positions: billed per position

GET /v1/positions/batch?chainId=1&ids=… returns up to 100 positions in one request and costs what the same number of single-position calls would: the detail price per position returned. Ids listed in missing and positions whose transaction list could not be loaded (transactionsDegraded) are not charged.

The whole request is charged up front, and the part that was not served is credited back before the answer is sent. X-Units-Charged is the net charge, and X-Quota-Remaining already includes the credit. A quota that cannot cover every id you asked for refuses the call with a 429 and uses none of your units; ask for fewer ids. Against the burst rate limit a batch counts as one request per 10 ids asked for, rounded up: 1 to 10 ids is one request, 100 ids is ten.

http
HTTP/1.1 200 OK
X-Units-Charged: 98
X-Quota-Remaining: 99714

{"chainId":1,"protocol":"uniswap-v4","positions":[…98 rows…],"missing":["5003","5004"]}

When the quota resets

00:00 UTC on the 1st of each month. Not a rolling 30 days, and not the anniversary of when you subscribed. X-Quota-Reset is the number of seconds until that instant, so you can act on it without doing calendar arithmetic.

The consequence worth planning for: subscribing on the 20th gives you the whole month’s allowance, and it resets eleven days later. We would rather be clear about that than quietly prorate an allowance nobody can predict.

Requests we refuse are not billed

Units are consumed before your request is served, and credited back on any 4xx. A malformed filter, an unknown position id, a 403 from a server key used in a browser — none of them cost anything. Billing for a request the API declined is not defensible, so we do not.

A 429 is the exception, and only technically: it is rejected before anything is consumed, so there is nothing to credit. A request that costs more than you have left is refused without touching what you have left, so a smaller request can still go through.

Every 5xx is credited back too, including the 503 with Retry-After returned when a read does not finish in time, such as a very deep list page that is still being reached. So is a 200 that reports it did not deliver everything asked for: a list or chart carrying "partial": true, or a position detail carrying "transactionsDegraded": true or "transactionsPartial": true. A response flagged "stale": true is complete, only older, and is billed normally.

MCP tool calls cost the same units as the API route behind them, and are counted under the key you gave the MCP client.

Reusing a response for 15 seconds

A successful response from a /v1/positions, /v1/pools or /v1/tokens route carries Cache-Control: private, max-age=15 and Vary: KC-APIKey. Your own client may reuse it for 15 seconds without asking again. private means a shared cache, proxy or CDN must not store it, and Vary means a copy is only reused for the same key.

http
HTTP/1.1 200 OK
Cache-Control: private, max-age=15
Vary: KC-APIKey
X-Quota-Remaining: 99812

A response reused from your own cache costs no units, because no request is sent. Every request that does reach the API is metered as usual, even within those 15 seconds. That includes a revalidation with If-None-Match answered 304 Not Modified. Many HTTP clients (server-side fetch, curl, most SDKs) keep no cache at all, so you only save units if yours does.

The header allows reuse; it does not say how old the data is. Read dataAsOf and stale for that. A reused response also repeats the X-RateLimit-* and X-Quota-* values from the original request. Errors, and any 200 flagged partial, stale or countsPending, are sent with Cache-Control: no-store and are never reused. So is a positions batch with any id in missing or any row degraded or stale.

Handling a 429

Both kinds carry Retry-After in seconds. Honour it rather than retrying on a fixed timer — a burst 429 clears in seconds, a quota 429 clears at the month boundary, and the header is how you tell them apart without parsing prose. The body also carries retryAfterSec.

http
HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0

{"error":"Rate limit exceeded","retryAfterSec":12}

If a paid plan lapses

Your account moves to Free and your keys keep working at Free limits. Nothing is revoked and nothing is deleted. Your consumed units for the current month are also reset at that point, so a downgrade cannot leave you locked out for the rest of the month on an allowance you had already spent.