# Market data feed

Market data is served by **Nuntius**, not by the TRON API (see
[Market data](https://docs.troncharts.xyz/docs/trading/market-data/)). The TRON API only issues the
session token that lets you in: it decides which venues and symbols your tenant
can see, signs that decision, and the Nuntius gateway enforces it.

## 1. Identify the caller

- **Server:** exchange your API key for a bearer as described in
  [Credentials](https://docs.troncharts.xyz/docs/auth/credentials/). The bearer pins your tenant, so no
  `Origin` or tenant header is needed.
- **Browser embed:** call from an origin registered on your tenant, or send
  `X-Tenant-Slug`. The signed-in user's cookie session is used when present.

## 2. Mint a feed session

```bash
curl -s -X POST https://api.troncharts.xyz/api/market-feed/session \
  -H "Authorization: Bearer $BEARER" \
  -H "Content-Type: application/json" -d '{}'
```

| Field | Meaning |
| --- | --- |
| `token` | Feed session token. Valid for **300 s**. |
| `expiresAt` | Token expiry, unix epoch **milliseconds**. |
| `refreshAfter` | When to mint the next one (60 s before `expiresAt`). |
| `gateway.url` | WebSocket URL to connect to. Use it as returned; do not hard-code a host. |
| `gateway.candleIntervals` | Candle intervals the gateway streams live. |
| `venues` | Venues your tenant is granted. |

The response is `Cache-Control: no-store`. Treat the token as a credential.

## 3. Connect and authenticate

1. Open `gateway.url`. The gateway sends `hello` first:
   ```json
   {"t":"hello","wire":1,"lim":{"subs":500,"outbox":1024,"depth":200},"feat":["seq","nack","unsub-levels","reauth"]}
   ```
2. Within **10 s**, send the token:
   ```json
   {"op":"auth","token":"<token>"}
   ```
3. Wait for `{"t":"auth","ok":true}` before subscribing. A rejected token
   closes the socket.

## 4. Subscribe

Symbols are venue-suffixed tickers, as listed by the Nuntius catalog
(`BTC.HL`, `ETH.HL`; see [History and catalog](#history-and-catalog-over-rest)).

```json
{"op":"sub","symbols":["BTC.HL","ETH.HL"],"levels":["L1"]}
```

Each symbol answers `ack` with a numeric `id`. Later frames for that symbol
carry the `id`, not the ticker:

```json
{"t":"ack","s":"BTC.HL","v":"hyperliquid","lv":["L1"],"id":331}
```

The current quote follows immediately (`snap: true`), then every change:

```json
{"t":"q","id":331,"seq":1386856,"snap":true,"bid":80211,"bidq":4.68466,"ask":80212,"askq":8.31542,"mark":80200,"index":80246,"fund":-0.000001784,"ts":1793829441205000000}
```

| Field | Meaning |
| --- | --- |
| `bid`, `ask` | Inside quote. `bidq`, `askq` are the sizes. |
| `mark` | The venue's mark price — what it liquidates against. |
| `index` | The venue's oracle / index price. |
| `fund` | Current funding rate. |
| `ts`, `pts` | Venue time and gateway publish time, unix epoch **nanoseconds**. |
| `oi` | Open interest in the venue's raw fixed-point. Not in natural units; do not use it yet. |

Prices are JSON numbers. Fields are present only when the venue supplies them;
an absent field is never zero.

`ack` with an empty `lv` means your session does not grant that symbol or level.

Other levels: `L2` (book, `b` frames), `TRADES` (`tr`), `CANDLES` (`c`).
`unsub` takes the same shape as `sub`. At most 500 symbols per connection.

## 5. Keep the connection

- **Refresh the token on the same socket.** At `refreshAfter`, mint a new
  session (step 2) and send `{"op":"auth","token":"<new>"}`. The gateway
  answers `auth ok` and keeps your subscriptions; there is no need to reconnect.
- **Heartbeat.** Send `{"op":"ping"}` and expect `{"t":"pong"}`.
- **Reconnect** with a fresh session if the socket drops, then subscribe again.
  The first `q` after `ack` is a full snapshot, so no state is lost.

## History and catalog over REST

The gateway also serves history and the symbol catalog, with the same session
token as `Authorization: Bearer <token>`:

- `GET /history/candles?symbol=BTC.HL&interval=1m&from=<ms>&to=<ms>&limit=` (up to 5000 bars)
- `GET /history/trades?symbol=BTC.HL&...`
- `GET /catalog/{venue}` — the symbols you can subscribe to and send in orders, with the metadata to size them
- `GET /stats/24h?venue={venue}` — last price, 24h change, high, low and volume per symbol

The host is the one in `gateway.url`, over `https`.

### The symbol catalog

`GET /catalog/{venue}` answers `{"venue":"…","markets":[…]}` for `hyperliquid`,
`aster`, `lighter`, `b3` and `lse`. It is the source of symbol metadata: take
tick size, lot size and leverage from here, not from the TRON API. Every row
carries:

| Field | Meaning |
| --- | --- |
| `symbol` | The ticker to subscribe to and to send in orders (`BTC.HL`, `BTCUSDT.A`, `ETH.LX`, `EURUSD.L`). On **B3** it is the bare code (`PETR4`, `WINFUT`): add `.B3` for orders and subscriptions (`WINFUT.B3`). |
| `name`, `exchange`, `assetClass`, `instrumentType`, `iconUrl` | Display fields. `instrumentType` is `perp`, `spot` or `future`. |
| `tick` | Price increment. Round every price you send to a multiple of it. |
| `qtyStep` | Quantity increment. Round every quantity you send to a multiple of it. |
| `priceDecimals`, `sizeDecimals` | Decimal places of a price and of a quantity. |

Some venues add their own fields:

| Venue | Extra fields |
| --- | --- |
| `hyperliquid` | `maxLeverage` (the venue's cap for the asset), `basePrice` |
| `aster` | `minSize` |
| `lighter` | `venueSymbol`, `marketId`, `minBaseAmount`, `minQuoteAmount` |
| `b3` | `contractMultiplier` (BRL per point: WIN 0.20, IND 1, WDO 10, DOL 50), `contractCode` on the continuous futures (the dated contract it maps to today, e.g. `WINZ26`), `marketStatus` (`open` / `closed`) and `reopenAt` (ISO time of the next open, `null` while open) |
| `lse` | `contractMultiplier` |

```json
{"symbol":"WINFUT","name":"Mini Ibovespa (front month)","exchange":"B3","assetClass":"index",
 "instrumentType":"future","iconUrl":null,"priceDecimals":0,"sizeDecimals":0,"tick":5,"qtyStep":1,
 "contractMultiplier":0.2,"contractCode":"WINZ26","marketStatus":"closed","reopenAt":"2026-11-12T12:00:00.000Z"}
```

The catalog lists only what your session may use: a venue the tenant has not
enabled answers with no rows. Treat a non-`200` answer or an empty `markets`
list as temporary and keep the last list you had.