24h Volume—Open Interest—24h Liquidations$1.36B24h Long/Short—BTC Dominance—ETH Dominance—
App
Language ▾
$ USD ▾
/api/sd/ls
GETAvailable

Long/short ratio for one coin

Self-data layer: long/short ratio for one coin

GET/api/sd/ls

Request

Query parameters

NameTypeRequiredDefaultAllowed valuesDescription
coinstringRequired——Coin symbol; 400 when missing. Alias: `base`. Example: BTC

Example request

curl -s "https://www.coinboss.com/api/sd/ls?coin=BTC"

Response fields

The field table is generated from real responses, so it lists exactly what the endpoint returns. Paths use a[] for array items and {*} for objects keyed by a dynamic name such as a coin or an exchange.

FieldTypeUnitDescription
successboolean—true when the request succeeded. On failure the body is `{ success: false, code, error, request_id }`.
coinstring—Coin symbol, upper case (for example BTC).
nownumbermsServer time when the response was built.
accountobject—Share of all accounts that are net long vs net short.
account.long_pctnumber%Long share.
account.short_pctnumber%Short share.
account.rationumber—Long share divided by short share (1 = balanced).
account.n_exchangesnumber—Number of exchanges contributing.
account.by_exchangearray—Per-exchange breakdown.
account.by_exchange[]object—Per-exchange breakdown.
account.by_exchange[].exchangestring—Exchange id, lower case (for example `binance`).
account.by_exchange[].symbolstring—Instrument symbol as normalised by CoinBoss (for example BTCUSDT).
account.by_exchange[].long_pctnumber%Long share.
account.by_exchange[].short_pctnumber%Short share.
account.by_exchange[].rationumber—Long share divided by short share (1 = balanced).
account.by_exchange[].updated_atnumbermsWhen this row was last updated.
account.by_exchange[].age_snumbersSeconds since this row was last updated.
account.by_exchange[].is_staleboolean—true when the row is older than the freshness window; stale rows are not used in totals.
account.by_exchange[].sourcestring—Which exchange statistic the row comes from.
account.by_exchange[].periodstring—Sampling period of the exchange statistic (for example `5m`).
top_accountobject—Same, restricted to the exchange-defined top traders.
top_account.long_pctnumber|null%Long share.
top_account.short_pctnumber|null%Short share.
top_account.rationumber|null—Long share divided by short share (1 = balanced).
top_account.n_exchangesnumber—Number of exchanges contributing.
top_account.by_exchangearray—Per-exchange breakdown.
top_account.by_exchange[]object—Per-exchange breakdown.
top_account.by_exchange[].exchangestring—Exchange id, lower case (for example `binance`).
top_account.by_exchange[].symbolstring—Instrument symbol as normalised by CoinBoss (for example BTCUSDT).
top_account.by_exchange[].long_pctnumber%Long share.
top_account.by_exchange[].short_pctnumber%Short share.
top_account.by_exchange[].rationumber—Long share divided by short share (1 = balanced).
top_account.by_exchange[].updated_atnumbermsWhen this row was last updated.
top_account.by_exchange[].age_snumbersSeconds since this row was last updated.
top_account.by_exchange[].is_staleboolean—true when the row is older than the freshness window; stale rows are not used in totals.
top_account.by_exchange[].sourcestring—Which exchange statistic the row comes from.
top_account.by_exchange[].periodstring—Sampling period of the exchange statistic (for example `5m`).
top_positionobject—Long vs short share of the positions held by top traders.
top_position.long_pctnumber|null%Long share.
top_position.short_pctnumber|null%Short share.
top_position.rationumber|null—Long share divided by short share (1 = balanced).
top_position.n_exchangesnumber—Number of exchanges contributing.
top_position.by_exchangearray—Per-exchange breakdown.
top_position.by_exchange[]object—Per-exchange breakdown.
top_position.by_exchange[].exchangestring—Exchange id, lower case (for example `binance`).
top_position.by_exchange[].symbolstring—Instrument symbol as normalised by CoinBoss (for example BTCUSDT).
top_position.by_exchange[].long_pctnumber%Long share.
top_position.by_exchange[].short_pctnumber%Short share.
top_position.by_exchange[].rationumber—Long share divided by short share (1 = balanced).
top_position.by_exchange[].updated_atnumbermsWhen this row was last updated.
top_position.by_exchange[].age_snumbersSeconds since this row was last updated.
top_position.by_exchange[].is_staleboolean—true when the row is older than the freshness window; stale rows are not used in totals.
top_position.by_exchange[].sourcestring—Which exchange statistic the row comes from.
top_position.by_exchange[].periodstring—Sampling period of the exchange statistic (for example `5m`).
position_allobject—Long vs short share of all positions (venues that publish it).
position_all.long_pctnumber|null%Long share.
position_all.short_pctnumber|null%Short share.
position_all.rationumber|null—Long share divided by short share (1 = balanced).
position_all.n_exchangesnumber—Number of exchanges contributing.
position_all.by_exchangearray—Per-exchange breakdown.
position_all.by_exchange[]object—Per-exchange breakdown.
position_all.by_exchange[].exchangestring—Exchange id, lower case (for example `binance`).
position_all.by_exchange[].symbolstring—Instrument symbol as normalised by CoinBoss (for example BTCUSDT).
position_all.by_exchange[].long_pctnumber%Long share.
position_all.by_exchange[].short_pctnumber%Short share.
position_all.by_exchange[].rationumber—Long share divided by short share (1 = balanced).
position_all.by_exchange[].updated_atnumbermsWhen this row was last updated.
position_all.by_exchange[].age_snumbersSeconds since this row was last updated.
position_all.by_exchange[].is_staleboolean—true when the row is older than the freshness window; stale rows are not used in totals.
position_all.by_exchange[].sourcestring—Which exchange statistic the row comes from.
position_all.by_exchange[].periodstring—Sampling period of the exchange statistic (for example `5m`).
takerobject—Taker buy vs taker sell volume share.
taker.long_pctnumber|null%Long share.
taker.short_pctnumber|null%Short share.
taker.rationumber|null—Long share divided by short share (1 = balanced).
taker.n_exchangesnumber—Number of exchanges contributing.
taker.by_exchangearray—Per-exchange breakdown.
taker.by_exchange[]object—Per-exchange breakdown.
taker.by_exchange[].exchangestring—Exchange id, lower case (for example `binance`).
taker.by_exchange[].symbolstring—Instrument symbol as normalised by CoinBoss (for example BTCUSDT).
taker.by_exchange[].long_pctnumber%Long share.
taker.by_exchange[].short_pctnumber%Short share.
taker.by_exchange[].rationumber—Long share divided by short share (1 = balanced).
taker.by_exchange[].updated_atnumbermsWhen this row was last updated.
taker.by_exchange[].age_snumbersSeconds since this row was last updated.
taker.by_exchange[].is_staleboolean—true when the row is older than the freshness window; stale rows are not used in totals.
taker.by_exchange[].sourcestring—Which exchange statistic the row comes from.
taker.by_exchange[].periodstring—Sampling period of the exchange statistic (for example `5m`).
definitionsobject—Definition of each measure. The five measures answer different questions and are never blended.
definitions.accountstring—Account-based measure.
definitions.top_accountstring—Top-trader account measure.
definitions.top_positionstring—Top-trader position measure.
definitions.position_allstring—All-position measure.
definitions.takerstring—Taker buy / sell measure.
methodobject—Plain-text statement of the formulas used for this response.
method.normalizestring—Plain-text note on normalisation: each exchange value is rescaled so long % + short % = 100, and ratio = long % ÷ short %.
method.aggregatestring—Aggregate across exchanges.
method.freshnessstring—Plain-text freshness rule: rows updated within 24 hours are shown and `is_stale` marks rows older than 2 hours.

Generated 2026-11-11 23:00 UTC from 4 real responses.

Example response

/api/sd/ls?coin=BTC · Real response captured 2026-11-13 03:57:48 UTC. Long arrays and maps are shortened for display: taker.by_exchange had 4 items; account.by_exchange had 6 items; top_position.by_exchange had 4 items.

  • {
    • "success": true,
    • "coin": "BTC",
    • "now": 1794542268813,
    • "account": {
      • "long_pct": 73.52,
      • "short_pct": 26.48,
      • "ratio": 2.7764,
      • "n_exchanges": 6,
      • "by_exchange": [ … 2 ]
      },
    • "top_account": {
      • "long_pct": 66.89,
      • "short_pct": 33.11,
      • "ratio": 2.0198,
      • "n_exchanges": 2,
      • "by_exchange": [ … 2 ]
      },
    • "top_position": {
      • "long_pct": 49.7,
      • "short_pct": 50.3,
      • "ratio": 0.9881,
      • "n_exchanges": 4,
      • "by_exchange": [ … 2 ]
      },
    • "position_all": {
      • "long_pct": 49.43,
      • "short_pct": 50.57,
      • "ratio": 0.9775,
      • "n_exchanges": 1,
      • "by_exchange": [ … 1 ]
      },
    • "taker": {
      • "long_pct": 43.47,
      • "short_pct": 56.54,
      • "ratio": 0.7688,
      • "n_exchanges": 4,
      • "by_exchange": [ … 2 ]
      },
    • "definitions": {
      • "account": "all accounts: share of accounts that are net long vs net short (headcount, not size)",
      • "top_account": "top traders only: share of top-trader accounts net long vs net short",
      • "top_position": "top traders only: long position size vs short position size",
      • "position_all": "all traders: long position size vs short position size (Bitget only; kept separate from top-trader figures)",
      • "taker": "taker buy volume vs taker sell volume in the period (aggressor flow; not positions)"
      },
    • "method": {
      • "normalize": "each exchange value converted to long% + short% = 100; ratio = long% / short%",
      • "aggregate": "simple mean of long% across exchanges within the same definition; different definitions are never mixed",
      • "freshness": "rows updated within 24h are shown; is_stale marks rows older than 2h"
      }
    }

Verified samples

Besides the example above, the probe calls this endpoint with these parameters and checks the schema each time.

ParametersHTTPLatencyResult
coin=ETH2005 msPass
coin=SOL2005 msPass
coin=ARKM2004 msPass
—4001 msPass returns the expected error

Checked 2026-11-13 03:27:48 UTC

Details

Authentication
None. Public endpoint.
Rate limit
1200 requests per minute per IP
Server cache
30s
Edge micro-cache
10s
Update frequency
every 5 min (binance top-trader account ratio and okx taker / top-trader position ratios hourly; long-tail symbols every 30 min)
Window
latest snapshot (rows within 24 h; is_stale flag after 2 h)
Data sources
Long/short ratios polled by in-house collectors from the public statistics endpoints of 7 exchanges (binance, okx, bybit, bitget, gate, htx, kraken).
Exchange coverage
account ratio: binance, okx, bybit, bitget, gate, kraken; top-trader account ratio: binance, htx; position ratio: binance, okx, gate, htx, bitget; taker buy/sell ratio: binance, okx, bitget, gate; upstream sampling periods differ (5 min to 1 h); symbol coverage is a rolling top-by-volume list (about 280 coins on binance account ratio, about 20-60 coins on other venues / types); the response lists each upstream endpoint and its sampling period
Units
long / short as percentages of 100; ratio = long / short
Method
per group (account, top_account, top_position, position_all, taker): simple mean of long% across exchanges; groups are never mixed
Timestamps
Unix epoch milliseconds (UTC) unless the field description says otherwise
Response format
json
Stability
Stable
Available since
2026-11-11

Live status

AvailableChecked 2026-11-13 03:52:39 UTCHTTP 2005 msSchema matchesNewest data point 83s old

Availability, last 30 days

100% of 410 checks passed

Errors

Failed calls share one shape on every endpoint. The full list is on the errors page. Errors and rate limits →

CodeHTTPMeaningWhat to do
INVALID_PARAM400A required parameter is missing or a value is not accepted. `param` names the parameter when it is known.Do not retry unchanged; fix the request.
UNAUTHORIZED401The `CB-API-KEY` header was sent but the key is unknown or revoked. Public data needs no key — drop the header or use a valid key.Do not retry unchanged.
FORBIDDEN403The route is not part of the public API (internal or account-only).Do not retry.
NOT_FOUND404Unknown route, or the requested coin / exchange / fund does not exist.Do not retry; check the path and identifiers against the catalog.
RATE_LIMITED429More requests than the per-minute limit. `Retry-After` gives the seconds to wait.Wait for `Retry-After`, then retry with backoff.
INTERNAL500Unexpected server error. The message is generic by design; quote `request_id` when reporting it.Retry once after a few seconds; report it with the request id if it persists.
UPSTREAM_FAILED503The data source behind this endpoint did not answer in time. No stale or substitute numbers are returned in its place.Retry with backoff; check the status page.
UNAVAILABLE501 / 503The dataset is temporarily not ready (cache warming) or the endpoint has no lawful public source yet.Retry later; the catalog marks endpoints that are unavailable by design.
REQUEST_FAILED200Some older endpoints answer HTTP 200 with `success: false`. Always check `success`, not only the HTTP status.Depends on the message; treat as a failed request.

Try it

GET/api/sd/lsAvailable
Parameters

string — Coin symbol; 400 when missing. Alias: `base`.

Request URLhttps://www.coinboss.com/api/sd/ls?coin=BTC
Choose an endpoint and press “Send request”. The response, headers and timing will appear here.