Authentication and limits

No key neededCopy Anchor Link

Every operation answers an unauthenticated request. A keyless caller shares one budget per client address across all operations: an IPv4 address counts on its own, an IPv6 address by its /64.

A key only raises the limits. It goes in a header, never in the query string:

X-API-Key: <your key>
Authorization: Bearer <your key>

• A key that is sent but unknown or revoked is 401, never a quiet downgrade to the keyless tier.
• A key in the query string is rejected with 400 key_in_query: query strings end up in proxy logs and browser history.
• GET /key reports the plan and limits of the key making the call.

Keyless limitsCopy Anchor Link

Without a key you get 300 calls per minute per client address (5 per second, burst 20), counted in units of 10 CU. A call spends its operation's x-avee-cost-cu, never less than one unit, so heavier operations run slower. The largest page a keyless call can ask for is 50 rows.

Reading the headersCopy Anchor Link

Every limited response reports where you stand, in the IETF RateLimit headers and the older X- convention side by side:

RateLimit-Policy: "plan";q=5;w=1;burst=20
RateLimit: "plan";r=17;t=1
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 17

Pace yourself on the remaining count rather than waiting for a refusal.

When you are overCopy Anchor Link

HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/problem+json

Sleep for Retry-After seconds, then retry. Retrying at once only spends the next second's budget.

Paying past the limitCopy Anchor Link

Instead of waiting, a keyless client can pay for the call in USDC with x402: the 429 carries the payment requirements, and a paid retry answers at once.