# Market data

REST gives you the snapshot; [`/ws/market`](https://docs.troncharts.xyz/docs/realtime/market/) gives you
the stream. Use REST to seed a chart or a book, then keep it current over the
socket rather than re-polling.

## Endpoints

| Endpoint | Returns |
| --- | --- |
| `GET /api/v1/market/candles/{venue}/{symbol}` | OHLCV history. Served from cache, falling back to the venue's REST API. |
| `GET /api/v1/market/depth/{venue}/{symbol}` | Order-book depth. |
| `GET /api/v1/market/depth/{venue}/{symbol}/grouped` | Depth aggregated into price buckets. |
| `GET /api/v1/market/tape/{venue}/{symbol}` | Recent trade prints. `?limit=` 1–200, default 50. |
| `GET /api/v1/market/stats/{ticker}` | Mark price and 24h statistics. Takes the venue-suffixed ticker (`BTC.HL`) as the whole path segment. |
| `GET /api/v1/market/quotes/{venue}/{symbol}` | The current quote for one symbol. |
| `GET /api/v1/market/fx` | FX rates, for accounts denominated in a non-USD currency. |

The `{venue}/{symbol}` suffix is mandatory on `candles`, `depth`, and `tape`,
as is the `{ticker}` segment on `stats` — the bare prefix 404s. `candles` also
requires `?interval=`.

First call on a pair nobody is subscribed to opens the subscription and answers
`503 cold_cache` on `/depth` and `/tape` rather than blocking. Retry after
~500ms.

```bash
curl -s "https://api.troncharts.xyz/api/v1/market/candles/hyperliquid/BTC.HL?interval=1h&limit=500" \
  -H "authorization: Bearer $TOKEN" \
  -H "x-tenant-slug: $TC_TENANT_SLUG"
```

Candles are REST-only — `sdk.market` covers quotes, depth, and FX, so reach
candles through the raw request escape hatch:

```ts
type Bar = {
  openTime: string; closeTime: string
  open: string; high: string; low: string; close: string; volume: string
  closed: boolean
}

const { bars } = await sdk.client.request<{ bars: Bar[] }>(
  '/api/v1/market/candles/hyperliquid/BTC.HL',
  { query: { interval: '1h', limit: 500 } },
)
```

The response envelope is `{ venue, symbol, interval, bars, source, window }`.
An empty `bars` means the window holds no prints — unless `truncated: true` is
also present, which means the history lookup gave up mid-flight and you should
retry rather than treat the series as exhausted.

## Symbols carry their venue

`BTC.HL`, `WINFUT.B3` — the suffix is how the platform resolves pricing, and it
is part of the symbol, not decoration. Always source symbols from
`GET /api/v1/symbols/{venue}`.

## Depth granularity

Deep books are expensive to ship in full. Where a venue supports it, request
grouped depth and let the server aggregate rather than pulling every level and
bucketing client-side.

## Shared subscribers

Market-data subscriptions are shared across all consumers of a deployment: the
platform holds one upstream connection per venue and fans out. You are not
charged a venue connection per client, and you cannot exhaust a venue's
connection budget by scaling your own fleet.

## Custom indicators and backtests

If you compute studies server-side, `GET /api/v1/indicators` and
`POST /api/v1/backtests/run` evaluate declarative indicator specs against the
same candle data, so a study renders identically in your UI and in a backtest.