API Endpoints

Complete reference for all CLOBr API endpoints with request/response examples.

Quick Reference

MethodEndpointDescriptionTier
GET/score/:addressGet single token scorePremium
POST/scoreBatch query up to 50 tokensDeveloper
GET/top-scoresTop 50 tokens by CLOBr scorePremium
GET/market-depthMarket depth data for a tokenPremium
GET/market-depth/bulkMarket depth for up to 20 crypto majors in one callPremium
WS/streamPush market depth for crypto majors and tokens (1 credit per push)Premium
GET/dca-pressureTop tokens ranked by DCA pressurePremium
GET/dca-ordersDCA orders with flow projectionsPremium
GET/limit-ordersLimit orders with price range filtersPremium
GET/whale-activityWhale accumulation & holder-flow for a tokenPremium
POST/whale-activityBulk whale summary for up to 10 tokensPremium
GET/dlmm/:addressDLMM pools for a single tokenPremium
GET/dlmm-poolsHot DLMM Pools board for a time windowPremium
GET/lp-cheat-sheetTokens ranked by LP fee densityPremium
GET/oddsTP/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/:addressDepth history: liquidity per market and price bin over timePremium

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).

Nothing changes unless you ask for it. An existing integration that never sends 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

KeyChainAddress format
solanaSolanaBase58 mint (32–44 chars)
robinhoodRobinhood Chain0x + 40 hex contract address
baseBase0x + 40 hex contract address
ethereumEthereum0x + 40 hex contract address
hyperevmHyperEVM0x + 40 hex contract address
allEvery 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_chain

The 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_supported

A 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_mismatch

An 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

EndpointChainsAbsent chain means
GET /score/:addresssolana, robinhood, base, ethereum, hyperevmDerived from the address
POST /scoresolana, robinhood, base, ethereum, hyperevmDerived per address
GET /top-scoressolana, robinhood, base, ethereum, hyperevmsolana
GET /market-depthsolana, robinhood, base, ethereum, hyperevm, plus crypto majors by key (crypto:BTC)Derived from the address
GET /limit-orderssolana, robinhood, base, ethereum, hyperevmThe address's own chain (a real filter here — see above)
GET /dca-pressuresolanasolana
GET /dca-orderssolanaDerived from the address
GET / POST /whale-activitysolanaDerived from the address
GET /dlmm/:addresssolanaDerived from the address
GET /dlmm-poolssolanasolana
GET /lp-cheat-sheetsolanasolana
GET /replay/:addresssolana, 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

NameRequiredDescription
addressYesToken address as a path segment: a base58 Solana mint or a 0x EVM contract address
chainNosolana, 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

StatusMeaning
availableToken analyzed, all data populated
pendingNew token, waiting for analysis (~15 seconds)
unsupportedOn 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.
unscoredDepth-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_unavailableToken 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

NameRequiredDescription
chainNosolana (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.

Premium: Live data at 60 requests per rolling minute (2,000,000 calls per month)
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 0x addresses): a token you request is refreshed on the same schedule as a token a Premium user has open.
  • last_refresh is the time of the data you got.

Parameters

NameRequiredDescription
token_addressYesToken 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.
chainNosolana, 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_typeNoDEX (default), CEX, or ALL
currencyNoUSD (default) or SOL
low_pct_changeNoLower bound % change (-0.9 to 10.0)
high_pct_changeNoUpper bound % change (-0.9 to 10.0)
delayedNotrue for delayed data
include_summaryNotrue 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_fineNoCrypto 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_typesNoCrypto 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_type defaults to ALL, and market_types and include_fine work.
  • It adds asset_key and a resolved block naming the token. Check resolved.contract_address once before you trade on it.
  • With market_types, an exchange market that stores spot and perp books as one row (for example OKX-USDT) is left out of spot and perp and listed in unsplit_markets, so a type is never guessed.
  • If the token loses its 0.1% bins, the key still works: depth_data keeps the 1% grid and fine_reason says not_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 is equity, commodity or preipo. 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_key and a resolved block 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.

Premium: 6 requests per rolling minute
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.

URL: wss://clobr.io/api/v1/stream
Access: 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_KEY header 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

DirectionMessageMeaning
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.
ServerreadyAuth accepted. Carries your tier and limits.
Serversubscribed / unsubscribedConfirms the keys now active or removed.
ServerdepthA full market-depth body for one key.
Servererror{"type":"error","code":"...","message":"..."}. The connection stays open unless a close follows.
ServerbyePlanned 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, chain
  • low_pct_change, high_pct_change
  • include_summary, include_fine
  • market_types: a string like "spot,perp" or an array like ["spot","perp"]
  • delayed: only false, 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": { ... }
  }
}
FieldMeaning
keyThe canonical key. It matches data.query_parameters.token_address.
seqCounts 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_msWhen CLOBr computed the data (Unix ms).
sent_msWhen the server sent the message (Unix ms).
dataThe exact GET /market-depth body for the key.

Errors

CodeMeaning
bad_requestMalformed message, unknown param name or invalid value.
not_allowedThe key or option is not available to you.
limitYou are over the assets-per-connection limit.
rate_limitedToo many subscribe or unsubscribe messages.
unavailableThat key's body could not be built right now. The message carries a key. The subscription stays, and the next update retries.

Close codes

CodeMeaning
4401Missing or invalid API key.
4402Subscription lapsed or monthly quota used up. CLOBr re-checks every 5 minutes.
4408No auth within 5 seconds.
4429Too many connections.
1012Planned restart. The server first sends {"type":"bye","reconnect_ms":2500}. Reconnect after reconnect_ms and subscribe again.

Limits

LimitPremiumDeveloper
Connections per account25
Assets per connection520
Subscribe / unsubscribe messages5 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.

Rate limit: 6 requests per minute on Premium, 12 on Developer (data updates every ~15 seconds)

Parameters

NameRequiredDescription
chainNosolana (default) or all. DCA data is Solana-only, so all is equivalent to solana; any other chain returns 400 chain_not_supported
sort_byNousd (default) or impact (percentage)
sort_dirNodesc (default, buy pressure first) or asc (sell pressure first)
sort_timeframeNo5_min, 30_min, 1_hr, 6_hr, 24_hr (default)
include_ordersNotrue to include nested individual orders per token (default: false)
order_limitNoMax orders per token when include_orders=true (default 5, max 20)
limitNoNumber of tokens to return (default 20, max 50)
min_mcap / max_mcapNoMarket cap filter range (USD)
min_liquidity / max_liquidityNoSupport 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

NameRequiredDescription
token_addressYesToken mint address (base58). A 0x address returns 400 chain_not_supported — DCA data is Solana-only
chainNosolana or all. Derived from the address, so it's only an assertion — a value that disagrees returns 400 chain_mismatch
sort_byNopct_impact (default) or usd_flow
min_mcap / max_mcapNoMarket cap filter range (USD)
min_liquidity / max_liquidityNoSupport 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
limitNoMax 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

NameRequiredDescription
token_addressYesToken address. Either shape: a base58 Solana mint or a 0x EVM contract address
chainNosolana, 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_changeNoLower bound % change (-0.99 to 10.0, default -0.9)
high_pct_changeNoUpper bound % change (-0.99 to 10.0, default 10.0)
limitNoMax 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.

Chain: Solana only
Rate limit: 1 request per second (cache responses ~60s, snapshot data refreshes roughly each minute)

Parameters

NameRequiredDescription
token_addressYesSolana token mint address (base58). A 0x address returns 400 chain_not_supported
chainNosolana or all. Derived from the address, so it's only an assertion — a value that disagrees returns 400 chain_mismatch
includeNoComma-separated sections: summary, sparkline, wallets (default: all three)
wallet_limitNoTop holders to return: 20, 50, or 100 (default 100)
wallet_activityNotrue 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.

Max tokens: 10 per request
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.

Rate limit: 1 request per second (Premium)

Parameters

NameRequiredDescription
addressYesToken mint address (base58), passed as a path segment. A 0x address returns 400 chain_not_supported — DLMM pools are Solana-only
chainNosolana 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.

Rate limit: 1 request per second (Premium)

Parameters

NameRequiredDescription
chainNosolana (default) or all. DLMM coverage is Solana-only, so all is equivalent to solana
periodNo1h (default), 2h, 4h, 12h, or 24h
sortNorangeyield (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
minTvlNoUSD TVL floor (0 to 10,000,000, default 10000; 0 when a mint is set)
mintNoBase58 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.

Rate limit: 1 request per second (Premium)

Parameters

NameRequiredDescription
chainNosolana (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
windowNoVolume window for the numerator: 1h (default), 6h, or 24h
denominatorNonear (default), bin10, or range. near = ±25-bin fixed band; bin10 = ±10-bin fixed band; range = liquidity inside the window's traveled price range
limitNoNumber 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.

Rate limit: 1 request per second (Premium). Inputs refresh every 45 seconds.

Parameters

NameRequiredDescription
assetYesBTC, 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, slNoTake profit and stop, in USD. tp above sl reads as a long, below as a short. Omit both for the ±1σ long levels
horizonNo1h, 4h (default) or 24h
leverageNo1 to 125 (default 1). Sets the liquidation price and the EV per $1,000 of margin
taker_fee_bpsNoTaker 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).

Rate limit: 1 request per 10 seconds per API key across all tokens. Developer keys get 10 requests per second. If the server is busy it returns 429 with 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: 0 and window.served_from: null; a window ending more than 365 days ago returns 400 window_out_of_range.
  • Every snapshot says which tier it came from. Where raw data exists, raw data is served.

Parameters

NameRequiredDescription
fromNoWindow 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.
toNoWindow end, same formats. Default: now. The window is clamped to the last 365 days.
groupNoWhat 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).
typesNoKeep 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.
onchainNotrue is short for types=onchain_pool,onchain_limit_order.
venuesNoKeep 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_venuesNoKeep 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.
marketsNoDeprecated, use group. split means group=market, aggregate means group=all. Sending both with different meanings returns 400 invalid_group.
min_pct, max_pctNoPrice band around each snapshot's price, in percent. Default -50 and 100; allowed -90 to 1000.
resolutionNo1pct (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.
granularityNoWith 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 bin is k on the grid bin_ratio = 1.01^0.1 (about 0.1%, given as bin_step): it covers prices from bin_ratio^k up to bin_ratio^(k+1) USD. price_usd is 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_pct says how far its bins reach (about 2 or about 10), and the top-level band_pct is the widest in the page. min_pct and max_pct narrow it.
  • Cadence and reach: one snapshot every 5 minutes, kept for up to 365 days. window.served_from shows where the stored history starts.
  • Ladders: group=market gives one ladder per venue (spot and perps separate, each on-chain venue summed per chain). venue, type, all and 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=type or all: 31 days at the 5-minute default, 93 days at 15m, the full 365 days at 1h or coarser. With group=market or venue (one ladder per venue, the largest response) the limit is 2,016 snapshots: 7 days at 5m, 21 days at 15m, 84 days at 1h. A longer window returns 400 window_too_long, and the message states the limit. Split a longer back-fill into several windows. For one venue over a long window, use group=all&venues=binance.
  • A page holds up to 50,000 cells and 288 snapshots, sized from the data (a ±10% group=market page holds about 3 snapshots). Page with next_from as above.
  • A page that takes longer than 15 seconds returns 503 query_timeout; retry it, or narrow it with group, types or venues. If the history store is unreachable, a page that needs it returns 503 history_unavailable instead 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.

API Endpoints | CLOBr Docs