API Endpoints
Complete reference for all CLOBr API endpoints with request/response examples.
Table of Contents
Quick Reference
| Method | Endpoint | Description | Tier |
|---|---|---|---|
| GET | /score/:address | Get single token score | Premium |
| POST | /score | Batch query up to 50 tokens | Developer |
| GET | /top-scores | Top 50 tokens by CLOBr score | Premium |
| GET | /market-depth | Market depth data for a token | Premium |
| GET | /market-depth/bulk | Market depth for up to 20 crypto majors in one call | Premium |
| WS | /stream | Push market depth for crypto majors and tokens (1 credit per push) | Premium |
| GET | /dca-pressure | Top tokens ranked by DCA pressure | Premium |
| GET | /dca-orders | DCA orders with flow projections | Premium |
| GET | /limit-orders | Limit orders with price range filters | Premium |
| GET | /whale-activity | Whale accumulation & holder-flow for a token | Premium |
| POST | /whale-activity | Bulk whale summary for up to 10 tokens | Premium |
| GET | /dlmm/:address | DLMM pools for a single token | Premium |
| GET | /dlmm-pools | Hot DLMM Pools board for a time window | Premium |
| GET | /lp-cheat-sheet | Tokens ranked by LP fee density | Premium |
| GET | /odds | TP/SL odds for major perps (BTC, ETH, SOL, XRP, DOGE, BNB, LINK, BCH, TRX, ETC, ADA, SUI, LTC, XLM, AVAX, APT, ZEC, HBAR, POL, PEPE, AAVE, UNI and WLD) | Premium |
| GET | /replay/:address | Depth history: liquidity per market and price bin over time | Premium |
Premium: available on every paid API tier, Premium and Developer. Developer: Developer tier only.
Chains
CLOBr covers more than one chain. Every object that describes a token carries a chain field, and every endpoint accepts an optional chain parameter (a query parameter on GET, a body field on POST /score and POST /whale-activity).
chain keeps getting exactly the rows and fields it got before — list endpoints still default to Solana. The new chain fields are added alongside the existing ones; nothing was renamed, retyped or removed. See the API changelog for the full 1.1.0 entry.Chain keys
| Key | Chain | Address format |
|---|---|---|
solana | Solana | Base58 mint (32–44 chars) |
robinhood | Robinhood Chain | 0x + 40 hex contract address |
base | Base | 0x + 40 hex contract address |
ethereum | Ethereum | 0x + 40 hex contract address |
hyperevm | HyperEVM | 0x + 40 hex contract address |
all | Every chain the endpoint covers | — always accepted |
How chain behaves
List endpoints — /top-scores, /dca-pressure, /dlmm-pools, /lp-cheat-sheet. There is no address to read the chain off, so an absent chain means solana. That is deliberate: quietly mixing other chains into a list you already consume would be a breaking change in disguise. Opt in with chain=all or a specific key.
Address-keyed endpoints — /score/:address, POST /score, /market-depth, /dca-orders, /limit-orders, /whale-activity, /dlmm/:address. The two address spaces cannot collide (base58 vs 0x), so the address itself decides the chain and chain is never required. When you do send it, it names which chain the address is on: a value that contradicts the address — an EVM chain on a base58 mint, or solana on a 0x address — fails with chain_mismatch instead of quietly answering about something else. Anything else is a pin, not an error.
One score per asset. A token that trades on more than one chain has a single CLOBr score, computed from depth merged across every chain it trades on. /score and /top-scores report that one number — the same one the CLOBr web app shows — whichever of the asset's addresses you ask about. Each token object's chain tells you which chain the address is on, not which chain the score came from.
/limit-orders is the one exception: there chain on a Solana mint is also a real filter over the asset's cross-chain legs (chain=all merges them, chain=robinhood returns only that leg's orders).
all is always a valid value. On an endpoint that covers one chain it simply means that chain.
Chain errors (400)
invalid_chainThe value is not a chain key we know, and is not all.
{
"error": "Invalid chain",
"message": "Unknown chain 'sol'. Supported chains: solana, robinhood, base, ethereum, hyperevm (or 'all').",
"error_code": "invalid_chain",
"chain": "sol",
"supported_chains": ["solana", "robinhood", "base", "ethereum", "hyperevm"]
}chain_not_supportedA real chain that this endpoint does not cover — also what you get when you pass a 0x address to a Solana-only endpoint. supported_chains lists what the endpoint does cover.
{
"error": "Chain not supported",
"message": "/dca-orders covers: solana",
"error_code": "chain_not_supported",
"chain": "robinhood",
"supported_chains": ["solana"]
}chain_mismatchAn explicit chain that disagrees with the address you asked about. resolved_chain says which chain the address actually belongs to. On POST /score the body also carries mismatched_addresses with every offending address.
{
"error": "Chain mismatch",
"message": "Address 9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump is on solana, not robinhood.",
"error_code": "chain_mismatch",
"chain": "robinhood",
"resolved_chain": "solana",
"address": "9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump"
}Chain support by endpoint
| Endpoint | Chains | Absent chain means |
|---|---|---|
| GET /score/:address | solana, robinhood, base, ethereum, hyperevm | Derived from the address |
| POST /score | solana, robinhood, base, ethereum, hyperevm | Derived per address |
| GET /top-scores | solana, robinhood, base, ethereum, hyperevm | solana |
| GET /market-depth | solana, robinhood, base, ethereum, hyperevm, plus crypto majors by key (crypto:BTC) | Derived from the address |
| GET /limit-orders | solana, robinhood, base, ethereum, hyperevm | The address's own chain (a real filter here — see above) |
| GET /dca-pressure | solana | solana |
| GET /dca-orders | solana | Derived from the address |
| GET / POST /whale-activity | solana | Derived from the address |
| GET /dlmm/:address | solana | Derived from the address |
| GET /dlmm-pools | solana | solana |
| GET /lp-cheat-sheet | solana | solana |
| GET /replay/:address | solana, robinhood, base, ethereum, hyperevm, plus crypto majors by key (crypto:BTC) | Derived from the address |
An endpoint listed as Solana-only still accepts chain=solana and chain=all; any other real chain returns chain_not_supported. Coverage grows over time — this table is the current state, and the supported_chains array in a 400 body is always authoritative.
GET /score/:address
Get CLOBr score and price data for a single token. Tokens not yet analyzed will have null values with a status message.
Both address shapes are accepted: a base58 Solana mint or a 0x contract address on an EVM chain (robinhood, base, ethereum, hyperevm). The chain comes from the address, and the response says which one answered in chain. A 0x address that is a bridged leg of an asset with a Solana leg is answered as that Solana mint, with chain: "solana".
Parameters
| Name | Required | Description |
|---|---|---|
| address | Yes | Token address as a path segment: a base58 Solana mint or a 0x EVM contract address |
| chain | No | solana, robinhood, base, ethereum, hyperevm, all, or a numeric chain id. Derived from the address, so it only pins which EVM chain a 0x address is read on — a value that contradicts the address returns 400 chain_mismatch |
Example Request
curl -X GET "https://clobr.io/api/v1/score/9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump" \ -H "x-api-key: your_api_key_here"
Response Format
{
"address": "9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump",
"chain": "solana",
"symbol": "FARTCOIN",
"name": "Fartcoin",
"clobr_score": 53.1,
"score_msg": "Balanced: Similar levels of support and resistance",
"clobr_last_run": "2025-09-15T10:30:00Z",
"clobr_current_price": 0.69420,
"status": "available"
}This endpoint never returns 404. An address we have no row for comes back 200 with status: "pending", because logging the request queues the token for analysis. See the status table below.
POST /score Developer Only
Batch query CLOBr scores for up to 50 tokens at once. Returns sparse data - tokens not yet analyzed will have null values.
Base58 Solana mints and 0x EVM contract addresses can be mixed freely in one batch — each address's chain comes from its shape. The optional chain body field names the chain of every address in the batch; any address that contradicts it fails the whole request with 400 chain_mismatch, whose mismatched_addresses lists the offenders.
Example Request
curl -X POST "https://clobr.io/api/v1/score" \
-H "x-api-key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"addresses": [
"9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump",
"0x4a3b1c2d5e6f7089a1b2c3d4e5f60718293a4b5c"
]
}'chain is optional in the body. Omit it and every address is answered on its own chain.
Response Format
{
"count": 2,
"tokens": [
{
"address": "9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump",
"chain": "solana",
"symbol": "FARTCOIN",
"clobr_score": 53.1,
"status": "available"
},
{
"address": "0x4a3b1c2d5e6f7089a1b2c3d4e5f60718293a4b5c",
"chain": "robinhood",
"symbol": null,
"clobr_score": null,
"status": "pending"
}
]
}Status Values
| Status | Meaning |
|---|---|
available | Token analyzed, all data populated |
pending | New token, waiting for analysis (~15 seconds) |
unsupported | On Solana: token excluded from coverage (stablecoins, wrapped tokens) — terminal. On an EVM chain it means not indexed yet: there is no on-demand refresh queue there, so the answer can change as coverage grows, but don't poll for it. |
unscored | Depth-only coverage: market-depth data and price are available, but this token is never scored. clobr_score stays null. Terminal — do not poll for a score. |
price_unavailable | Token supported but no price data from Jupiter |
GET /top-scores
Returns the top 50 tokens ranked by CLOBr score. No parameters required: without chain the board is Solana only, exactly as before. Pass chain=robinhood for the Robinhood Chain board, or chain=all to merge every supported chain into one top 50 by score.
Parameters
| Name | Required | Description |
|---|---|---|
| chain | No | solana (default), robinhood, base, ethereum, hyperevm, or all |
Example Request
curl -X GET "https://clobr.io/api/v1/top-scores?chain=all" \ -H "x-api-key: your_api_key_here"
Response Format
{
"chain": "all",
"count": 50,
"tokens": [
{
"address": "...",
"chain": "solana",
"symbol": "FARTCOIN",
"clobr_score": 95.6,
"clobr_current_price": 0.69420,
"status": "available"
},
{
"address": "0x4a3b1c2d5e6f7089a1b2c3d4e5f60718293a4b5c",
"chain": "robinhood",
"symbol": "HOOD",
"clobr_score": 91.2,
"clobr_current_price": 1.24,
"status": "available"
},
...
]
}The top-level chain echoes the effective filter ("solana" when you sent nothing). Each token carries the chain it actually lives on.
GET /market-depth
Returns market depth data for a specific token.
Developer: Live data at 180 requests per rolling minute (10,000,000 calls per month), or a higher custom limit
How fresh the data is
Every live request (anything but delayed=true) counts as someone viewing the token, the same as an open token page.
- Crypto majors (
crypto:BTC): while you request a major at least once a minute, its depth within about 25% of the price is rebuilt from streaming order books about every 3 seconds. The rest of the range refreshes about once a minute. After more than a minute with no request, the first response can be the regular snapshot (up to about 3 minutes old). Requests a few seconds later are live again. - Tokens (Solana mints and
0xaddresses): a token you request is refreshed on the same schedule as a token a Premium user has open. last_refreshis the time of the data you got.
Parameters
| Name | Required | Description |
|---|---|---|
| token_address | Yes | Token address to query. Either shape: a base58 Solana mint or a 0x EVM contract address. A crypto major is addressed by its key, crypto:BTC (CEX books plus on-chain stable-quoted pools). A few on-chain tokens also have a crypto key alias, such as crypto:PUMP; see crypto key aliases. A tokenized stock or other real-world asset has an asset key, such as equity:ANT. |
| chain | No | solana, robinhood, base, ethereum, hyperevm, or all. Derived from token_address, so it's only an assertion — a value that disagrees returns 400 chain_mismatch. For a 0x address that is a token on two chains, an explicit EVM chain picks which chain's data answers (without it, the most recently scored chain does) |
| exchange_type | No | DEX (default), CEX, or ALL |
| currency | No | USD (default) or SOL |
| low_pct_change | No | Lower bound % change (-0.9 to 10.0) |
| high_pct_change | No | Upper bound % change (-0.9 to 10.0) |
| delayed | No | true for delayed data |
| include_summary | No | true to include aggregated support/resistance totals broken down by exchange_type and source, plus a total constant-product liquidity figure (default: false). Returned under a top-level summary object. |
| include_fine | No | Crypto majors (crypto:BTC) and tracked tokens such as LINK and PUMP. true adds fine 0.1% depth bins within 10% of the price (default: false). |
| market_types | No | Crypto keys only (majors and aliases). Comma-separated liquidity types to keep: spot (CEX spot books), perp (CEX perpetual and futures books), onchain (on-chain pools). Case and spaces do not matter. Leave it off, or send all three, for every type. Works together with exchange_type (spot and perp are CEX, onchain is DEX). leveraged is not accepted because leveraged tokens add no depth. An empty or unknown value returns 400, and so does sending it with a token address. |
Example Request
curl -X GET "https://clobr.io/api/v1/market-depth?token_address=9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump&delayed=true&include_summary=true" \ -H "x-api-key: your_api_key_here"
Response Format
{
"query_parameters": {
"token_address": "...",
"exchange_type": "DEX",
"currency": "USD",
"delayed": true,
"include_summary": true,
"chain": "solana"
},
"chain": "solana",
"last_refresh": 1747593235,
"clobr_score": 53.1,
"score_msg": "Balanced: Similar levels of support and resistance",
"price": 0.00151,
"ui_amount_multiplier": 1,
"depth_data": [
{
"price": 0.00164,
"support": 0,
"resistance": 5553.40,
"constant_product": 945.11
},
...
],
"summary": {
"by_exchange_type": [
{ "exchange_type": "DEX", "support": 38000.00, "resistance": 40000.00 }
],
"by_source": [
{ "source": "Orca Whirlpool", "support": 20000.00, "resistance": 25000.00 },
{ "source": "Meteora DLMM", "support": 18000.00, "resistance": 15000.00 }
],
"constant_product": 3186681.11
}
}Each depth_data row is a 1% price band, and its price is the bottom of that band. The row priced p holds the liquidity priced from p up to, but not including, p × 1.01. Draw it from p to p × 1.01, not centred on p.
ui_amount_multiplier matters for a few Solana tokens with a display multiplier, such as PreStocks and xStocks. price and depth_data are per token as a wallet shows it. If your chart prices the raw unit, multiply every price by ui_amount_multiplier. It is 1 for every other token.
chain is the chain the token address resolved to (solana for a base58 mint, an EVM chain key such as robinhood or base for a 0x contract address). It is always present, at the top level and inside query_parameters. For a major's crypto:<SYMBOL> key it is null, because a major trades on exchanges and on several chains at once; the response adds asset_key instead, and clobr_score and score_msg are null.
The summary object is only returned when include_summary=true. Aggregations honor the same token_address, percentage range, exchange_type filter, and currency conversion as depth_data. by_exchange_type and by_source cover concentrated liquidity (CLMM/DLMM/limit orders); constant-product AMM liquidity is reported separately under constant_product.
On a crypto:<SYMBOL> key the summary also has breakdown_grain. When your range sits inside 10% of the price (low_pct_change of -0.10 or more, high_pct_change of 0.10 or less) and the latest 0.1% data covers all of it, it is fine_10bp: by_exchange_type and by_source are summed from 0.1% bins, and a bin on the edge of your range counts only for the part inside it. breakdown_as_of is the time of that data (it refreshes every 5 seconds). Otherwise the breakdowns use 1% rungs: rung_1pct, with breakdown_as_of null.
With delayed=true, you get the newest snapshot that is at least 1 hour old. If that snapshot is more than 6 hours old, CLOBr does not serve it: depth_data is empty and the response adds reason (delayed_snapshot_too_old), snapshot_as_of (the time of the withheld snapshot) and max_age_hours (6). The status is still 200. Ask with delayed=false on a Premium key for live depth. If no snapshot is at least 1 hour old yet but a live one exists, you get the same empty answer with reason no_delayed_snapshot, and snapshot_as_of is the time of the live snapshot.
With include_fine=true on a crypto:<SYMBOL> key, the response adds three fields. fine_depth_data lists 0.1% bins, ascending by price, inside 10% of the price and your percentage range. Each row has the same fields and currency as depth_data plus step, the bin height as a fraction of its price (about 0.000995). fine_source is live, bins_fine or none (no fine data right now; the array is empty). fine_as_of is the ISO time of the fine data, or null. The 1% depth_data is always returned too.
include_fine=true also works with a token address. CLOBr tracks fine bins for a growing set of tokens (LINK and PUMP first, then tokens with enough daily exchange volume). A token address gets the same three fields plus fine_key (asset:<id>, or null) and fine_reason. When the token is not tracked, fine_reason is not_tracked and fine_depth_data is empty. exchange_type still applies: the default DEX keeps on-chain fine rows only, so send ALL or CEX to include exchange order books.
"fine_depth_data": [
{
"price": 107210.55,
"support": 1843210.12,
"resistance": 0,
"constant_product": 0,
"step": 0.000995
},
...
],
"fine_source": "live",
"fine_as_of": "2026-10-19T16:02:11.000Z"With market_types on a crypto:<SYMBOL> key, depth_data, fine_depth_data and summary hold only the types you picked, and query_parameters.market_types lists them in the order spot, perp, onchain. price stays the major's price. A type with no liquidity (for example perps on a major no exchange lists perps for) returns 200 with an empty depth_data.
curl "https://clobr.io/api/v1/market-depth?token_address=crypto:BTC&market_types=spot,perp&include_fine=true" \ -H "x-api-key: your_api_key_here"
Crypto key aliases
Some tokens trade like majors but live on chain, so they keep their token address. A crypto key alias lets you call them by key anyway: crypto:PUMP (PUMP on Solana) and crypto:LINK (Chainlink, native on Ethereum). Each alias points at one token. We add aliases by hand after review, never by matching a symbol, so a key you have not seen here returns 404 rather than another token's data.
- The response is the token's own depth, across every chain it trades on plus its exchange books, with the crypto key rules:
exchange_typedefaults toALL, andmarket_typesandinclude_finework. - It adds
asset_keyand aresolvedblock naming the token. Checkresolved.contract_addressonce before you trade on it. - With
market_types, an exchange market that stores spot and perp books as one row (for exampleOKX-USDT) is left out of spot and perp and listed inunsplit_markets, so a type is never guessed. - If the token loses its 0.1% bins, the key still works:
depth_datakeeps the 1% grid andfine_reasonsaysnot_tracked. - Aliases also work in
/market-depth/bulk, the push stream and/replay. A major always keeps its own key.
curl "https://clobr.io/api/v1/market-depth?token_address=crypto:PUMP&market_types=perp&include_fine=true" \
-H "x-api-key: your_api_key_here"
{
"query_parameters": { "token_address": "crypto:PUMP", "exchange_type": "ALL", "market_types": ["perp"], ... },
"chain": null,
"asset_key": "crypto:PUMP",
"resolved": {
"asset_id": 113569,
"chain": "solana",
"chain_id": 101,
"contract_address": "pumpCmXqMfrsAkQ5r49WcJnRayYRqmXz6ae8H7H9Dfn",
"name": "Pump",
"symbol": "PUMP"
},
"depth_data": [ ... ],
"fine_depth_data": [ ... ],
"fine_key": "asset:113569",
"fine_reason": null,
"unsplit_markets": ["OKX-USDT"]
}Asset keys for tokenized stocks and other real-world assets
A tokenized stock trades as several tokens on several chains, plus perpetual contracts on exchanges. An asset key asks for all of it at once: equity:ANT returns Anthropic's depth across its Solana pools, its Robinhood Chain and Base pools, and the exchange books we track for it.
- The key is
<kind>:<SYMBOL>, where kind isequity,commodityorpreipo. Case does not matter. - Like an alias, each key is added by hand after review. A key you have not seen here returns 404, never a different asset's data.
- It works like a crypto key alias: the same parameters and rules, plus
asset_keyand aresolvedblock naming the token that answered. It also works in/market-depth/bulk, the push stream and/replay.
curl "https://clobr.io/api/v1/market-depth?token_address=equity:ANT&include_summary=true" \
-H "x-api-key: your_api_key_here"
{
"query_parameters": { "token_address": "equity:ANT", "exchange_type": "ALL", ... },
"chain": null,
"asset_key": "equity:ANT",
"resolved": {
"asset_id": 285265,
"chain": "solana",
"chain_id": 101,
"contract_address": "ANTBTZQ1EUuTxUs3tfeampxdqTWPHmwyJmcWj4xoAyNe",
"name": "Anthropic",
"symbol": "ANT"
},
"depth_data": [ ... ],
"summary": { ... }
}GET /market-depth/bulk
Market depth for up to 20 crypto majors in one call. Polling nine majors across spot, perp and on-chain takes 3 calls a minute instead of 27.
Developer: 30 requests per rolling minute (a custom limit does not change it)
One call counts as one request toward the rate limit and bills one call per token returned in
results.Each token in a live call counts as a viewer, so a major you poll at least once a minute stays on the 3 second ladder, exactly as with GET /market-depth.
Parameters
tokens is required: 1 to 20 comma-separated crypto:<SYMBOL> keys (majors or aliases) or asset keys such as equity:ANT. Anything else returns 400. Every other parameter works as on GET /market-depth (market_types, exchange_type, include_summary, include_fine, low_pct_change, high_pct_change, currency, delayed) and applies to every token.
Example
curl -X GET "https://clobr.io/api/v1/market-depth/bulk?tokens=crypto:BTC,crypto:ETH,crypto:SOL&market_types=spot&include_summary=true&include_fine=true" \ -H "x-api-key: YOUR_API_KEY"
Response
{
"results": {
"crypto:BTC": { /* exactly what GET /market-depth returns for crypto:BTC */ },
"crypto:ETH": { ... }
},
"errors": {
"crypto:XYZ": { "status": 404, "error": "Token not found", "message": "No crypto asset has this key" }
}
}A token that fails does not fail the others. The call returns 200 with that token under errors, carrying the status and error the single call would have returned. Entries share the single call's 3-second cache.
Stream market depth (WebSocket)
A push feed for crypto majors and on-chain tokens. The server sends the exact GET /market-depth body for a key each time CLOBr refreshes it: about every 3 seconds for a major, and every 5 to 10 seconds for a token someone is watching. Updates for one key arrive at most once per second. Every message is a full body, not a diff.
wss://clobr.io/api/v1/streamAccess: Premium and Developer
Keys:
crypto:<SYMBOL> keys on CLOBr's majors roster or alias list, a Solana mint, or a 0x token address: the same token_address values GET /market-depth accepts, with the same params.Signal only: subscribe with
"params":{"signal":true} to get a small {"type":"update","key":"...","seq":2,"data_ts_ms":...} message instead of the body, then fetch only what you need.Authentication
Never put your key in the URL. Use one of two ways:
- Send an
x-api-key: YOUR_API_KEYheader on the WebSocket upgrade request. Use this from bots and servers. - Send
{"op":"auth","api_key":"YOUR_API_KEY"}as the first message, within 5 seconds. Use this in browsers, which cannot set headers on a WebSocket.
The server replies with:
{"type":"ready","tier":"premium","limits":{"connections":2,"assets":5}}tier is premium or developer.
Messages
| Direction | Message | Meaning |
|---|---|---|
| Client | {"op":"auth","api_key":"..."} | First-message auth (see above). |
| Client | {"op":"subscribe","keys":[...],"params":{...}} | Start receiving depth for the keys. Replies subscribed, then one depth message per key right away. |
| Client | {"op":"unsubscribe","keys":[...]} | Stop receiving the keys. Replies unsubscribed. |
| Client | {"op":"ping"} | Replies {"type":"pong"}. Useful where you cannot see WebSocket pings, such as browser extensions. |
| Server | ready | Auth accepted. Carries your tier and limits. |
| Server | subscribed / unsubscribed | Confirms the keys now active or removed. |
| Server | depth | A full market-depth body for one key. |
| Server | error | {"type":"error","code":"...","message":"..."}. The connection stays open unless a close follows. |
| Server | bye | Planned restart. Reconnect after reconnect_ms and subscribe again. |
The server also sends a WebSocket ping every 20 seconds. Most libraries answer it automatically.
Subscribe
{
"op": "subscribe",
"keys": ["crypto:BTC", "crypto:ETH"],
"params": {
"market_types": "perp",
"exchange_type": "ALL",
"include_fine": true,
"include_summary": true,
"currency": "USD",
"low_pct_change": -0.25,
"high_pct_change": 0.25
}
}params uses the same names, defaults and validation as the GET /market-depth query string. The token comes from keys. Allowed names:
exchange_type,currency,value_type,chainlow_pct_change,high_pct_changeinclude_summary,include_finemarket_types: a string like"spot,perp"or an array like["spot","perp"]delayed: onlyfalse, because the stream is live data
Unknown names are rejected. All keys in one subscribe share the same params. Subscribing again to a key you already have replaces its params. The server replies:
{"type":"subscribed","keys":["crypto:BTC","crypto:ETH"]}To stop, send {"op":"unsubscribe","keys":["crypto:BTC"]}. The reply is {"type":"unsubscribed","keys":["crypto:BTC"]}.
Depth message
{
"type": "depth",
"key": "crypto:BTC",
"seq": 812,
"sent_ms": 1761180000123,
"data_ts_ms": 1761179998456,
"data": {
"query_parameters": { "token_address": "crypto:BTC", "market_types": ["perp"], ... },
"chain": null,
"asset_key": "crypto:BTC",
"last_refresh": 1761179998,
"price": 108412.5,
"depth_data": [ ... ],
"fine_depth_data": [ ... ],
"summary": { ... }
}
}| Field | Meaning |
|---|---|
| key | The canonical key. It matches data.query_parameters.token_address. |
| seq | Counts per connection and key, +1 per message, starting at 1. If your client falls more than a few MB behind on reads, the server skips updates for it (no seq is used) until it catches up. Each message is a full body, so nothing needs repair. |
| data_ts_ms | When CLOBr computed the data (Unix ms). |
| sent_ms | When the server sent the message (Unix ms). |
| data | The exact GET /market-depth body for the key. |
Errors
| Code | Meaning |
|---|---|
| bad_request | Malformed message, unknown param name or invalid value. |
| not_allowed | The key or option is not available to you. |
| limit | You are over the assets-per-connection limit. |
| rate_limited | Too many subscribe or unsubscribe messages. |
| unavailable | That key's body could not be built right now. The message carries a key. The subscription stays, and the next update retries. |
Close codes
| Code | Meaning |
|---|---|
| 4401 | Missing or invalid API key. |
| 4402 | Subscription lapsed or monthly quota used up. CLOBr re-checks every 5 minutes. |
| 4408 | No auth within 5 seconds. |
| 4429 | Too many connections. |
| 1012 | Planned restart. The server first sends {"type":"bye","reconnect_ms":2500}. Reconnect after reconnect_ms and subscribe again. |
Limits
| Limit | Premium | Developer |
|---|---|---|
| Connections per account | 2 | 5 |
| Assets per connection | 5 | 20 |
| Subscribe / unsubscribe messages | 5 per 10 seconds per connection | |
Billing and live lane
Each pushed depth message costs 1 credit per API key, the same as one GET /market-depth call. Usage is recorded once per minute per key under the endpoint /api/v1/stream. One asset updating about every 3 seconds is about 20 credits per minute.
A subscription counts as an active viewer, so the asset stays on CLOBr's 3 second live lane while you are subscribed.
Client behavior we recommend
- Reconnect with exponential backoff.
- Subscribe again after every reconnect.
- Treat each message as a full replacement of the last one for that key.
Example: Node (ws)
import WebSocket from "ws";
const KEYS = ["crypto:BTC", "crypto:ETH"];
let delay = 1000;
function connect() {
const ws = new WebSocket("wss://clobr.io/api/v1/stream", {
headers: { "x-api-key": process.env.CLOBR_API_KEY },
});
ws.on("message", (raw) => {
const msg = JSON.parse(raw.toString());
if (msg.type === "ready") {
delay = 1000;
ws.send(JSON.stringify({
op: "subscribe",
keys: KEYS,
params: { market_types: "perp", include_summary: true },
}));
} else if (msg.type === "depth") {
console.log(msg.key, msg.seq, msg.data_ts_ms);
} else if (msg.type === "bye") {
delay = msg.reconnect_ms;
} else if (msg.type === "error") {
console.error(msg.code, msg.message);
}
});
ws.on("close", (code) => {
if (code === 4401 || code === 4402) return; // fix the key or plan first
setTimeout(connect, delay);
delay = Math.min(delay * 2, 30000);
});
ws.on("error", () => {});
}
connect();Example: browser
Browsers cannot set headers, so authenticate with the first message. Do not ship a key you cannot rotate in public page code. Call the stream from your own backend or an extension where you can keep it private.
const KEYS = ["crypto:BTC"];
let delay = 1000;
function connect(apiKey) {
const ws = new WebSocket("wss://clobr.io/api/v1/stream");
ws.onopen = () => {
ws.send(JSON.stringify({ op: "auth", api_key: apiKey }));
};
ws.onmessage = (event) => {
const msg = JSON.parse(event.data);
if (msg.type === "ready") {
delay = 1000;
ws.send(JSON.stringify({ op: "subscribe", keys: KEYS }));
} else if (msg.type === "depth") {
render(msg.key, msg.data); // full replacement each time
}
};
ws.onclose = (event) => {
if (event.code === 4401 || event.code === 4402) return;
setTimeout(() => connect(apiKey), delay);
delay = Math.min(delay * 2, 30000);
};
}GET /dca-pressure
Returns the top tokens ranked by aggregate DCA (Dollar Cost Average) pressure. Includes net buy/sell totals and impact projections across multiple timeframes (5min to 24hr). Optionally includes nested individual orders per token.
Parameters
| Name | Required | Description |
|---|---|---|
| chain | No | solana (default) or all. DCA data is Solana-only, so all is equivalent to solana; any other chain returns 400 chain_not_supported |
| sort_by | No | usd (default) or impact (percentage) |
| sort_dir | No | desc (default, buy pressure first) or asc (sell pressure first) |
| sort_timeframe | No | 5_min, 30_min, 1_hr, 6_hr, 24_hr (default) |
| include_orders | No | true to include nested individual orders per token (default: false) |
| order_limit | No | Max orders per token when include_orders=true (default 5, max 20) |
| limit | No | Number of tokens to return (default 20, max 50) |
| min_mcap / max_mcap | No | Market cap filter range (USD) |
| min_liquidity / max_liquidity | No | Support Liquidity filter range (USD): CLOBr's buy-support depth within ±25% of the current price (the in-range share of constant-product / 50-50 pool liquidity plus concentrated buy-side / paired-token liquidity in those price rungs), not total or sell-side liquidity |
Example Request
curl -X GET "https://clobr.io/api/v1/dca-pressure?sort_by=impact&sort_timeframe=1_hr&limit=10" \ -H "x-api-key: your_api_key_here"
Response Format
{
"query_parameters": {
"sort_by": "impact",
"sort_timeframe": "1_hr",
"include_orders": false,
"limit": 10,
"chain": "solana"
},
"count": 10,
"tokens": [
{
"token": {
"address": "98sMhvDwXj1RQi5c5Mndm3vPe9cBqPrbLaufMXFNMh5g",
"chain": "solana",
"symbol": "HYPE",
"name": "HYPE",
"icon": "https://...",
"mcap": 5250000000,
"liquidity_usd": 525000,
"price_usd": 0.001
},
"buy_order_count": 5,
"sell_order_count": 0,
"total_buy_usd": 371518.97,
"total_sell_usd": 0,
"net_usd": 371518.97,
"impact": {
"net_usd_5_min": 100.50,
"net_usd_30_min": 500.25,
"net_usd_1_hr": 1200.00,
"net_usd_6_hr": 8000.00,
"net_usd_24_hr": 369369.07,
"net_pct_5_min": 0.02,
"net_pct_30_min": 0.08,
"net_pct_1_hr": 0.15,
"net_pct_6_hr": 0.90,
"net_pct_24_hr": 0.07
},
"orders": []
}
]
}GET /dca-orders
Returns top DCA (Dollar Cost Average) orders for a token, sorted by percentage impact or USD flow. Includes active order details with time-based flow projections. Ideal for identifying large DCA buy/sell pressure to feed trading bots and terminals.
Parameters
| Name | Required | Description |
|---|---|---|
| token_address | Yes | Token mint address (base58). A 0x address returns 400 chain_not_supported — DCA data is Solana-only |
| chain | No | solana or all. Derived from the address, so it's only an assertion — a value that disagrees returns 400 chain_mismatch |
| sort_by | No | pct_impact (default) or usd_flow |
| min_mcap / max_mcap | No | Market cap filter range (USD) |
| min_liquidity / max_liquidity | No | Support Liquidity filter range (USD): CLOBr's buy-support depth within ±25% of the current price (the in-range share of constant-product / 50-50 pool liquidity plus concentrated buy-side / paired-token liquidity in those price rungs), not total or sell-side liquidity |
| limit | No | Max orders to return (default 20, max 50) |
Example Request
curl -X GET "https://clobr.io/api/v1/dca-orders?token_address=9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump&sort_by=usd_flow&limit=10" \ -H "x-api-key: your_api_key_here"
Response Format
{
"query_parameters": {
"token_address": "9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump",
"sort_by": "usd_flow",
"limit": 10,
"chain": "solana"
},
"token": {
"address": "9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump",
"chain": "solana",
"symbol": "FARTCOIN",
"name": "Fartcoin",
"mcap": 850000000,
"liquidity_usd": 12500000,
"clobr_score": 53.1,
"price_usd": 0.69420,
"last_refresh": 1747593235
},
"count": 10,
"orders": [
{
"dca_address": "...",
"chain": "solana",
"direction": "BUY",
"symbol": "FARTCOIN",
"paired_symbol": "SOL",
"deposited_usd": 5000,
"remaining_usd": 3200,
"pct_filled": 0.36,
"in_active_range": true,
"cycle_frequency": 3600,
"price_range": {
"min_usd": 0.50,
"max_usd": 1.00,
"current_price_usd": 0.694
},
"flow_projections": {
"usd_next_5_min": 12.50,
"usd_next_30_min": 75.00,
"usd_next_1_hr": 150.00,
"usd_next_6_hr": 900.00,
"usd_next_24_hr": 3200.00
}
}
]
}GET /limit-orders
Returns active limit orders for a token within a specified percentage range of current price. Default range is -90% to +1000%. Includes orders from both Jupiter and Fusion platforms. Use the optional pct range parameters to narrow results.
This is the one endpoint where chain is a real filter rather than only an assertion. For a base58 Solana mint, leaving it off returns exactly the Solana orders it always did; chain=all merges in the orders on that asset's other chain legs, and chain=robinhood returns only that leg's orders. A 0x contract address is answered from that chain directly. The percentage range, the limit and the sort all apply to the merged list, and every order carries its own chain.
Parameters
| Name | Required | Description |
|---|---|---|
| token_address | Yes | Token address. Either shape: a base58 Solana mint or a 0x EVM contract address |
| chain | No | solana, robinhood, base, ethereum, hyperevm, or all. Absent means the address's own chain (Solana orders only for a base58 mint); all merges every leg of the asset |
| low_pct_change | No | Lower bound % change (-0.99 to 10.0, default -0.9) |
| high_pct_change | No | Upper bound % change (-0.99 to 10.0, default 10.0) |
| limit | No | Max orders to return (default 100, max 500) |
Example Request
curl -X GET "https://clobr.io/api/v1/limit-orders?token_address=9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump&low_pct_change=-0.5&high_pct_change=2.0&chain=all" \ -H "x-api-key: your_api_key_here"
Response Format
{
"query_parameters": {
"token_address": "9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump",
"low_pct_change": -0.5,
"high_pct_change": 2.0,
"limit": 100,
"chain": "all"
},
"token": {
"address": "9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump",
"chain": "solana",
"symbol": "FARTCOIN",
"name": "Fartcoin",
"mcap": 850000000,
"liquidity_usd": 12500000,
"clobr_score": 53.1,
"price_usd": 0.69420,
"last_refresh": 1747593235
},
"count": 42,
"orders": [
{
"order_address": "...",
"chain": "solana",
"direction": "BUY",
"platform": "jupiter",
"symbol": "FARTCOIN",
"paired_symbol": "SOL",
"maker": "...",
"usd_price": 0.55,
"current_price_usd": 0.694,
"pct_away": -0.21,
"usd_support_amount": 2500.00,
"usd_resistance_amount": 0,
"pct_complete": 15.5,
"created_at": 1747500000
}
]
}query_parameters.chain echoes the filter that was applied (all here). token.chain is the chain the queried address lives on, and each order's chain is the leg that order sits on — with chain=all a single response can mix them.
GET /whale-activity
Returns the Whale Accumulation panel data for a single Solana token by contract address. Includes accumulating wallets, brand-new wallets and net flow bucketed by holder tier (top 20 / 50 / 100) over 1D / 7D / 30D windows, a 30-day daily sparkline per tier, and (optionally) the top-holder table with per-wallet 1D/7D/14D/30D balance change and an optional 30-day activity trend.
Rate limit: 1 request per second (cache responses ~60s, snapshot data refreshes roughly each minute)
Parameters
| Name | Required | Description |
|---|---|---|
| token_address | Yes | Solana token mint address (base58). A 0x address returns 400 chain_not_supported |
| chain | No | solana or all. Derived from the address, so it's only an assertion — a value that disagrees returns 400 chain_mismatch |
| include | No | Comma-separated sections: summary, sparkline, wallets (default: all three) |
| wallet_limit | No | Top holders to return: 20, 50, or 100 (default 100) |
| wallet_activity | No | true to attach a 30-day daily activity trend per wallet (heavier payload, default false) |
Example Request
curl -X GET "https://clobr.io/api/v1/whale-activity?token_address=9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump&include=summary,sparkline,wallets&wallet_limit=50" \ -H "x-api-key: your_api_key_here"
Response Format
{
"token_address": "9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump",
"chain": "solana",
"has_coverage": true,
"last_snapshot_at": "2025-09-15T10:30:00Z",
"windows": ["1d", "7d", "30d"],
"tiers": ["top20", "top50", "top100"],
"summary": {
"accumulating": {
"top20": { "1d": 4, "7d": 9, "30d": 12 },
"top50": { "1d": 8, "7d": 21, "30d": 31 },
"top100": { "1d": 13, "7d": 38, "30d": 57 }
},
"new_wallets": {
"top20": { "1d": 1, "7d": 2, "30d": 3 },
"top50": { "1d": 2, "7d": 5, "30d": 9 },
"top100": { "1d": 3, "7d": 8, "30d": 15 }
},
"net_flow": {
"top20": { "1d": { "net": 1250000, "inflow": 1400000, "outflow": -150000 }, "7d": { "...": "..." }, "30d": { "...": "..." } },
"top50": { "...": "..." },
"top100": { "...": "..." }
}
},
"sparkline": {
"top20": [
{ "day": "2025-08-17", "accumulating": 2, "new_wallets": 0, "net": 320000, "inflow": 400000, "outflow": -80000 }
],
"top50": [ "..." ],
"top100": [ "..." ]
},
"wallets": [
{
"rank": 1,
"owner": "5Q544fKr...",
"balance": 12750000,
"balance_change": {
"1d": { "tokens": 0, "pct": 0 },
"7d": { "tokens": 250000, "pct": 2.0 },
"14d": { "tokens": 750000, "pct": 6.2 },
"30d": { "tokens": 12750000, "pct": null }
}
}
]
}balance_change.pct is null for brand-new positions (no pre-window balance). When has_coverage is false the token has not been backfilled yet and summary/wallets are empty.
POST /whale-activity Bulk
Returns whale accumulation summary (and optional sparkline) for up to 10 Solana tokens in one request. Wallet tables are not available in bulk. Use the single-token GET for those. Tokens without coverage come back with has_coverage: false.
Rate limit: 6 requests per minute on Premium, 12 on Developer (quota cost = number of tokens requested)
Example Request
curl -X POST "https://clobr.io/api/v1/whale-activity" \
-H "x-api-key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"token_addresses": [
"9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump",
"7GCihgDB8fe6KNjn2MYtkzZcRjQy3t9GHdC8uHYmW2hr"
],
"include": ["summary", "sparkline"]
}'The body also accepts an optional chain field (solana or all). Each address's chain comes from its shape, so it is only an assertion.
Response Format
{
"chain": "solana",
"count": 2,
"tokens": [
{
"token_address": "9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump",
"chain": "solana",
"has_coverage": true,
"last_snapshot_at": "2025-09-15T10:30:00Z",
"summary": { "accumulating": { "...": "..." }, "new_wallets": { "...": "..." }, "net_flow": { "...": "..." } },
"sparkline": { "top20": ["..."], "top50": ["..."], "top100": ["..."] }
},
{
"token_address": "7GCihgDB8fe6KNjn2MYtkzZcRjQy3t9GHdC8uHYmW2hr",
"chain": "solana",
"has_coverage": false,
"last_snapshot_at": null
}
]
}GET /dlmm/:address
Returns the DLMM pools for a single token: the pool list with 1-hour realized stats and leader chips. Mirrors the token page's DLMM Pools tab. A pool with no board activity this hour has stats_1h: null and no chips, and individual stats_1h fields can also be null. The per-pool chips array is the label mirror of the winning pool in chips.leaders.
Parameters
| Name | Required | Description |
|---|---|---|
| address | Yes | Token mint address (base58), passed as a path segment. A 0x address returns 400 chain_not_supported — DLMM pools are Solana-only |
| chain | No | solana or all. Derived from the address, so it's only an assertion — a value that disagrees returns 400 chain_mismatch |
Example Request
curl -X GET "https://clobr.io/api/v1/dlmm/9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump" \ -H "x-api-key: your_api_key_here"
Response Format
{
"address": "9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump",
"chain": "solana",
"period": "1h",
"pools": [
{
"pubkey": "Ah2sM6ZzR8YpXv1kQ3n7DfWcJL9uTbEo5RgNhKmSPqV",
"bin_step": 100,
"active_id": 8388608,
"token_x_mint": "So11111111111111111111111111111111111111112",
"token_x_symbol": "SOL",
"token_x_icon": "https://...",
"token_x_decimals": 9,
"token_x_price": 172.4,
"token_y_mint": "9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump",
"token_y_symbol": "SOLdiers",
"token_y_icon": "https://...",
"token_y_decimals": 6,
"token_y_price": 0.0000249,
"pool_price": 0.0000249,
"base_fee_pct": 1.0,
"dynamic_fee_pct": 3.58,
"reserve_x": 350.2,
"reserve_x_usd": 60000,
"reserve_y": 2100000000,
"reserve_y_usd": 52900,
"total_liquidity_usd": 112900,
"num_positions": 0,
"num_wallets": 0,
"stats_1h": {
"fees": 2000,
"volume": 585100,
"effectiveFeeBps": 34.2,
"feesPerAvgTvl": 0.0163,
"rangeYield": 0.125,
"rangeTvl": 16000,
"feeCapture": 1.4,
"captureShare": 0.55,
"tvl": 585100
},
"chips": []
}
],
"chips": {
"definitions": [
{ "key": "feesPerAvgTvl", "label": "Top $/TVL", "tip": "..." },
{ "key": "rangeYield", "label": "Top range yield", "tip": "..." },
{ "key": "fees", "label": "Most fees", "tip": "..." }
],
"leaders": {
"feesPerAvgTvl": "Ah2sM6ZzR8YpXv1kQ3n7DfWcJL9uTbEo5RgNhKmSPqV",
"rangeYield": "Ah2sM6ZzR8YpXv1kQ3n7DfWcJL9uTbEo5RgNhKmSPqV",
"fees": "Ah2sM6ZzR8YpXv1kQ3n7DfWcJL9uTbEo5RgNhKmSPqV"
}
}
}GET /dlmm-pools
Returns the Hot DLMM Pools board: live Meteora DLMM pools ranked for a single time window. Scope the board to one token's pools with the mint parameter, which also adds a rangeYield figure per pool.
Parameters
| Name | Required | Description |
|---|---|---|
| chain | No | solana (default) or all. DLMM coverage is Solana-only, so all is equivalent to solana |
| period | No | 1h (default), 2h, 4h, 12h, or 24h |
| sort | No | rangeyield (default), feespertvl, fees, volume, or tvl. rangeyield = fees / avg liquidity in the window's full traveled price range (set-and-forget); rangeCeiling in the response is the perfect-rebalancer upper bound; feespertvl = fees / warehouse-averaged pool TVL |
| minTvl | No | USD TVL floor (0 to 10,000,000, default 10000; 0 when a mint is set) |
| mint | No | Base58 token mint that scopes the board to that token's pools (adds rangeYield) |
Example Request
curl -X GET "https://clobr.io/api/v1/dlmm-pools?period=1h&sort=feespertvl&minTvl=10000" \ -H "x-api-key: your_api_key_here"
Response Format
{
"chain": "solana",
"period": "1h",
"sort": "feespertvl",
"minTvl": 10000,
"mint": null,
"count": 50,
"data": [
{
"address": "Ah2sM6ZzR8YpXv1kQ3n7DfWcJL9uTbEo5RgNhKmSPqV",
"baseSymbol": "SOL",
"quoteSymbol": "SOLdiers",
"baseMint": "So11111111111111111111111111111111111111112",
"quoteMint": "9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump",
"tokenIcon": "https://...",
"tvl": 585100,
"binStep": 100,
"baseFeePct": 1.0,
"volume": 585100,
"fees": 2000,
"effectiveFeeBps": 34.2,
"captureShare": 0.55,
"feeCapture": 1.4,
"tokenPoolCount": 5,
"rangeTvl": 16000,
"rangeYield": 0.125,
"rangeCeiling": 0.31,
"feesPerAvgTvl": 0.0163
}
]
}GET /lp-cheat-sheet
Returns the LP fee-density leaderboard: tokens ranked by fee density (organic volume ÷ near-price liquidity), the return-on-liquidity signal for LPs. Same metric as the /lp-cheat-sheet page.
Parameters
| Name | Required | Description |
|---|---|---|
| chain | No | solana (default), robinhood, base, ethereum, hyperevm, or all. On EVM chains organic_volume is total DEX volume (no wash filter yet), and 6h with denominator=range returns no EVM rows |
| window | No | Volume window for the numerator: 1h (default), 6h, or 24h |
| denominator | No | near (default), bin10, or range. near = ±25-bin fixed band; bin10 = ±10-bin fixed band; range = liquidity inside the window's traveled price range |
| limit | No | Number of tokens to return (1 to 100, default 25) |
Example Request
curl -X GET "https://clobr.io/api/v1/lp-cheat-sheet?window=1h&denominator=near&limit=25" \ -H "x-api-key: your_api_key_here"
Response Format
{
"chain": "solana",
"window": "1h",
"denominator": "near",
"limit": 25,
"count": 25,
"data": [
{
"rank": 1,
"address": "9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump",
"chain": "solana",
"symbol": "SOLdiers",
"name": "SOLdiers",
"icon": "https://...",
"organic_volume": 585100,
"denom_liquidity_usd": 112900,
"fee_density": 5.18
}
]
}Tokens with under $1,000 of near-price liquidity are excluded (denominator floor).
GET /odds
For a major perp (BTC, ETH, SOL, XRP, DOGE, BNB, LINK, BCH, TRX, ETC, ADA, SUI, LTC, XLM, AVAX, APT, ZEC, HBAR, POL, PEPE, AAVE, UNI and WLD): the probability that price hits your take profit first, your stop first, or neither within 1h, 4h or 24h. Every answer carries the random-walk odds for the same levels (what the odds would be if price moved randomly with the same volatility), the inputs used, and the payoff and costs per $1,000 notional for a long and a short. Expected P&L is minus your costs: in our out-of-sample tests the odds did not make any take-profit / stop pair pay on average. Inputs are volatility, momentum, funding and time of day. Liquidation heatmaps and order book depth are not inputs: they did not add accuracy in our 3-year backtest. Monthly results: track record.
Parameters
| Name | Required | Description |
|---|---|---|
| asset | Yes | BTC, ETH, SOL, XRP, DOGE, BNB, LINK, BCH, TRX, ETC, ADA, SUI, LTC, XLM, AVAX, APT, ZEC, HBAR, POL, PEPE, AAVE, UNI and WLD. Every asset has 1h; 4h for BTC, ETH, SOL, XRP, DOGE, BNB, LINK, BCH, TRX and ETC; 24h for BTC, ETH and SOL. |
| tp, sl | No | Take profit and stop, in USD. tp above sl reads as a long, below as a short. Omit both for the ±1σ long levels |
| horizon | No | 1h, 4h (default) or 24h |
| leverage | No | 1 to 125 (default 1). Sets the liquidation price and the EV per $1,000 of margin |
| taker_fee_bps | No | Taker fee per side in basis points (default 4.5) |
Example Request
curl -X GET "https://clobr.io/api/v1/odds?asset=BTC&tp=83500&sl=80100&horizon=4h" \ -H "x-api-key: your_api_key_here"
Response Format (shortened)
{
"asset": "BTC",
"price": 82036.8,
"horizon": "4h",
"side": "long",
"tp": 83500,
"sl": 80100,
"p_tp_first": 0.0206,
"p_sl_first": 0.0043,
"p_neither": 0.9751,
"baseline": {
"random_walk": { "p_tp_first": 0.0127, "p_sl_first": 0.0008, "p_neither": 0.9865 },
"martingale": { "p_tp_first_given_hit": 0.5696 }
},
"sigma": { "horizon_pct": 0.71, "plus_1": 82620.9, "minus_1": 81456.8, "plus_2": 83209.1, "minus_2": 80881.0 },
"inputs": { "realized_vol_annualized_pct": 33.2, "funding_rate_last_settled": 0.00006606, "funding_interval_hours": 8 },
"ev": {
"notional_usd": 1000, "leverage": 1, "taker_fee_bps": 4.5, "funding_settlements": 1,
"long": { "ev_usd": -0.95, "gain_if_take_profit_usd": 17.84, "loss_if_stop_usd": 23.61, "fees_usd": 0.9, "funding_usd": 0.05 },
"short": { "ev_usd": -0.85 }
},
"model": { "name": "tpsl-odds", "version": "1.0.0+fit20261020", "track_record": "/odds/track-record" },
"assumptions": ["..."]
}EV = P(TP first) × gain − P(SL first) × loss − fees − funding, per $1,000 notional. A trade that hits neither level counts as zero. Full field list in the OpenAPI spec.
GET /replay/:address
Returns a token's depth history: the support and resistance liquidity in every market, per price bin, snapshot by snapshot. It is the data behind the Replay tab, at the resolution it is stored. Works for a Solana mint, a 0x contract or a crypto major's key (crypto:BTC). A crypto key alias (crypto:PUMP) reads its token's history and names it in resolved_token. The address decides the chain, so chain is optional. The one case it matters is a 0x address that is a token on two chains: an explicit EVM chain (solana, robinhood, base, ethereum, hyperevm) picks which chain's history answers, and a chain that contradicts the address returns 400 chain_mismatch. Majors are served at the 1% price grid by default; add resolution=fine for their 10 bp grid (see 10 bp history for crypto majors).
replay_busyand Retry-After: 1; retry, and no quota is used. Each request costs one call from your monthly quota.Resolution and retention
- Solana: every stored snapshot (
raw, seconds to a couple of minutes apart, depending on the token) from 2026-10-03 18:00 UTC onward. Before that, one snapshot every 15 minutes (15m) back to late September 2026. - Robinhood Chain: every stored snapshot (
raw, about 2 minutes apart) from 2026-10-01 onward. Before that, one snapshot per hour (1h, about -25% to +22% around the price) back to late September 2026, for actively tracked tokens. - How much history exists: 365 days is a rolling retention limit, not the amount available today. History grows by one day each day until it reaches 12 months (around October 2027); after that, the oldest day drops off each day. A window with no stored snapshots returns
snapshot_count: 0andwindow.served_from: null; a window ending more than 365 days ago returns 400window_out_of_range. - Every snapshot says which
tierit came from. Where raw data exists, raw data is served.
Parameters
| Name | Required | Description |
|---|---|---|
| from | No | Window start. Unix epoch seconds (1791053458) or an RFC 3339 timestamp with a zone (2026-10-03T00:00:00Z). Default: 24 hours before to. Milliseconds and timestamps without a zone are rejected. |
| to | No | Window end, same formats. Default: now. The window is clamped to the last 365 days. |
| group | No | What one ladder stands for. market (default): each pool or order book. venue: every market of one venue summed, for example all Orca Whirlpool pools. type: one ladder per type (see types). all: one ladder per snapshot, everything summed (the smallest response). |
| types | No | Keep only these types, comma-separated: onchain_pool (DEX pools, including the constant-product total), onchain_limit_order (Jupiter, Meteora and Fusion limit orders), cex_spot, cex_perp (futures and perps books). Default: all. |
| onchain | No | true is short for types=onchain_pool,onchain_limit_order. |
| venues | No | Keep only these venues, comma-separated venue keys. A key is the venue name in lowercase with dashes: orca-whirlpool, meteora-dlmm, jupiter-limit-order, constant-product, binance, binance-futures, uniswap-v3-robinhood. Every response lists the token's keys in facets.venues. A key with no depth in the page comes back in filter.venues_not_found. |
| exclude_types, exclude_venues | No | Keep everything except these keys. The short way to drop one or two venues, for example exclude_venues=binance-futures,hyperliquid-perps. Send venues or exclude_venues (and types or exclude_types), not both. |
| markets | No | Deprecated, use group. split means group=market, aggregate means group=all. Sending both with different meanings returns 400 invalid_group. |
| min_pct, max_pct | No | Price band around each snapshot's price, in percent. Default -50 and 100; allowed -90 to 1000. |
| resolution | No | 1pct (default): the 1% grid every token has. fine: the 10 bp grid, for crypto keys (crypto:BTC, or an alias such as crypto:PUMP, whose 10 bp history starts 2026-11-01) only. Any other address returns 400 invalid_resolution. |
| granularity | No | With resolution=fine only: the last snapshot in each UTC bucket of 5m, 15m, 1h, 4h or 1d. Default: every stored snapshot (one per 5 minutes). It also sets how long a window may be (see below). |
Paging
One response holds up to 100,000 cells (and at most 288 snapshots), and never part of a snapshot. If the window does not fit, next_from is the time of the first snapshot not served: request again with from=next_from and the same to. next_from is null on the last page. A busy token such as PUMP fits about 15 split snapshots per page, or a full hour of aggregate ones.
Response format
The response is columnar. Markets are listed once, and each snapshot carries parallel arrays: cell i is market_idx[i], bin[i], support_usd[i], resistance_usd[i]. A bin is a step on a 1% geometric ladder: its price is price_usd × 1.01^bin. Times are Unix epoch seconds. Send Accept-Encoding: gzip or br; a full page compresses about 5 to 10 times.
10 bp history for crypto majors
resolution=fine serves a major's depth on the 10 bp grid the Replay tab shows, from the same stored snapshots. What changes from the 1% grid:
- Bins are absolute. A cell's
binis k on the gridbin_ratio = 1.01^0.1(about 0.1%, given asbin_step): it covers prices frombin_ratio^kup tobin_ratio^(k+1)USD.price_usdis the snapshot's price. - Band: bins cover ±2% of the price in history written before the deploy of clobr_bg#140, and ±10% from that deploy on. Each snapshot's
band_pctsays how far its bins reach (about 2 or about 10), and the top-levelband_pctis the widest in the page.min_pctandmax_pctnarrow it. - Cadence and reach: one snapshot every 5 minutes, kept for up to 365 days.
window.served_fromshows where the stored history starts. - Ladders:
group=marketgives one ladder per venue (spot and perps separate, each on-chain venue summed per chain).venue,type,alland the filters work as on the 1% grid.
Limits. These keep one request to a bounded amount of work:
- A window may hold at most 8,928 snapshots at its granularity with
group=typeorall: 31 days at the 5-minute default, 93 days at15m, the full 365 days at1hor coarser. Withgroup=marketorvenue(one ladder per venue, the largest response) the limit is 2,016 snapshots: 7 days at 5m, 21 days at15m, 84 days at1h. A longer window returns 400window_too_long, and the message states the limit. Split a longer back-fill into several windows. For one venue over a long window, usegroup=all&venues=binance. - A page holds up to 50,000 cells and 288 snapshots, sized from the data (a ±10%
group=marketpage holds about 3 snapshots). Page withnext_fromas above. - A page that takes longer than 15 seconds returns 503
query_timeout; retry it, or narrow it withgroup,typesorvenues. If the history store is unreachable, a page that needs it returns 503history_unavailableinstead of skipping the history.
How big it gets (crypto:BTC, about 80 ladders per snapshot at group=market), at ±2%: one hour is about 600 KB of JSON (about 100 KB with br) at group=market, 30 KB at group=type and 10 KB at group=all; a day at group=market is about 21 pages. At ±10% expect about 5 times that (a day at group=market is about 100 pages). For long back-tests, group=type or granularity=1h is usually enough and far smaller.
curl --compressed "https://clobr.io/api/v1/replay/crypto:SOL?resolution=fine&group=type&from=2026-10-22T00:00:00Z&to=2026-10-23T00:00:00Z" \ -H "x-api-key: your_api_key_here"
Grouping and filters
The filter runs first, then the grouping, so a grouped ladder never holds depth you filtered out. Each type and venue is classified from the market's source: CEX books are spot or perps (futures, perps and COIN-M books), on-chain order books are limit orders, and every other on-chain market is a pool. Constant-product depth is stored as one total per token, so its venue is constant-product. Every response except group=all without a filter carries facets: each type's and venue's mean depth per snapshot in the page, before the filter, with the keys to use. Grouping makes cells fewer, not snapshots: paging works as below. To leave out a venue or two, use the exclude form: group=venue&exclude_venues=binance-futures keeps every venue but Binance Futures.
Example: depth per venue, on-chain only
curl --compressed "https://clobr.io/api/v1/replay/pumpCmXqMfrsAkQ5r49WcJnRayYRqmXz6ae8H7H9Dfn?from=1791139064&group=venue&onchain=true" \ -H "x-api-key: your_api_key_here"
{
"group": "venue",
"filter": { "types": ["onchain_limit_order", "onchain_pool"], "venues": null,
"exclude_types": null, "exclude_venues": null, "venues_not_found": [] },
"snapshot_count": 10,
"groups": [
{ "key": "byreal-clmm", "label": "ByReal CLMM", "type": "onchain_pool" },
{ "key": "raydium-clmm", "label": "Raydium CLMM", "type": "onchain_pool" },
{ "key": "meteora-dlmm", "label": "Meteora DLMM", "type": "onchain_pool" }
],
"facets": {
"frames": 10,
"types": [
{ "key": "onchain_pool", "label": "On-chain pools", "usd": 18580647 },
{ "key": "onchain_limit_order", "label": "On-chain limit orders", "usd": 67386 },
{ "key": "cex_spot", "label": "CEX spot", "usd": 38051443 },
{ "key": "cex_perp", "label": "CEX perps", "usd": 69455478 }
],
"venues": [
{ "key": "hyperliquid-perps", "label": "Hyperliquid Perps", "type": "cex_perp", "usd": 27817478 },
{ "key": "binance-futures", "label": "Binance Futures", "type": "cex_perp", "usd": 18940544 }
]
},
"snapshots": [
{
"t": 1791139077,
"tier": "raw",
"price_usd": 0.00657776510719,
"group_idx": [0, 0, 0],
"bin": [-69, -68, -67],
"support_usd": [158.52, 159.31, 160.11],
"resistance_usd": [0, 0, 0]
}
]
}Example: one venue, summed into one ladder
curl --compressed "https://clobr.io/api/v1/replay/pumpCmXqMfrsAkQ5r49WcJnRayYRqmXz6ae8H7H9Dfn?from=1791139064&group=all&venues=orca-whirlpool" \ -H "x-api-key: your_api_key_here"
{
"group": "all",
"filter": { "types": null, "venues": ["orca-whirlpool"],
"exclude_types": null, "exclude_venues": null, "venues_not_found": [] },
"snapshot_count": 10,
"row_count": 1390,
"markets": [],
"snapshots": [
{
"t": 1791139077,
"tier": "raw",
"price_usd": 0.00657776510719,
"bin": [-69, -68, -67],
"support_usd": [3843.96, 3874.22, 3942.74],
"resistance_usd": [0, 0, 0]
}
]
}Example Request
curl --compressed "https://clobr.io/api/v1/replay/pumpCmXqMfrsAkQ5r49WcJnRayYRqmXz6ae8H7H9Dfn?from=2026-10-03T19:30:58Z&to=2026-10-03T20:30:58Z" \ -H "x-api-key: your_api_key_here"
Example Response (trimmed)
{
"token": "pumpCmXqMfrsAkQ5r49WcJnRayYRqmXz6ae8H7H9Dfn",
"chain": "solana",
"window": {
"from": 1791053458,
"to": 1791057058,
"clamped": false,
"served_from": 1791053474,
"served_to": 1791053848
},
"next_from": 1791053857,
"group": "market",
"filter": { "types": null, "venues": null, "exclude_types": null,
"exclude_venues": null, "venues_not_found": [] },
"markets_mode": "split",
"min_pct": -50,
"max_pct": 100,
"bin_ratio": 1.01,
"snapshot_count": 15,
"row_count": 94619,
"markets": [
{ "source": "Meteora DLMM", "exchange_type": "DEX",
"address": "4C8KctYZtMTZwV83Y5AcTPVT2aXYYu2t9ZhHdotFGnno", "pair": "MET" },
{ "source": "Meteora DLMM", "exchange_type": "DEX",
"address": "D7CCRNx6e2ck22P8N93xqJ2Kbcu13RmYVFYeVRqAyN8n", "pair": "SOL" }
],
"snapshots": [
{
"t": 1791053474,
"tier": "raw",
"price_usd": 0.006302025402746,
"market_idx": [1, 1, 1],
"bin": [-1, 0, 1],
"support_usd": [60.31, 0, 0],
"resistance_usd": [0, 60.31, 120.62]
}
]
}A 0x address that is the Robinhood Chain leg of a token that also trades on Solana is answered from the Solana mint, named in resolved_token. Cells under $1 per market and bin are left out. With group=all, markets is empty and snapshots have no market_idx. With group=venue or type, cells index groups through group_idx instead.