Connect
Authorization header on a WebSocket. A browser instead passes metastreams.v1 and a session token as subprotocols, and the server selects metastreams.v1. An API key is not accepted in the subprotocol list.
Browser
Channels
?marks an optional key, so{}matches every trade, transfer, candle or token, and…means the channel takes more keys. Each channel page lists all of them.spot.trades,spot.transfers,spot.candlesandspot.tokensshare one filter language, described in Filtering streams.spot.tokensalso sends anexitframe when a token stops matching.spot.tokensandspot.candlesacceptthrottleMsalongsidefilters, andspot.candlesalso acceptsmetric,denominationandclosedOnly.- No REST endpoint returns transfers. Every other
dataobject has the same shape as the matching REST response, with three exceptions. A streamed candle also includes itschain,token,poolandtimeframe. A streamed position has no price, sovalue,unrealizedPnl,totalPnl,pnlPctand everytokenfield exceptchainandaddressarenull. A streamed holder has norank.
Frames
Client messages
Server messages
- Use
subscriptionIdto route updates and to unsubscribe. The subscribe ack returns it, and every update includes it. - The ack for a subscription always arrives before its first update, and the ack for an unsubscribe arrives after that subscription’s last update.
Initial snapshot
A stream only sends changes that happen after you subscribe.spot.trending is the exception: its first update contains the full board. To build a complete view on any other channel:
- Subscribe and buffer the updates.
- Read the snapshot from the REST endpoint.
- Apply the buffered updates, and then each new update, on top of the snapshot.
A subscription survives a server-side interruption, but missed updates are not replayed and no frame marks the gap. If you need every row, also re-read the snapshot on a schedule.
Errors
When a frame is rejected, the server returns anerror frame with a REST error code, and the connection stays open.
The error includes the
id of the frame that caused it. It has no id when that frame is not JSON, has no string id, or is an unsubscribe.
Heartbeat
Send{"action": "ping"} about every 30 seconds. If you receive no pong within a few seconds, reconnect.
Close codes
Subscriptions do not survive a reconnect. Send your subscribe frames again, then fill the gap with a fresh snapshot.
Reconnection
The examples below resubscribe after every close. They reconnect immediately after1001, back off after any other close, and stop on 401, 402, 1008 or 4402. They connect with an API key. A browser client with a session token requests a new token from its backend and reconnects after a 1008 close with the reason token expired.