API conventions
Rules that hold across endpoints: URL layout, the response envelope, symbols, units, timestamps, pagination and caching.
Base URL and versioning
All endpoints live under one base URL and are called with HTTPS GET. The current paths are version v1. Within v1, changes are additive: fields and endpoints may be added, existing fields keep their name, type and meaning. A breaking change would ship under a new path and be announced in the changelog first.
Base URL
https://www.coinboss.com/apiResponse envelope
Every JSON response has a top-level success flag. Endpoints of the self-collected data layer (paths under /api/sd) share the same additional blocks:
| Field | Description |
|---|---|
| success | true when the call worked. Always check it. |
| schema | Identifier and major version of the response shape. |
| now | Server time when the response was assembled, in milliseconds. |
| coverage | Which exchanges are included, which are unavailable and why, and which were excluded as stale. |
| method | The formula or rule behind each aggregate in the response. |
| meta | Sources, timestamps, window, quality grade, staleness flag, cache lifetime and the fallback behaviour. |
Older endpoints return success plus a data field and may not include coverage, method or meta. Their reference pages document the exact fields.
Coins, contracts and exchanges
- coin parameters take the upper-case base symbol, for example BTC or PEPE.
- Multiplier contracts such as 1000PEPE or kPEPE are merged into their base coin, with quantities converted.
- Exchange identifiers are lower case, for example binance, okx, bybit, hyperliquid.
- Contract symbols are returned as the exchange names them. USDT-, USDC- and coin-margined contracts and dated futures are distinguished by a contract type field where an endpoint mixes them.
- Tokenised-stock and commodity perpetuals that share a ticker with a crypto asset are excluded from the crypto aggregates.
Units
- Fields ending in _usd are US-dollar notional.
- Funding rates are fractions, not percent: 0.0001 means 0.01%. Fields ending in _8h are normalised to an 8-hour interval; the original interval is returned next to the raw rate.
- Fields ending in _pct are percentages: 1.5 means 1.5%.
- Open interest is single-sided notional in USD unless a field description says otherwise. Exchanges that publish double-sided figures are noted in the method block.
- Some legacy endpoints return decimals as strings to preserve precision. The field table shows the type as string(decimal).
Timestamps
- Timestamps are Unix epoch milliseconds in UTC unless a field description says otherwise.
- observed_at is the exchange's own timestamp for the newest record included, or null when the exchange does not provide one.
- received_at is when the CoinBoss collector stored that record.
- fetched_at is when the response was assembled. With a cached response it is older than the time of your call by up to the cache TTL.
- Daily series use UTC day boundaries.
Windows and intervals
- Window parameters use short tokens: 1h, 4h, 12h, 24h, and on some endpoints 3d, 7d, 30d, 90d. The reference page lists the accepted values for each endpoint.
- An unknown window value is either rejected with INVALID_PARAM or falls back to the documented default, as stated per parameter.
- Bucket size for time series depends on the window and is stated on the reference page.
Pagination and sorting
- List endpoints use limit and offset, or page and size, as documented per endpoint. Limits are capped; a larger value is reduced to the cap.
- Where a response includes total, it is the number of rows before pagination.
- Sort order is fixed unless the endpoint documents a sort parameter.
Null, zero and missing
- null means the value is unknown or unavailable. 0 means a measured zero.
- Charts must show a gap for null. Do not interpolate.
- A field marked “may be absent” in a field table can be missing from the object entirely; treat it like null.
Caching
- Each endpoint has a server cache TTL, shown on its reference page and as meta.cache_ttl_s. The X-Cache header reports HIT, STALE or MISS.
- A short edge cache of about ten seconds sits in front of most GET endpoints.
- Polling faster than the TTL returns identical data and only consumes your rate limit.
WebSocket
WebSocket
wss://www.coinboss.com/ws- The stream is push-only JSON. Each message has a type field.
- After a disconnect, reconnect with a delay and backfill from the matching HTTP endpoint.
Machine-readable documentation
The catalog, each endpoint's parameters and field table, the status and the quality matrix are available as JSON under /api/meta, and the whole catalog as an OpenAPI 3 document.