CoinBeacon API

Parameters

None. Everything this endpoint returns is pinned server-side.

Status and edge cases

• A failed upstream returns 200 with null in the affected fields, never a 5xx.

Notes

• Cached 10 minutes server-side. Polling faster returns the same snapshot.
• avgFunding8hPct is the funding-index APR divided by 1095 (365 x 3), so the sampled -0.0006643 is -0.0006643 percent per 8 hours, not a fraction and not an APR.
• volumeChange24hPct and btcDominanceChange24hPct come from our own history series, not from CoinGecko, and are null unless a stored sample sits within 4 hours of the 24h-ago mark.
• Zero is never returned for a level: a source that reports 0 for market cap, volume or dominance is mapped to null. A change of exactly 0 percent is kept.
• fearGreed.updatedAt moves about once a day; the top-level updatedAt moves every 10 minutes.
• The rate limit is keyed per IP and per route, so this 120/min is not shared with the other market endpoints.

Status and edge cases

• hours never returns 400. Verified live: hours=abc fell back to 24 and hours=9999 clamped to 168.
• An empty or unreadable series returns 200 with points: [] and coveredHours: 0.

Notes

• Retention is 8 days but hours clamps at 168, so 7 days is the deepest readable window. hours=9999 returned 551 points and coveredHours 167.9.
• Spacing is not fixed. Do not compute a rate by assuming a constant interval between points.
• mcap, vol and btcDom are scrubbed to null on read when a stored level was non-positive. Plot nulls as gaps, not as zeros.
• A repeated ?hours=a&hours=b uses the first value. hours=1&hours=100 returned coveredHours 0.9.
• This route reads Redis directly and is not cached, unlike /public/market/globals.

Parameters

None. Everything this endpoint returns is pinned server-side.

Status and edge cases

• A segment with no indexed coins returns score null and count 0 rather than an error.

Notes

• Scores are unweighted means of per-coin trend scores in -100..+100. A large-cap and a microcap count the same.
• regime is mixed whenever any timeframe is positive and any other is negative, whatever the headline score. Otherwise bull above +5, bear below -5, neutral in between.
• perTf[].count falls on longer timeframes because fewer coins have enough history. Live: 444 coins at 15m against 280 at 1w for USDT.
• avgRsi pools the 15m, 1h, 4h, 1d and 1w RSI indexes into one mean, so it is not the mean of per-coin RSI and coins covered on more timeframes weigh more.
• avgRsi is null until the worker's RSI index has populated.
• Cached 60 seconds.

Parameters

None. Everything this endpoint returns is pinned server-side.

Status and edge cases

• altseason and stablecoins are independently nullable inside a 200; check for null before reading their fields.

Notes

• The basis set is pinned to BTCUSDT, ETHUSDT and SOLUSDT. There is no parameter to change it.
• Either basis leg older than 5 minutes yields null for that leg and a null basisPct, rather than a number computed off a dead quote.
• altseason excludes BTC itself and every coin tagged stablecoin, then takes the top 50 by rank.
• stablecoins counts only peggedUSD circulating supply, so EUR- and other-pegged coins are out of scope.
• change24hUsd and change7dUsd cover different windows (1 day and 7 days) and normally differ; only change7dUsd matches change7dPct.
• Cached 60 seconds; the stablecoin leg has its own 15-minute cache, so that block can be up to 15 minutes older than updatedAt.

Status and edge cases

• A symbol containing anything but letters, digits, underscore and hyphen, or shorter than 2 or longer than 24 characters, returns 400 "Invalid symbol".
• An unrecognised venue returns 400 with the accepted list.
• A repeated ?symbol=a&symbol=b returns 400 "Invalid symbol". Verified live.
• A well-formed but unknown symbol returns 200 with every metric null and history: []. Verified: symbol=ZZZZUSDT.
• When the venue cannot be asked (it is rate-limiting us, or our per-minute ceiling for its data is spent), the route returns 200 with the last good reading for that symbol from the past hour (check updatedAt), or every metric null if there is none.

Notes

• Pass the venue's contract symbol, not a base asset: BTC is not a valid symbol here.
• Each venue publishes a different subset, and a reading it does not publish is null: Bybit publishes the all-accounts share only (no top-trader or taker reading); HTX publishes its top traders' positions only, so globalLongPct, takerBuySellRatio and history stay null and []; Binance, OKX and Gate publish all three. OKX and Gate publish ratios, converted to shares here.
• OKX does not cover its USDC-margined swaps: those return every metric null.
• Case-insensitive: symbol=btcusdt returns the BTCUSDT response with symbol upper-cased.
• globalLongPct and topLongPct are percents in 0-100; the two *Ratio fields are raw ratios, not percents.
• The headline globalLongPct is the last element of history, so the two always agree.
• Each source degrades independently: a single upstream endpoint failing nulls one field and leaves the rest populated.
• A cache miss costs the venue one to three calls (three on Binance and OKX), and every distinct symbol is its own cache key per venue. Do not iterate symbols in a loop.

Status and edge cases

• Any currency other than BTC or ETH returns 400 "Invalid currency. Allowed: BTC, ETH". Verified: currency=SOL.
• If Deribit is unreachable the response is 200 with dvol, change24hPct, percentile30d, low30d and high30d all null and history: [].

Notes

• percentile30d is a rank, not a position in the low-high span: it answers how much of the last month was calmer than now.
• change24hPct uses the close 25 hourly candles back because the last candle is the in-progress hour.
• history is downsampled from roughly 720 hourly candles to about 60 points. Use it for shape, not for exact hourly values.
• Cached 10 minutes per currency, matching Deribit's hourly print cadence.
• dvol is annualised percent implied vol, not a daily move.

Parameters

None. Everything this endpoint returns is pinned server-side.

Status and edge cases

• A CoinGecko failure returns 200 with coins: [] rather than an error.

Notes

• Order is CoinGecko's trending order. Do not re-read it as a gainers ranking.
• Rows are base assets, not tradable pairs, and carry no venue. They will not all exist on our venues.
• Coins with an empty symbol are dropped, so fewer than 10 rows is normal.
• Cached 10 minutes.

Status and edge cases

• An unlisted exchange returns 400 with the 14 allowed values in the message. Verified: exchange=htx.
• A window not on the allowlist returns 400 with the 7 allowed values. Verified: window=10.
• A venue with no stored symbols returns 200 with empty gainers and losers, totalSymbols 0 and coverageMinutes 0.

Notes

• updatedAt is an ISO 8601 string on this route and on /public/market/movers/all. Every other endpoint in this group returns epoch ms as a number.
• Symbols with exactly 0 percent change are in neither list, but that does not shorten the response: each side is the top or bottom 20 of a ranking of hundreds, so 20 and 20 is normal. Live 20/20 at window=1, 15, 60 and 1440 on binance_futures, and at window=1440 on kraken_futures. Fewer rows come back only when the venue has under 20 symbols above (or below) 0 percent in the window.
• totalSymbols counts the whole ranked set (760 live on binance_futures); only the 40 rows come back.
• If coverageMinutes is below windowMinutes the percentages cover less time than you requested.
• window=1 reads a roughly 10-second tick series retained for 60 minutes; every longer window reads a one-sample-per-minute series.
• A symbol whose window holds one sample is scored 0 percent and therefore appears in neither list.
• Symbols are venue-native and not always ASCII. binance_futures currently lists a CJK-named perp (U+9F99 U+867E followed by USDT).
• Cached about 35 seconds per exchange and window combination.
• sparks=1 costs one request like any other call. The lines are sampled from the same one-sample-a-minute price history the percent change is read from, so they exist on every venue in the allowlist, including those with no candle data. Points per line: 30 on the 1 and 5 minute windows (a 30-minute line), 15 on 15, 30 on 30, and 48 on 60, 240 and 1440.
• A failed line read returns the rows without spark rather than failing the request, so check for the key rather than assuming it.

Status and edge cases

• An unlisted exchange or window returns 400 with the allowed values in the message.
• A venue with no stored symbols returns 200 with movers: [], totalSymbols 0 and returnedCount 0.

Notes

• The 250-row cap has no offset, cursor or page parameter. Rows past 250 cannot be read on this route, even though totalSymbols reports 761.
• Unlike /movers, this shape includes symbols with no movement: one in-window sample reports 0 percent, and a symbol with none is still listed at its last stored price with 0 percent.
• This route is 60/min, half the rest of the market group, and uses a separate market-heavy bucket.
• Rows never carry spark here. To draw a trend line on a page of these rows, send their symbols to /public/market/movers/sparks, at most 50 per call.
• A cold cache is slow: earlier measurement showed 4.79 s for exchange=binance&window=60, and one attempt returned no response before succeeding on retry.
• updatedAt is an ISO 8601 string here, not epoch ms.

Status and edge cases

• No symbols parameter, or an empty one, returns 400 "symbols is required (comma-separated)". A repeated symbols parameter is not an error: symbols=BTCUSDT&symbols=ETHUSDT returned both lines, like the comma form. Both verified live.
• More than 50 symbols returns 400 "At most 50 symbols per request". Verified with 51.
• A symbol containing whitespace, a control character or any of * ? [ ] \ returns 400 "Invalid symbol" and fails the whole request. Verified: BTC*USDT.
• An unlisted exchange or window returns 400 with the allowed values in the message. Verified: window=10.

Notes

• Membership is checked against the venue's own movers list, so an unknown, delisted or misspelled symbol simply has no key in sparks. Compare the keys you get back with the list you sent.
• The line and the percentage agree by construction: the last point is pinned to the row's currentPrice and, when spanMinutes equals windowMinutes, the first point to its oldestPrice.
• Points per line: 30 on the 1 and 5 minute windows, 15 on 15, 30 on 30, and 48 on 60, 240 and 1440. The history holds one sample a minute, so a line never has more points than its span has minutes.
• Symbols are venue-native and not always ASCII: binance_futures lists perps whose names are Chinese characters followed by USDT. Percent-encode the list.
• Venue keys here are the movers' underscore spellings (binance_futures), not the hyphenated ids of the board and candle routes.
• Lines are memoised per venue, window and market for about 35 seconds, the lifetime of the movers ranking they belong to. There is no updatedAt; the lines describe the same snapshot as /public/market/movers/all.

Status and edge cases

• A symbol under 2 characters, over 30, or containing anything but A-Z and 0-9 returns 400 "Malformed symbol".
• An unknown symbol returns 200 with prices: [], spreadPercent: null and exchangesWithPrice: 0, not a 404. Verified: /compare/NOTACOINXYZ and /compare/BT.
• Lowercase input is accepted and normalised: /compare/btcusdt returned the BTCUSDT comparison.

Notes

• symbol is a full pair, not a base asset. Comparing BTC rather than BTCUSDT returns an empty prices array.
• Aliases are canonicalised before the lookup, so the response symbol can differ from what you sent: /compare/XBTUSD returned symbol BTCUSD, meta.requestedSymbol XBTUSD and 18 rows. Match on meta.requestedSymbol if you need your own input back.
• Only prices 15 seconds old or newer enter spreadPercent. Prices between 15 and 60 seconds are still returned and counted in delayedShown. Older ones are dropped and counted in staleFiltered.
• A price is an outlier when it sits more than max(0.5 percent, 5 x the median absolute deviation) from the median of the comparable prices; both constants are deployment settings, so treat them as the defaults. The test needs at least 4 comparable venues. Below that nothing is flagged, meta.medianPrice is null and every medianDeviationPercent is null.
• A price is unchanged when its venue's one-a-minute price history shows the same value for at least 15 minutes while the median of the other venues' price ranges over that span is at least 0.2 percent, and at least 3 of that venue's own price steps. It needs 3 other venues with history. Durations are read from up to 30 samples, so a longer stand reads about 30 minutes. These constants are deployment settings; treat them as the defaults.
• meta.unavailable names every checked venue missing from prices[], so exchangesChecked equals prices.length plus unavailable.length (45 + 10 = 55 for BTCUSDT on 2026-09-30). A venue whose quote aged past maxAgeMs is listed there as too_old and is also counted in staleFiltered.
• sort (asc), maxAgeMs (60000), limit and offset are pinned server-side and cannot be set from the query.
• liveFetched is always 0 on this route: cachedOnly is pinned so an anonymous call can never trigger an outbound exchange fetch.
• The venue set here is the full ingest list (55 checked for BTCUSDT on 2026-09-30) and is not the same as the 14-venue movers allowlist.
• This route is 300/min on the market-heavy bucket: each call is one cached read per venue, never an exchange fetch.

Status and edge cases

• limit has no 4xx path: 0, -5, abc and 99999 all return 200 with the capped list.
• Over 120 requests per minute returns 429; the 429 body and Retry-After were not exercised.
• A browser fetch from a non-allowlisted Origin returns 500 {"statusCode":500,"message":"An unexpected error occurred","error":"Internal Server Error","timestamp":"2026-09-12T20:15:43.175Z","path":"/public/market-cap?limit=1"} instead of a CORS rejection. Verified live with Origin: https://example.com.

Notes

• count and meta.count are the total rows in the snapshot, not the rows returned: ?limit=5 returns count 664 with coins.length 5.
• Always pass limit. With no limit the response is the full 664-row snapshot, 645 KB on 2026-09-30.
• base is the join key; symbol is not unique. 664 distinct bases map to 652 distinct symbols.
• Twelve rows duplicate another row: each pair shares one cmcId and repeats marketCap and rank verbatim (price can differ, because the two rows can take it from different sources): SHIB/1000SHIB, PEPE/1000PEPE, LUNC/1000LUNC, BONK/1000BONK, FLOKI/1000FLOKI, XEC/1000XEC, CHEEMS/1000CHEEMS, MOG/1000000MOG, SATS/1000SATS, BEAM/BEAMX, RON/RONIN, LUNA/LUNA2. Deduplicate by cmcId before summing market cap or counting coins; filtering on a "1000" prefix still double counts BEAM, RON and LUNA. 1MBABYDOGE is an alias base key with no parent row, so it is not a duplicate.
• Five base keys are non-ASCII (Chinese-character meme tickers). They appear here but cannot be fetched from /public/market-cap/{symbol}.
• Percent-change fields are percent, not ratios. Money fields are USD.
• price is the only field with a live clock. On 2026-09-30, 639 of 664 rows had priceSource venue and 25 had cmc, among them the 1000-prefixed alias rows such as 1000SHIB and 1000PEPE. marketCap, volume24h and every percent change stay on the hourly CoinMarketCap poll, so on a venue-priced row price and percentChange24h come from different clocks.
• dateAdded and lastUpdated are ISO 8601 strings; meta.updatedAt is epoch ms.
• Three of the 664 rows carried rank null on 2026-09-30 (CROSS, STAMP, STANDARD), each with marketCap 0. Null-rank rows sort last.
• meta is nullable. With an unwritten or empty cache the route returns meta null, count 0 and coins [] at 200 (read from source; every live call returned a populated meta).
• The guarded route's search parameter is not exposed here. Unknown query params are ignored.
• Server-side only: a browser request carrying an Origin outside the site allowlist is rejected with 500, not a CORS error.
• The 120/min market-medium budget is counted per handler, not shared across the three market-cap routes. Measured in one 60s window, x-ratelimit-remaining-market-medium read 112 on /public/market-cap, 118 on /public/market-cap/narratives and 115 on /public/market-cap/BTC, each with its own reset.

Status and edge cases

• A symbol outside ^[A-Za-z0-9]{1,20}$ returns 400 {"statusCode":400,"message":"Invalid symbol","error":"Bad Request","timestamp":"2026-09-12T20:15:42.593Z","path":"/public/market-cap/BTC-USD"}. Verified on BTC-USD and on a non-ASCII base.
• An unknown but well-formed symbol returns 200 with found:false, entry null and info null, never 404. Verified on ZZZNOTACOIN.
• Over 120 requests per minute returns 429; the 429 body was not exercised.
• A browser fetch from a non-allowlisted Origin returns 500, not a CORS rejection.

Notes

• An unknown coin is 200 with found:false and entry/info null. Branch on found, never on the status code.
• The path segment is the base key from /public/market-cap, not the CMC ticker. 1000SHIB resolves and returns symbol SHIB; the five non-ASCII base keys in the list are unreachable here because of the charset guard.
• found:true does not imply info. A coin with no CoinMarketCap profile record returns a populated entry with info null; 1 of 664 coins was in that state on 2026-09-30 (CARDS).
• entry carries neither base nor logo: /public/market-cap adds both to its rows and this route returns the raw 27-field entry. Join back onto the list with the envelope's base, and read the image from info.logo.
• entry.lastUpdated is an ISO 8601 string while the envelope's updatedAt is epoch ms.
• narratives is routed ahead of this parameter, so /public/market-cap/narratives is always the sector board and can never be a coin lookup. Do not use it as a symbol example.
• Server-side only: a browser request carrying an Origin outside the site allowlist is rejected with 500, not a CORS error.

Parameters

None. Everything this endpoint returns is pinned server-side.

Status and edge cases

• No parameters and no 4xx path; every observed call returned 200.
• meta and updatedAt are typed nullable and would be null with an empty cache, leaving narratives empty at 200. Not observed live, so treat it as unverified rather than expected.
• Over 120 requests per minute returns 429; the 429 body was not exercised.
• A browser fetch from a non-allowlisted Origin returns 500, not a CORS rejection.

Notes

• coins[] is capped at 12 members per sector. Use coinCount for membership, never coins.length: the largest sector on 2026-09-30 had coinCount 200 with 12 rows.
• 54 allowlisted tags collapse to 45 labels, and tags that share a label form one sector. CoinMarketCap's "DEX" and "Decentralized Exchange (DEX) Token" tags are one DEX sector under tag decentralized-exchange-dex-token, and a coin carrying both counts once. Key by tag.
• Sectors with fewer than 3 qualifying members are dropped; coins with no tags or no 24h change are skipped entirely.
• A coin lands in every allowlisted sector its tags match, so sectors overlap and totalMarketCap double counts across the board.
• A coin listed under two exchange tickers (SHIB and 1000SHIB, RON and RONIN) is one CoinMarketCap entry and counts once in each sector, under CoinMarketCap's own symbol.
• The average is equal-weighted, not market-cap weighted.
• avgPct24h and medianPct24h are rounded to 2 decimals; the per-coin percentChange24h values are not rounded.
• Only curated tags are surfaced. Ecosystem tags (ethereum-ecosystem and similar) and portfolio tags are excluded by design, so this is not a full CMC tag dump.
• Takes no parameters: the 3-member floor and the 12-coin cap are fixed server-side.
• Server-side only: a browser request carrying an Origin outside the site allowlist is rejected with 500, not a CORS error.

Status and edge cases

• Unknown, mis-cased, empty or repeated exchange returns 400 {"statusCode":400,"message":"Unknown funding exchange","error":"Bad Request","timestamp":"2026-09-12T20:15:56.129Z","path":"/public/funding/all?exchange=nope"}. Every 4xx and 5xx in this group carries that same five-key envelope, with path echoing the request path and query string.
• A browser request from an origin outside the CORS allowlist returns 500, not a CORS error. Verified with Origin: https://example.com. Call this server-side.
• A venue with nothing cached returns 200 with rates: [] and totalSymbols: 0, not a 404 (read from source; not reproduced live).

Notes

• Rows are sorted by the NATIVE rate, which mixes 1h, 4h and 8h settlement. Re-sort on normalizedRate8hPercent before ranking.
• exchange is case-sensitive: exchange=BINANCE_FUTURES returns 400 while exchange=binance_futures returns 200.
• Sending the parameter twice returns 400: the handler receives an array, which is not on the allowlist.
• bitmex_futures was REMOVED from the allowlist on 2026-09-19: BitMEX shut down entirely on 2026-09-23 04:00 UTC. It had already thinned to 2 symbols (BTCUSDT, ETHUSDT) when measured 2026-09-12 while the other eight carried 341-981 (binance 863, bybit 765, okx 464, bitget 787, gateio 981, kucoin 677, huobi 341, bingx 968).
• Top-level updatedAt is an ISO 8601 string for the snapshot build; per-row updatedAt is epoch ms for ingestion. Do not treat them as the same clock.
• Responses come from a short server-side cache (35s default, env-tunable): three consecutive calls returned an identical updatedAt.
• No pagination and no limit parameter. binance_futures returned 245 KB.

Status and edge cases

• A base that is not 1–24 letters or digits after upper-casing returns 400 "Malformed base asset" (BTC-USD, a base with a space, or a 25-character base). Until 2026-10-01 the rule was /^[A-Z0-9]{1,15}$/, which rejected funded bases such as 币安人生 and 龙虾.
• 404 "No funding data for this coin" means no tracked venue funds the coin right now (a leg a venue lists but does not fund does not count). Until 2026-10-01 it also covered coins whose legs all read the same rate: DOGE, DOT and XMR returned 404 on 2026-09-30 at exactly 0.01% per 8h on every venue; those now return 200 with a zero spread.
• 503 "Funding data is temporarily unavailable" means the API holds no funding data at all: an outage, not an answer about the coin. Retry it; do not treat it as a 404.
• Both error bodies use the five-key envelope described on /public/funding/all: statusCode, message, error, timestamp, path.
• A browser request from an origin outside the CORS allowlist returns 500, not a CORS error. Call this server-side.

Notes

• spread.exchangeCount counts venue legs, not distinct exchanges. BTC returned 10 legs across 8 venues on 2026-09-30 because binance_futures and bingx_futures each list a USDT and a USDC perp.
• history covers ONE venue: the first of binance_futures, bybit_futures, okx_futures, bitget_futures, gateio_futures, kucoin_futures, huobi_futures, bingx_futures that lists the coin, and on it the USDT perp when it lists more than one. It is chosen by venue, never by rate, so it does not move between reads, and it is not a blend across venues.
• history.points are roughly hourly and capped at 30 days; BTC returned 743 points.
• A size-multiplier contract is filed under the coin it expresses: 1000PEPE under PEPE, 10000SATS under SATS, and Bybit's suffix form SHIB1000 under SHIB. Compare their rates 1:1, since funding is a percentage of the position, but never their prices: a 1000PEPE contract trades at about 1000 times PEPE.
• The merge is skipped when one venue lists two of the contracts side by side. binance_futures and bitget_futures list both CATUSDT and 1000CATUSDT, which are different coins sharing a ticker, so CAT and 1000CAT each return only their own legs.
• /public/funding/spread does not merge: 1000PEPE and PEPE are separate rows there, the way funding-spread alerts pair contracts, so a coin's spread here can differ from its row there.
• stats.d7 and stats.d30 are computed only from history.points, so they describe that one venue and are null when the window is empty.
• dataAt is epoch ms and is the timestamp of the LAST history point, not the freshness of venues[]; read ratesAt for that. dataAt is null when the history series is empty, which happens for a coin that is funded but has no cached series, and also when the Redis history read fails, so parse it as number|null.
• The response is cached per coin for 60s, and the set of funded legs behind it is re-read about every 35s.
• This 30-day series is the only funding history on the public surface. GET /public/funding/history is a 404 and is deliberately not exposed.

Parameters

None. Everything this endpoint returns is pinned server-side.

Status and edge cases

• A browser request from an origin outside the CORS allowlist returns 500, not a CORS error. Call this server-side.
• No 4xx input path exists: the endpoint takes no parameters.

Notes

• No parameters. The venue (binance_futures), both side limits (25) and the spread limit (12) are constants in the controller.
• Ranking uses normalizedRate8hPercent, unlike /public/funding/all which sorts on the native rate. The same data in the two endpoints will therefore be in a different order.
• aprPercent appears only on this endpoint; /public/funding/all does not carry it.
• negative[] is ordered most negative first.
• stale is always false. Judge freshness from dataAt instead.
• dataAt is epoch ms here, while /public/funding/all.updatedAt is an ISO 8601 string. The names are near-identical across this group; check the type before parsing.
• spreads[] carries the same phantom-leg risk as /public/funding/spread: 1 of the 12 rows measured on 2026-09-12 (CSOPSKHYNIX2L, a tokenized-equity perp) rested on a leg at exactly 0.

Parameters

None. Everything this endpoint returns is pinned server-side.

Status and edge cases

• A browser request from an origin outside the CORS allowlist returns 500, not a CORS error. Call this server-side.
• An empty window returns 200 with points: [] and current: null, not a 404 (read from source; not reproduced live).
• No 4xx input path exists: the endpoint takes no parameters.

Notes

• There are no parameters. The 1440-minute window is hardcoded and any query string is ignored; the authenticated twin of this route accepts a window, this one does not.
• Samples arrived every 15-16 minutes: 93 points covering 23.9 hours when measured 2026-09-12.
• medianAprPercent pins to 10.95 whenever most perps sit at the 0.01% per 8h baseline (0.01 x 3 x 365); it held that value for all 93 samples. Read avgAprPercent for movement in the tail.
• avgAprPercent swings through zero. Across those 93 samples it ranged -5.145 to +3.782 percent, with 47 of 93 negative, and current was -1.203. Do not assume a positive floor or chart it on a zero-based axis.
• current is literally points[points.length - 1], not a fresh computation, so it carries that point's timestamp.
• sampleCount moved between 5842 and 5902 across the window, so a shift in the index can be a change of constituents rather than repricing.
• Served from a short server-side cache (35s default, env-tunable).

Parameters

None. Everything this endpoint returns is pinned server-side.

Status and edge cases

• A browser request from an origin outside the CORS allowlist returns 500, not a CORS error. Call this server-side.
• No 4xx input path exists: the endpoint takes no parameters.
• Transport-level drops were seen on repeated large pulls from one client; retry once before treating a failure as an outage.

Notes

• About 600 KB per call (619,524 bytes measured), with no pagination and no limit parameter. Warm calls took 1.2-1.3 s; a cold cache has been measured at 8-10 s.
• Do not read spreadAprPercent as an arbitrage return. 153 of 542 rows carried a leg at exactly 0 - a book the venue lists but does not actually fund - and the gap on those rows is manufactured by that zero. Filter out rows where shortRate8hPercent or longRate8hPercent is exactly 0.
• A deny list of known frozen-zero legs already removes some of them, and it fails open: if that list is missing or expired, more zero legs reappear at the top of the ranking.
• Not every row is a cryptocurrency. Tokenized equity perps (CSOPSKHYNIX2L, SAMSUNG, SKHYNIX, TENCENTHKD, MRVL) rank high and mostly sit on a zero leg.
• baseAsset is derived by stripping a quote suffix (USDT, USDC, BUSD, FDUSD, EUR, USD, GBP, TRY, KRW, JPY, AUD, BRL, BTC, ETH, BNB) from the venue symbol, so BTCUSDT and BTCUSDC both fold into BTC and count as two legs.
• Rows whose gap is zero are dropped entirely, not returned with a 0: on 2026-09-30 DOGE was absent because all eight venues priced it at exactly the 0.01% per 8h baseline.
• The 2-venue-leg minimum is pinned in the controller and is not a query parameter.
• Legs settle on different intervals (1h, 4h, 8h). Only the normalizedRate8hPercent and the spread figures are comparable; ratePercent is per that venue's own interval. In a live pull of 541 rows, 0 were out of descending order on normalizedRate8hPercent while 58 were out of order on ratePercent.

Parameters

None. Everything this endpoint returns is pinned server-side.

Status and edge cases

• Never 404s. If the ingest is down the response is 200 with stale: true and empty arrays.
• market and largestPrint are null, not absent, when there is no data to summarise.

Notes

• largestPrint is the largest among the 200 prints currently held, not the largest of the day. Nothing stores a daily maximum.
• The $25,000 tape floor is a preference, not a filter: if fewer than 10 prints clear it the server falls back to the unfiltered tape. A live call returned a $15.65 print in tape[].
• Every dollar figure is USD. Coin-margined contracts (ETHUSD_PERP, BTCUSD_PERP), whose quantities are contract counts and which once took the top rows at 250-800x their real notional, have not been collected since 2026-10-04.
• baseAsset is a suffix strip, not a lookup. A contract whose name does not end in a quote currency keeps its full name, so a dated future such as BTCUSDT_251226 has baseAsset "BTCUSDT_251226". Do not key a coin lookup on it without handling that.
• This route costs 120 requests per minute, not the 300 the other liquidation routes allow, and the buckets are per route so the budgets do not pool.
• Check stale before rendering. A frozen snapshot otherwise looks identical to a live one.
• rekt rows are the same aggregate rows as /aggregates?window=24h, minus lastTs. totalSymbols is that endpoint's count.

Parameters

None. Everything this endpoint returns is pinned server-side.

Status and edge cases

• No 404 path. If the ingest feed is down the response is 200 with items: [] and count: 0.

Notes

• side "long" means long positions were liquidated (a forced sell), so price was falling. Binance's raw forceOrder side is the opposite of this and is already inverted for you.
• Venue is pinned to binance-futures here and is not a parameter. /public/liquidations/{symbol}/prints is the one liquidation route that takes a venue.
• Do not judge freshness from updatedAt: it is the server clock at the moment the 5s cache entry was built, so it is byte-identical across every call inside the TTL and can be 5s old. Four back-to-back calls returned 1789244215744. Compare items[0].ts to now instead.
• The payload is cached for 5 seconds, so polling faster than that returns the same rows.
• Binance throttles its liquidation stream to at most one event per symbol per second, so prints under-report during fast moves. Treat counts as observed, not complete.
• Only linear contracts appear: USD-M (BTCUSDT), USDC (BTCUSDC) and dated USDT futures. Coin-margined contracts (BTCUSD_PERP), whose qty is a contract count, have not been collected since 2026-10-04, so every notionalUsd is on one USD scale.
• Rows are in ingest-receive order, which is only approximately ts-descending. A 200-row sample held 7 adjacent pairs where the next row's ts was higher, by up to 851 ms. Sort by ts yourself if exact ordering matters.
• symbol is not guaranteed ASCII: a live tape carried a Binance meme pair whose base is CJK text. That symbol is unreachable from the /{symbol}/prints route, which strips every character outside A-Z, 0-9, underscore and hyphen.

Status and edge cases

• An unrecognised window silently falls back to 1h with a 200; there is no 400.
• No 404 path. A quiet market returns 200 with items: [] and count: 0.

Notes

• count is the pre-cap match total. At window=24h a live call returned count 416 with 100 rows; only read items.length for the rows you have.
• Omitting window gives 1h, not 24h. Send it explicitly if you want a different window.
• A symbol is excluded when its window total is under $1,000. That floor is fixed and ignoring it is not possible from the query string.
• market.updatedAt is the worker's last write; the top-level updatedAt is when this response body was generated. Use market.updatedAt for staleness.
• Every dollar figure is USD. Coin-margined contracts (ETHUSD_PERP, BTCUSD_PERP), which once reported contracts x price at 250-800x their real notional and took the top of this table, have not been collected since 2026-10-04.
• Cached server-side, 20 seconds by default (the TTL is a deployment setting, so treat 20s as the documented floor rather than a guarantee).

Parameters

None. Everything this endpoint returns is pinned server-side.

Status and edge cases

• Both arrays empty is a normal calm-market response, not a fault. A live call returned active: [] with 8 rows in recent[].

Notes

• recent[] rows carry three keys active[] rows do not: type, spottedAt and durationMs. Do not reuse one row type for both arrays. Every other key is shared: a live recent[0] held symbol, side, startedAt, lastEventAt, count, longUsd, shortUsd, totalUsd, baselineUsd, tier, windowUsd, windowCount, peakWindowUsd, thresholdUsd, q24, lastPrice, hotUntil, updatedAt.
• recent[] is pinned to 8 rows and contains only type "end". There is no way to ask for more.
• side "long" means longs were being liquidated, so price was falling.
• A row leaves active[] under either of two rules: untouched for 90 seconds (an orphan from a restarted ingest worker), OR now past hotUntil + 30 seconds regardless of how recently it was touched. The second fires more often. Either way active[] can shrink without an end event appearing in recent[].
• thresholdUsd is per-symbol, derived from q24, so a $10k cascade on a thin altcoin and a $10m one on BTC can both be tier 1. Compare totalUsd to baselineUsd, not across symbols.
• Cached for 5 seconds.

Status and edge cases

• An unrecognised venue returns 400 with the accepted list. HTX is htx-futures here; huobi-futures is rejected.
• An unknown symbol returns 200 with items: [] and count: 0, not a 404. A live call to /NOTACOIN/prints returned an empty result with symbol echoed as "NOTACOIN".
• A symbol containing stripped characters is silently rewritten: /btc.usdt/prints answered with symbol "BTCUSDT" and that symbol's 127 rows.
• A symbol that sanitises to nothing short-circuits: /%24%24%24/prints returned HTTP 200 {"symbol":"","items":[],"count":0,"windowMs":0,"updatedAt":...}: the one case where windowMs is not 86400000.

Notes

• Pass a contract symbol, not a base asset. BTCUSDT returned 127 rows in the same minute BTC returned 0.
• Rows here have no symbol key; the symbol is top-level. The /tape rows carry it per item. The two shapes are not interchangeable.
• items[] is oldest first. /tape is newest first.
• Only prints of $1,000 or more are included, and the window is always the last 24 hours. Neither is a parameter.
• At most the 4000 most recent prints are read from storage. If more than 2000 survive the $1,000 floor, the response keeps the largest by notional, not the most recent, then re-sorts by time.
• Case is folded for you: /btcusdt/prints and /BTCUSDT/prints returned the same 127 rows.
• The symbol must match the venue: /BTC-USDT-SWAP/prints?venue=okx-futures reads OKX's Bitcoin perpetual, while /BTCUSDT/prints?venue=okx-futures returns no rows.
• Only linear contracts are collected. Coin-margined ones (BTCUSD_PERP on binance-futures, inverse swaps elsewhere) and OKX's USDC swaps return an empty result, exactly like a quiet symbol.
• Cached for 8 seconds per symbol and venue.

Status and edge cases

• A symbol failing /^[A-Z0-9]{2,20}$/i returns 400 with a five-key body: {"statusCode":400,"message":"Invalid symbol","error":"Bad Request","timestamp":"2026-09-12T20:17:27.586Z","path":"/public/open-interest/BTC-USDT/history"}. timestamp is an ISO 8601 string and path echoes the request path. Verified with BTC-USDT and BTCUSD_PERP.
• A well-formed but unknown symbol returns 200 with points: [], not a 404. Verified with NOTAREALSYM.
• An unrecognised period silently falls back to 15m with a 200. Verified with period=3m.
• An upstream Binance failure also returns 200: with the last good history for that symbol and period if one was fetched in the past hour (check updatedAt), otherwise with points: []. That answer is cached for 15 seconds, so retry after that.

Notes

• points[].time is epoch seconds while updatedAt is epoch milliseconds. Mixing them is the easiest mistake here.
• The row limit is pinned to 500 and is not a parameter. Binance caps history at roughly 30 days, so the span you get depends on period: period=5m returned 500 points covering 41.6 hours, period=4h returned 186, period=1d returned 31.
• Coin-margined contracts are unreachable: BTCUSD_PERP fails the symbol regex with a 400 because of the underscore.
• Binance-futures only. There is no venue parameter and no other exchange behind this route.
• Responses are cached for 60 seconds per symbol and period, and concurrent cold requests collapse into one upstream call. Polling faster than 60s gains nothing.
• Read back the echoed symbol and period and check points.length before charting; bad input does not raise.

Parameters

None. Everything this endpoint returns is pinned server-side.

Status and edge cases

• No parameters are read, so unknown query strings are ignored and still return 200.
• A request from an Origin outside the configured allowlist returns 500 with {"statusCode":500,"message":"An unexpected error occurred"}, not 403.

Notes

• Read this before calling /public/screener. Any id not in this list is a 400.
• The list is a frozen server-side constant, not derived from live data. Cache it; it cannot change between deploys.
• No cache is applied to this handler, but the payload is static. Do not poll it.
• The filters and thresholds behind each preset are not exposed. Only id, label and description are returned.
• Server-to-server only. A browser fetch from a third-party origin returns 500, not a CORS error, because the API's CORS origin callback throws for unknown origins.

Status and edge cases

• Missing preset returns 400: "preset is required. Allowed: oversold-4h, deeply-oversold-4h, ...".
• An unknown preset returns 400: "Unknown preset \"nope\". Allowed: ...".
• A repeated ?preset=a&preset=b arrives comma-joined and returns 400 as an unknown preset, not a 200 for the first value.
• An empty result is a 200 with matched 0, count 0 and rows []. It is not an outage; near-ath has returned 0 rows.
• If the worker's board is missing the response is still 200 with universe 0, rows [] and meta.stale true, never a 500.
• A request from an Origin outside the configured allowlist returns 500, not 403.

Notes

• Call /public/screener/presets first. preset is required and the 15 ids are the only accepted values.
• limit and offset are ignored. Sending ?limit=3&offset=50 still returns meta.limit 100, meta.offset 0 and the full first page; verified live.
• Rows are capped at 100 with no pagination. When meta.matched exceeds 100 the tail is unreachable (deep-drawdown returned matched 244, count 100).
• The metric columns after marketCap differ per preset. Read the keys off rows[0] rather than assuming a fixed schema, skipping closedBar, which is a flag and not a column.
• Technical columns such as rsi@4h read the candle that is still forming, the one a chart draws, so they move within the candle. trendScore, sqs, trendline breaks, divergences, relative volume and the green-day streak read the last closed candle.
• A timeframe-scoped column is suffixed with its timeframe, e.g. "rsi@4h", "bbBandwidth@1d". A column whose preset names no timeframe falls back to 4h.
• Identity fields are always base, name, logo, rank, venue, symbol, quote, price, priceSource, marketCap. A preset column that repeats one of those is deduplicated, so some presets show 4 extra columns rather than 5.
• Responses are memoised in-process for 75 seconds per preset, on top of the worker's 60-second board rebuild. The payload therefore changes at most once per 75 seconds. Two polls less than a minute apart can still straddle a cache expiry and return different bytes, so polling faster than once per 75 seconds gains nothing.
• null means unknown, never zero. A coin with no perp has null funding and is dropped from a numeric filter rather than treated as 0.
• Stablecoins are excluded from every preset. Wrapped assets are included.
• marketCap can legitimately be 0 on very new listings; the futures presets set no market-cap floor.
• Server-to-server only. A browser fetch from a third-party origin returns 500, not a CORS error.