Rate limits and quotas

Everything is counted in calls, and there are three limits on them:

1. Calls per month. What you pay for. A hard cap with no overage charges.
2. Calls per minute. A fixed window per clock minute.
3. Burst. A bucket that holds your plan's maximum calls per request and refills at the per-second rate, so one full request always fits in a full bucket.

Calls: one per item, weightedCopy Anchor Link

A call is counted by what you get back or ask for, not by HTTP request. Most items cost 1 call. Richer items cost more.

• A list costs its weight for each item it returns. A page of 37 trending coins costs 37 calls. A page of 20 footprint candles costs 40, because a footprint candle weighs 2.
• A batch costs its weight for each id you ask for. /v1/sentiment/callers?assets=BTC,ETH,SOL,DOGE,XRP costs 5 calls, even if one of the assets has no data.
• A single lookup has a flat cost: 1 call for /v1/analytics/crowd/BTC, 2 for /v1/coins/BTC, 3 for /v1/liquidations/BTC. A lookup that finds nothing still pays.
• A search costs 5 calls plus 1 call per result. A search with no results costs 5.
• A stream connection is free. Each event delivered costs 1 call, taken before it is sent.
• An empty list costs 1 item's worth, so polling an empty list is not free.
• /v1/status, /v1/usage and /v1/tombstones are free.
• Test keys never count towards the month.

Every response tells you what it cost in the X-Decryptr-Cost header. The API reference shows the cost on each endpoint.

Reserved before it runsCopy Anchor Link

Before a list runs, the API reserves the most it could cost: limit times the calls per item. If your remaining budget cannot cover that, the request is refused with 429 and nothing is read or charged. Ask for a smaller limit to fit. After the request runs, the unused part comes back and you pay only for what was returned.

A worked exampleCopy Anchor Link

You are on Starter and have 60 calls left this month.

Page sizesCopy Anchor Link

Each plan sets the most calls one request may reserve. For searches the 5 call base counts too. The most items per request is that number divided by the endpoint's weight, rounded down. On Pro (50), you can ask for 50 trending coins, or 25 footprint candles. Asking for more is refused with 400 limit_too_large, and the error's max_items says what your plan allows.

When calls run outCopy Anchor Link

Every plan is a hard cap. There are no surprise bills: requests are refused with 429 quota_exceeded until the month resets on the 1st (UTC) or you upgrade. See Plans and pricing.

Limits per planCopy Anchor Link

The per-second figure is how fast the burst bucket refills. All figures are calls.

Headers on every responseCopy Anchor Link

Every authenticated response, including a 429, carries these:

X-Request-Id: 3f6c2a8e-6a1f-4c1e-9d2b-0a5e7c1d9b42
X-Decryptr-Cost: 37
RateLimit-Policy: "burst";q=25;w=1, "minute";q=60;w=60, "month";q=50000;w=2592000
RateLimit: "minute";r=23;t=37
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 23
X-RateLimit-Reset: 37
X-RateLimit-Burst-Remaining: 12
X-Quota-Limit: 50000
X-Quota-Remaining: 48210

/v1/usage returns your plan, limits and calls used as JSON, and is free to call.

Handling 429Copy Anchor Link

A 429 always comes with Retry-After and a problem body whose code says which limit you hit. For rate_limited and quota_exceeded, the body also has limit (burst, minute or quota), calls_requested and retry_after.

Retry rate_limited with exponential backoff and jitter, and respect Retry-After when it is longer:

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

export async function getWithBackoff(url, key, maxTries = 5) {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
    if (res.status !== 429) return res;

    const problem = await res.json();
    // Only the request rate is worth retrying; the other 429s will fail again.
    if (problem.code !== "rate_limited" || attempt + 1 >= maxTries) return res;

    const retryAfter = Number(res.headers.get("Retry-After") ?? 1) * 1000;
    const backoff = Math.min(30_000, 500 * 2 ** attempt);
    await sleep(Math.max(retryAfter, backoff) + Math.random() * 250);
  }
}