WebSocket stream
Reference for wss://api.rarebl.com/ws: subscribe messages, channels, events, ping and pong, limits.
# WebSocket stream
`wss://api.rarebl.com/ws` pushes live events: new blocks, fees, address activity, transaction progress and token transfers. It is keyless like the rest of the API. This is a reference page: there is no Try It for a WebSocket, so use the examples below from your own client. For a walkthrough see [Live data over WebSocket](https://docs.rarebl.com/guides/websocket).
## Connect
```js JavaScript
const ws = new WebSocket('wss://api.rarebl.com/ws');
ws.onopen = () => ws.send(JSON.stringify({
op: 'subscribe',
channels: ['blocks:btc', 'live', 'fees:eth'],
}));
ws.onmessage = (msg) => {
const m = JSON.parse(msg.data);
if (m.op === 'ping') return ws.send(JSON.stringify({ op: 'pong' }));
console.log(m);
};
```
## Messages
| Direction | Message | Meaning |
| --- | --- | --- |
| Client to server | `{"op":"subscribe","channels":[…]}` | Subscribe to channels. |
| Server to client | `{"op":"subscribed","channels":[…],"rejected":[{"channel","reason"}]}` | The channels now active, and any that were refused. Channels come back normalised (ETH lower-case, BCH CashAddr without the prefix). |
| Client to server | `{"op":"unsubscribe","channels":[…]}` | Stop receiving channels. |
| Server to client | `{"channel","type","data","ts"}` | An event on a channel. |
| Server to client | `{"op":"ping"}` every 20 s | Answer with `{"op":"pong"}`. Any message you send counts as life; 70 s of silence closes the socket. |
| Server to client | `{"op":"error","code","message"}` | A message was refused. |
## Channels
| Channel | Event data |
| --- | --- |
| `live` | The heads of all chains, like [Live stats](https://docs.rarebl.com/api/stats/live). The latest is replayed on subscribe. |
| `blocks:<chain>` | New blocks of a chain, for example `blocks:btc`. |
| `fees:<chain>` | Fee updates, for example `fees:eth`. |
| `address:<chain>:<address>` | Activity on an address. On BTC, LTC and BCH the address is **watched automatically**. |
| `tx:<chain>:<txid>` | Progress of a transaction, for example `tx:eth:0x…`. |
| `token:<chain>:<address>` | Token transfers to or from an address on ETH or TRON. |
| `token:<chain>:c:<contract>` | Token transfers of a contract on ETH or TRON. |
## Event types
`block.new`, `block.reorged`, `address.activity`, `tx.confirmations`, `tx.final`, `tx.dropped`, `tx.replaced`, `token.transfer`, `live` and `fees`. The `data` of each event follows the shapes in [Data types](https://docs.rarebl.com/data-types) and the webhook events in [Webhooks](https://docs.rarebl.com/guides/webhooks): read `type`, then treat `data` as the object for that kind of event.
## Limits
| Limit | Value |
| --- | --- |
| Connections | 3 per IP (the 4th is closed with code 1008) |
| Subscriptions | 200 channels per connection |
| Heartbeat | the server pings every 20 s; answer `{"op":"pong"}` |
| Slow clients | closed with code 1013 after 256 unacknowledged messages |
| Client messages | more than 60 in 10 s closes with 1008; frames are capped at 16 kB |
Reconnect with back-off after a drop, and resubscribe: subscriptions do not survive a dropped connection. A client that cannot keep up is disconnected rather than buffered without bound.
## Related
[Webhooks](https://docs.rarebl.com/guides/webhooks) for server-to-server delivery with retries; [Live stats](https://docs.rarebl.com/api/stats/live) to poll instead; [Rate limits](https://docs.rarebl.com/rate-limits) for the stream class.