Don't invest unless you're prepared to lose all the money you invest. This is a high-risk investment and you should not expect to be protected if something goes wrong. Take 2 mins to learn more.

DecryptrDevelopers

Rate limits and quotas

How the Decryptr API counts units (one per item, weighted by endpoint), the limits per plan, the headers on every response, 429 and Retry-After, and a backoff example.

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

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

Units: one per item, weighted

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

  • A list costs its weight for each item it returns. A page of 37 trending coins costs 37 units. 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 units, even if one of the assets has no data.
  • A single lookup has a flat cost: 1 unit 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 units plus 1 unit per result. A search with no results costs 5.
  • A stream connection is free. Each event delivered costs 1 unit, 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.

EndpointCost in unitsReserved before it runs
GET /v1/statusFreeNothing
GET /v1/usageFreeNothing
GET /v1/trending/coins1 unit per item returnedlimit
GET /v1/calls/outcomes1 unit per item returnedlimit
GET /v1/calls/most-called1 unit per item returnedlimit
GET /v1/sentiment/callers1 unit per id asked forNumber of ids
GET /v1/sentiment/{asset}1 unit per item returnedlimit
GET /v1/analytics/crowd/{asset}1 unit, also when not found1
GET /v1/coins/{asset}2 units, also when not found2
GET /v1/prop/programs1 unit per item returnedlimit
GET /v1/levels/rounds1 unit per item returnedlimit
GET /v1/levels/rounds/{id}1 unit, also when not found1
GET /v1/liquidations/{asset}3 units, also when not found3
GET /v1/orderflow/delta1 unit per item returnedlimit
GET /v1/orderflow/footprint2 units per item returnedlimit x 2
GET /v1/derivatives/{asset}/funding1 unit per item returnedlimit
GET /v1/whales/positions2 units per item returnedlimit x 2
GET /v1/whales/positioning2 units per item returnedlimit x 2
GET /v1/calls1 unit per item returnedlimit
GET /v1/calls/{id}1 unit, also when not found1
GET /v1/callers3 units per item returnedlimit x 3
GET /v1/callers/{handle}3 units, also when not found3
GET /v1/traders3 units per item returnedlimit x 3
GET /v1/traders/batch3 units per id asked forNumber of ids
GET /v1/traders/{id}3 units, also when not found3
GET /v1/leaderboard1 unit per item returnedlimit
GET /v1/tombstonesFreeNothing
GET /v1/signals1 unit per item returnedlimit
GET /v1/signals/{id}1 unit, also when not found1
GET /v1/signals/{id}/impact2 units, also when not found2
GET /v1/sentiment/{asset}/news1 unit per item returnedlimit
GET /v1/stream/signals1 unit per event delivered, connecting is freeNothing at connect
GET /v1/trending/topics1 unit per item returnedlimit
GET /v1/calendar1 unit per item returnedlimit
GET /v1/events/{id}/calls1 unit, also when not found1
GET /v1/profiles/{handle}1 unit, also when not found1
GET /v1/search/people5 units, plus 1 unit per item returned5 + limit
GET /v1/posts1 unit per item returnedlimit
GET /v1/posts/{id}1 unit, also when not found1
GET /v1/posts/{id}/replies1 unit per item returnedlimit
GET /v1/coins/{asset}/posts1 unit per item returnedlimit
GET /v1/trending/posts1 unit per item returnedlimit
GET /v1/search/posts5 units, plus 1 unit per item returned5 + limit
GET /v1/stream/posts1 unit per event delivered, connecting is freeNothing at connect
GET /v1/communities1 unit per item returnedlimit
GET /v1/communities/{slug}1 unit, also when not found1
GET /v1/communities/{slug}/posts1 unit per item returnedlimit
GET /v1/lists/{id}1 unit per item returnedlimit
GET /v1/leaderboards/levels1 unit per item returnedlimit
GET /v1/traders/{id}/prop3 units, also when not found3
GET /v1/traders/wallets3 units per item returnedlimit x 3
GET /v1/communities/{slug}/activity1 unit per item returnedlimit
GET /v1/communities/{slug}/members/history1 unit per item returnedlimit
GET /v1/rooms1 unit per item returnedlimit
GET /v1/rooms/{id}/activity1 unit per item returnedlimit
GET /v1/tags/{tag}/volume1 unit per item returnedlimit
GET /v1/trending/tags1 unit per item returnedlimit
GET /v1/levels/rounds/{id}/distribution2 units, also when not found2
GET /v1/prop/firms/{firm}/stats1 unit, also when not found1
GET /v1/whales/leaderboard1 unit per item returnedlimit
GET /v1/market/coins1 unit per item returnedlimit
GET /v1/market/coins/{asset}1 unit, also when not found1
GET /v1/market/tickers1 unit per id asked forNumber of ids
GET /v1/market/candles1 unit per item returnedlimit
GET /v1/market/funding1 unit per item returnedlimit
GET /v1/market/open-interest1 unit per item returnedlimit
GET /v1/market/long-short1 unit per item returnedlimit
GET /v1/market/long-short/exchanges1 unit per item returnedlimit
GET /v1/market/liquidations/heatmap2 units per item returnedlimit x 2
GET /v1/market/liquidations/totals1 unit per item returnedlimit
GET /v1/market/trending1 unit per item returnedlimit

Reserved before it runs

Before a list runs, the API reserves the most it could cost: limit times the units 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 example

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

RequestReservedResultCostLeft
/v1/liquidations/BTC3Runs357
/v1/orderflow/delta?asset=BTC&limit=2525Fits, returns 252532
/v1/orderflow/delta?asset=BTC&limit=2525Fits, returns 25257
/v1/orderflow/delta?asset=BTC&limit=252525 does not fit in 7, refused with 429 quota_exceeded07
/v1/sentiment/callers?assets=BTC,ETH,SOL,DOGE,XRP5Runs, DOGE has no data52
/v1/coins/BTC2Runs20
/v1/usage0Runs, free00

Page sizes

Each plan sets the most units one request may reserve. For searches the 5-unit 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 units run out

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 plan

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

PlanUnits / second (refill)Units / minuteUnits / monthMax units per request
Developer2201,00010
Starter56050,00025
Pro15300300,00050
Business409001,500,000100
EnterpriseBy contractBy contractBy contractBy contract

Headers on every response

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
HeaderMeaning
X-Decryptr-CostUnits this request was charged.
X-RateLimit-LimitUnits allowed per minute.
X-RateLimit-RemainingUnits left in this minute, after this request.
X-RateLimit-ResetSeconds until the minute window resets.
X-RateLimit-Burst-RemainingUnits left in the burst bucket.
X-Quota-LimitUnits allowed per calendar month (UTC).
X-Quota-RemainingUnits left this month, after this request.
RateLimit-Policy, RateLimitThe same limits in the IETF draft 11 format.
RateLimit-Limit, RateLimit-Remaining, RateLimit-ResetOlder draft names for the minute window.
Retry-AfterOn a 429: seconds to wait before trying again.

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

Handling 429

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.

CodeWhat to do
rate_limitedWait Retry-After seconds, then retry. If the request alone is bigger than your bucket, ask for a smaller limit.
quota_exceededNot enough units left this month. Ask for a smaller limit, wait for the reset, or upgrade. Retrying the same request will fail again.
too_many_auth_failuresToo many failed key checks from your client. Fix the key, then wait Retry-After seconds.
stream_limitYou already have your plan's number of open streams (2 on Pro, 10 on Business, shared by the signal and post streams). Close one, or reconnect after the server ends a connection.

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

get-with-backoff.mjs
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);
  }
}

On this page