Skip to main content
A single WebSocket connection streams trades, transfers, candles, tokens, wallet balances, positions, holders, native prices and trending boards to you as they change.

Connect

Browsers cannot set the 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
Each session token has its own 20 connections, 20 subscriptions and 2,000 addresses, counted separately from its key. All the session tokens of one key share a limit of 10,000 open connections.

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.candles and spot.tokens share one filter language, described in Filtering streams.
  • spot.tokens also sends an exit frame when a token stops matching. spot.tokens and spot.candles accept throttleMs alongside filters, and spot.candles also accepts metric, denomination and closedOnly.
  • No REST endpoint returns transfers. Every other data object has the same shape as the matching REST response, with three exceptions. A streamed candle also includes its chain, token, pool and timeframe. A streamed position has no price, so value, unrealizedPnl, totalPnl, pnlPct and every token field except chain and address are null. A streamed holder has no rank.

Frames

Client messages

Server messages

  • Use subscriptionId to 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:
  1. Subscribe and buffer the updates.
  2. Read the snapshot from the REST endpoint.
  3. Apply the buffered updates, and then each new update, on top of the snapshot.
Repeat all three steps after every reconnect. Use the key and rule below to merge each object type.
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 an error 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 after 1001, 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.