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

Options history (hourly)

Hourly series of option open interest, volume, put/call ratio, ATM IV or max pain for one coin. History starts when CoinBoss began collecting (2026-11-11); earlier hours are not back-filled.

GET/api/sd/options/history
Partial coverage. Collection of this series started on 2026-11-11. Until the requested range is filled, the response returns the points that exist, reports `points_count` against `expected_points`, and marks `meta.quality = "PARTIAL"`. Missing hours are not interpolated.
Degraded. The endpoint reports data quality STALE

Request

Query parameters

NameTypeRequiredDefaultAllowed valuesDescription
coinstringRequired——Coin symbol, case-insensitive (for example `BTC`). Missing or malformed values return 400. Example: BTC
metricstringRequired—oi, volume, pcr, atm_iv, max_painSeries to return. Example: oi
rangestringOptional7d24h, 7d, 30d, 90dLook-back range; one point per hour, 2160 points at most.
exchangestringOptionalallall, deribit, binance, bybit, okx, gate, coincallOne venue, or `all` for the cross-venue aggregate.

Example request

curl -s "https://www.coinboss.com/api/sd/options/history?coin=BTC&metric=oi"

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 }`.
schemastring—Schema id of this response. It changes only when an existing field changes meaning or type.
nownumbermsServer time when the response was built.
coinstring—Coin symbol (upper case).
exchangestring—Exchange id (lower case).
metricstring—Series selected by the `metric` parameter.
rangestring—Look-back range applied.
intervalstring—Spacing of the series points.
points_countnumber—Number of points returned.
expected_pointsnumber—Number of hourly points the requested range would hold when complete.
history_started_atnumbermsTime of the first hour collected by CoinBoss.
first_tnumbermsTime of the first point returned.
last_tnumbermsTime of the last point returned.
pointsarray—Series points, oldest first.
points[]object—Series points, oldest first.
points[].tnumbermsStart of the time bucket.
points[].snapshot_atnumbermsTime of the collector round the point was written from.
points[].n_exchangesnumber—Number of venues in the point.
points[].exchangesarray—Venues included in this row.
points[].exchanges[]string—Venues included in this row.
points[].oi_usdnumberUSDOpen interest as USD notional: coin quantity × spot index price. One-sided. may be absent
points[].call_oi_usdnumberUSDCall open interest, USD notional. may be absent
points[].put_oi_usdnumberUSDPut open interest, USD notional. may be absent
points[].oi_coinnumbercoinOpen interest in units of the underlying coin. may be absent
points[].index_pricenumberUSDSpot index price used for USD conversion (median of the venues' own index prices in aggregates). may be absent
coverageobject—What is and is not included in the numbers. Compare this before comparing totals with another source.
coverage.included_exchangesarray—Sources whose fresh data is included.
coverage.included_exchanges[]string—Sources whose fresh data is included.
coverage.unavailablearray—Sources that could not be included, each with a reason. They are never counted as 0.
coverage.unavailable[]object—Sources that could not be included, each with a reason. They are never counted as 0.
coverage.unavailable[].exchangestring—Exchange id (lower case).
coverage.unavailable[].reasonstring—Machine-readable reason code.
coverage.unavailable[].detailstring—Human-readable explanation of the reason.
coverage.stale_excludedarray—Rows left out because their last update is outside the fresh window. empty in the samples used to generate this table
methodobject—Plain-text statement of the formulas used for this response, one entry per field.
method.pointsstring—Formula note for `points`, plain text.
method.exchangesstring—Formula note for `exchanges`, plain text.
method.history_depthstring—Formula note for `history_depth`, plain text.
method.oi_usdstring—Formula note for `oi_usd`, plain text. may be absent
metaobject—Lineage and freshness of this response.
meta.schemastring—Schema id of this response. It changes only when an existing field changes meaning or type.
meta.sourcearray—Upstream public endpoints the data was collected from.
meta.source[]object—Upstream public endpoints the data was collected from.
meta.source[].exchangestring—Exchange id (lower case).
meta.source[].endpointstring—Public endpoint of the source the collector reads (shown for lineage; clients never call it).
meta.observed_atnull—Timestamp given by the source for the data.
meta.received_atnumbermsTime the CoinBoss collector received the data.
meta.fetched_atnumbermsTime this response was assembled.
meta.windowstring—Time window the numbers cover.
meta.qualitystring—FRESH, PARTIAL, STALE, BROKEN or UNAVAILABLE, judged from data timestamps and coverage.
meta.is_staleboolean—True when the data is older than its fresh window.
meta.cache_ttl_snumbersCache lifetime of this response.
meta.fallbackstring—What the endpoint returns when the collector or a source fails.
points[].pcr_oinumberratioPut open interest ÷ call open interest, in coin units; `null` when the call side is 0. may be absent
points[].pcr_volnumberratioPut 24h volume ÷ call 24h volume, in coin units; `null` when the call side is 0. may be absent
method.pcr_oistring—Formula note for `pcr_oi`, plain text. may be absent
method.pcr_volstring—Formula note for `pcr_vol`, plain text. may be absent
points[].atm_iv_30dnumber%ATM IV interpolated linearly to a constant 30-day maturity; `null` when 30 days is not bracketed by two expiries. may be absent
method.atm_ivstring—Formula note for `atm_iv`, plain text. may be absent
method.atm_iv_30dstring—Formula note for `atm_iv_30d`, plain text. may be absent

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

Example response

/api/sd/options/history?coin=BTC&metric=oi · Real response captured 2026-11-13 03:58:20 UTC. Long arrays and maps are shortened for display: points had 23 items; meta.source had 6 items; coverage.unavailable had 12 items.

  • {
    • "success": true,
    • "schema": "coinboss.sd.options/1",
    • "now": 1794542300888,
    • "coin": "BTC",
    • "exchange": "all",
    • "metric": "oi",
    • "range": "7d",
    • "interval": "1h",
    • "points_count": 23,
    • "expected_points": 168,
    • "history_started_at": 1794416400000,
    • "first_t": 1794416400000,
    • "last_t": 1794520800000,
    • "points": [
      • { … 9 },
      • { … 9 }
      ],
    • "coverage": {
      • "included_exchanges": [ … 6 ],
      • "unavailable": [ … 2 ],
      • "stale_excluded": []
      },
    • "method": {
      • "points": "one point per UTC hour bucket (t = bucket start, ms); the value is the LAST collector snapshot inside that hour (snapshot_at); hours in which the collector prod…",
      • "exchanges": "exchanges that were fresh and therefore included in that hour's figure; a change in this list between points explains level shifts in the all-exchange series",
      • "history_depth": "hourly summaries are kept for 90 days; the series starts when the collector was first deployed (history_started_at), so fewer points than the requested range ma…",
      • "oi_usd": "sum over contracts of oi_coin x that exchange's spot index price (USDT/USDC treated 1:1 as USD); oi_coin is open interest in units of the underlying coin after …"
      },
    • "meta": {
      • "schema": "coinboss.sd.options/1",
      • "source": [ … 2 ],
      • "observed_at": null,
      • "received_at": 1794522484809,
      • "fetched_at": 1794542300888,
      • "window": "7d",
      • "quality": "STALE",
      • "is_stale": true,
      • "cache_ttl_s": 300,
      • "fallback": "hours without a collector snapshot are absent from the series (no interpolation); PARTIAL means fewer hourly points exist than the requested range (history shor…"
      }
    }

Verified samples

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

ParametersHTTPLatencyResult
coin=ETH&range=24h&metric=pcr2002 msPass STALE
coin=BTC&metric=atm_iv2003 msPass STALE
coin=BTC4001 msPass returns the expected error

Checked 2026-11-13 03:58:20 UTC

Details

Authentication
None. Public endpoint.
Rate limit
1200 requests per minute per IP
Server cache
5m
Edge micro-cache
10s
Update frequency
One point per hour, written from the last collector round of that hour.
Window
24h / 7d / 30d / 90d, hourly points.
Data sources
Public REST option endpoints of Deribit, Binance, Bybit, OKX, Gate and Coincall, collected and stored by CoinBoss (sd_opt_latest, sd_opt_summary_hourly). No third-party aggregator is involved.
Exchange coverage
Six option venues. A coin that has no listed options on the selected venues returns HTTP 200 with null fields, `meta.quality = "UNAVAILABLE"` and the reason under `coverage.unavailable`. Venues without a public option feed are listed there as well.
Pagination
No paging; `range` bounds the number of points.
Sorting
Time ascending.
Units
USD notional = contracts × contract size × spot index price of the venue. `*_coin` fields are in units of the underlying coin. Implied volatility is in percent (55 = 55 %). `vol_premium_usd_24h` is premium turnover, reported separately and never added to notional volume.
Timestamps
Unix epoch milliseconds (UTC) unless the field description says otherwise
Response format
json
Stability
Stable
Available since
2026-11-11

Live status

DegradedChecked 2026-11-13 03:58:20 UTCHTTP 2002 msSchema matchesNewest data point 6h old

The endpoint reports data quality STALE

Availability, last 30 days

99.75% of 407 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/options/historyDegraded
Parameters

string — Coin symbol, case-insensitive (for example `BTC`). Missing or malformed values return 400.

string — Series to return.

string · default 7d — Look-back range; one point per hour, 2160 points at most.

string · default all — One venue, or `all` for the cross-venue aggregate.

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