> For the complete documentation index, see [llms.txt](https://txnlab.gitbook.io/haystack-dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://txnlab.gitbook.io/haystack-dev/haystack-api/websocket.md).

# Live Data (WebSocket)

Live prices, trades, market data, liquidity notices and curve updates over a WebSocket.

`wss://api.hay.app/api/wsLiveData`

One socket streams live updates for the assets you watch: price changes, trades, market data about once a minute, and on request liquidity adds and removes and HayLaunch curve updates.

## Connecting

Browsers can't set headers on a WebSocket, so a browser sends a publishable key as the `apiKey` query parameter:

```javascript
const ws = new WebSocket('wss://api.hay.app/api/wsLiveData?apiKey=hay_pk_...')
```

A server can send its secret key in the `X-API-Key` header of the upgrade request instead. A secret key in the URL is ignored. Opening a socket counts against a limit of 30 per minute.

## Commands

Every message you send is JSON with a `requestId` of your choice and one `command`, written as `{ "type", "value" }`:

```json
{ "requestId": "req-1", "command": { "type": "watch", "value": { "asset": ["31566704", "0"] } } }
```

| Command | `value`                                                                                                                           |
| ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `watch` | `{ asset: string[], include?: string[] }`. Up to 40 asset IDs, as strings. Replaces what was watched and resumes a paused stream. |
| `pause` | `true`. Pauses the stream. To resume, send `watch` again.                                                                         |

Nothing streams until your first `watch`. A `watch` naming an unknown asset is refused whole, with an `ack` whose `success` is `false`, and the previous watch stays. A command that breaks the schema, such as more than 40 assets or 10 `include` values, ends the socket.

`include` opts into messages beyond prices, trades and metrics:

* `liquidity`: adds and removes in the assets' pools.
* `curve`: HayLaunch curve updates.

Use them for a page about one token: a watch that includes ALGO with `liquidity` gets every add and remove in every ALGO pool. Unknown values are ignored.

## Messages

Every message you receive is `{ "assetId": "<id>", "data": { "type", "value" } }`. `assetId` is a string. Messages that aren't about an asset leave it out (older servers sent `null`), so test for both.

| `type`        | `value`                                                                                                                                                                                                                                                                                 |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connected`   | `true`, once the socket is ready.                                                                                                                                                                                                                                                       |
| `ack`         | `{ requestId, success, error }`: the answer to one of your commands.                                                                                                                                                                                                                    |
| `priceChange` | `{ timestamp, price, usdPrice }`: the asset's new price per whole token, in ALGO and USD. Price-only updates come at most once every 2 seconds per asset, the latest price winning. Each trade is also followed at once by a `priceChange` at its price.                                |
| `trade`       | A trade, as in [activity](/haystack-dev/haystack-api/trades-and-liquidity.md#activity): `type`, `account`, `amount`, `priceInAlgo`, `priceInUsd`, `totalCostUsd`, ... The swap inside an uneven or single-sided liquidity add or remove arrives as a trade too, with `liquidityOp` set. |
| `metrics`     | About once a minute: `changeAlgo` and `changeUsd` (percent changes), `volume24h`, `tvl`, `marketCap`, `fdMarketCap`, `circulatingSupply`, `totalSupply`, `burnedSupply` (whole tokens), `holders`.                                                                                      |
| `liquidity`   | `include: ["liquidity"]` only. A notice of an add or remove: `{ side, opType, poolId, account, timestamp, round, roundPos, groupId, txnId, totalUsd }`. Fetch the full event from [activity](/haystack-dev/haystack-api/trades-and-liquidity.md#activity) with `kinds=liquidity`.       |
| `curve`       | `include: ["curve"]` only. A HayLaunch token's curve after a buy or sell: `{ realTokenReserves, realBondingReserves, round, roundPos, timestamp, bonded }`, reserves in base units as strings. `bonded: true` means the curve is closed.                                                |
| `closing`     | `true`: the server is closing a socket that has been idle for 9 minutes, with no messages either way. Reconnect when you need it again.                                                                                                                                                 |

## Keeping the socket healthy

The server pings every 30 seconds and closes a socket that stops answering. A client that stops reading is cut off. Pings don't count as activity: a paused socket, or one watching quiet assets, is closed after 9 idle minutes.

Reconnect with backoff, send your `watch` again, and refetch from the REST endpoints anything you missed while disconnected. Pause the stream while your page is hidden. If it stays hidden for long, close the socket and reconnect when the page comes back.
