WebSocket streams
Vega's API contains WebSocket endpoints that offer real-time updates to changes in the state of the Vega network, allowing subscriptions to events such as per-market trades or changes to a party's position.
As Vega relies on a blockchain, time moves in discrete blocks and so updates will appear as blocks are executed.
Authentication and rate limiting
API tokens are not required to access the API as they are all public. TLS is supported on all WebSocket endpoints but note that whether it is enabled on a particular data node is a choice made by the data node's operator.
WebSocket connections are rate limited by a maximum allowed number of subscriptions per IP address. The default maximum is set to 250 connections, but note that this value may differ between data node operators.
Subscription to a WebSocket endpoint happens when the connection is opened and unsubscription occurs when the connection is closed. It is not necessary to send a request through the WebSocket to initiate the subscription or to prove the liveliness of the connection.
Subscribing using the WebSocket API
The tabs below show how to stream all ledger movements that occur on the Vega Fairground network using Bash, Python, and NodeJS.
- Bash
- Python
- Node
- Browser
curl -L -X GET 'https://api.n07.testnet.vega.xyz/api/v2/stream/ledger/movements'
import rel
import json
import websocket
url = "wss://api.n07.testnet.vega.xyz/api/v2/stream/ledger/movements"
def on_message(ws, message):
print(json.loads(message))
ws = websocket.WebSocketApp(
url=url,
on_message=on_message,
)
ws.run_forever(dispatcher=rel, reconnect=5)
rel.signal(2, rel.abort)
rel.dispatch()
// https://www.npmjs.com/package/ws
import { WebSocket } from 'ws';
const url = "wss://api.n07.testnet.vega.xyz/api/v2/stream/ledger/movements";
const client = new WebSocket(url);
client.on('message', message => {
console.log(message.toString());
});
const client = new WebSocket("wss://api.n07.testnet.vega.xyz/api/v2/stream/ledger/movements");
client.onmessage = console.dir;
The above examples show how to use WebSockets to stream all ledger movements that occur on the Vega Fairground network. An example payload is shown below:
{
"result": {
"ledgerMovement": {
"entries": [
{
"fromAccount": {
"assetId": "fBTC",
"type": 7,
"marketId": "0570e3ba31dda99bcaa78cf7c32fe97f3ec93c7a87ae6efd41fc524defa1bef2"
},
"toAccount": {
"assetId": "fBTC",
"type": 4,
"owner": "ee023a39d8c76b7c32b235f4620fb50cae2af3068368979c41eaeb519ce8d3fd"
},
"amount": "30",
"type": 10,
"timestamp": "1679568591503926199",
"fromAccountBalance": "31",
"toAccountBalance": "3999823695"
}
],
"balances": [
{
"account": {
"assetId": "fBTC",
"type": 4,
"owner": "ee023a39d8c76b7c32b235f4620fb50cae2af3068368979c41eaeb519ce8d3fd"
},
"balance": "30"
}
]
}
}
}
All enum values are sent as their integer values and not their string representation. This is to reduce the amount of data in each packet and for speedy performance.
Snapshots of data
Some of the WebSocket endpoints will send a snapshot of the current state of data when a connection is first made. This allows for an application to build an initial state, creating context for subsequent updates. The snapshot data will be sent in batches after which subsequent messages will only be updates to the snapshot state.
As an example, when streaming orders the current state of the order book will be sent first:
{
"result": {
"snapshot": {
"orders": [],
"lastPage": true
}
}
}
The last batch of snapshot data will have lastPage set to true after which the stream will switch to sending updates of the order book:
{
"result": {
"updates": {
"orders": []
}
}
}
Adding filters to subscriptions
Most of the WebSocket endpoints support filtering such as by-party or by-market. The filters are set as query parameters on the URL.
- Bash
- Python
- Node
- Browser
curl -L -X GET 'https://api.n07.testnet.vega.xyz/api/v2/stream/trades?api.n07.testnet.vega.xyz/api/v2/stream/trades?partyId?=faf83ce0533a2321ba2c0570844c631d4d888f6cc0e549e5222c1964ed764338'
import rel
import json
import websocket
url = "wss://api.n07.testnet.vega.xyz/api/v2/stream/trades?partyId?=faf83ce0533a2321ba2c0570844c631d4d888f6cc0e549e5222c1964ed764338"
def on_message(ws, message):
print(json.loads(message))
ws = websocket.WebSocketApp(
url=url,
on_message=on_message,
)
ws.run_forever(dispatcher=rel, reconnect=5)
rel.signal(2, rel.abort)
rel.dispatch()
import { WebSocket } from 'ws';
const url = "wss://api.n07.testnet.vega.xyz/api/v2/stream/trades?partyId?=faf83ce0533a2321ba2c0570844c631d4d888f6cc0e549e5222c1964ed764338";
const client = new WebSocket(url);
client.on('message', message => {
console.log(message.toString());
});
const client = new WebSocket("wss://api.n07.testnet.vega.xyz/api/v2/stream/trades?partyId?=faf83ce0533a2321ba2c0570844c631d4d888f6cc0e549e5222c1964ed764338");
client.onmessage = console.dir;
The above examples show how to use WebSockets to stream trades filtering on a partyId. The stream will only contain trades where buyer or seller matches faf83ce0533a2321ba2c0570844c631d4d888f6cc0e549e5222c1964ed764338.
All WebSocket APIs
The available WebSocket APIs are listed below.
| Description | Documentation | Call |
|---|---|---|
| Stream account details | Accounts | /api/v2/stream/accounts |
| Stream candles data | Candles | /api/v2/stream/candles/data |
| Stream liquidity provisions for a given market and party | Liquidity provisions | /api/v2/stream/liquidity-provisions |
| Stream margin levels for a given party (and optionally market) | Margin levels | /api/v2/stream/margin/levels |
| Stream data for given markets | Markets depth | /api/v2/stream/markets/depth |
| Stream updates of market depth for given markets | Markets depth updates | /api/v2/stream/markets/depth/updates |
| Stream data about given markets | Markets data | /api/v2/stream/markets/data |
| Stream all orders, or optionally for a given market and party | Orders | /api/v2/stream/orders |
| Stream all positions, or optionally for a given market and party | Positions | /api/v2/stream/positions |
| Stream all trades, or optionally for a given market and party | Trades | /api/v2/stream/trades |
| Stream governance proposals | Governance proposals | /api/v2/stream/governance |
| Stream governance votes for a party | Governance votes | /api/v2/stream/votes |