Streaming events

Streaming events from Vega

Introduction

There are several streaming data APIs available on Vega. These include, but are not limited to: streaming trades, orders, positions, market data and events.

An event is an action or a side-effect that is triggered by a Vega node in response to a state change, for instance, starting of an auction or blockchain time updating. Events are streamed from something we refer to as an Event Bus.

Streaming events from the event bus APIs can provide rich real-time information to your client applications.

Events

Below is a table of all the event bus types that can be returned from a Vega Node:

Event type/code Description
BUS_EVENT_TYPE_ALL Receive events by ALL event types, used when filtering stream from event bus.
**NOTE: GraphQL API does not currently support subscribing to ALL events.**
See API reference for gRPC.
BUS_EVENT_TYPE_TIME_UPDATE (gRPC)
TimeUpdate (GraphQL)
Event for blockchain time updates.
See API reference for gRPC or GraphQL.
BUS_EVENT_TYPE_TRANSFER_RESPONSES (gRPC)
TransferResponses (GraphQL)
Event for when a transfer happens internally, contains the transfer information.
See API reference for gRPC or GraphQL.
BUS_EVENT_TYPE_POSITION_RESOLUTION (gRPC)
PositionResolution (GraphQL)
Event indicating position resolution has occurred.
See API reference for gRPC or GraphQL.
BUS_EVENT_TYPE_ORDER (gRPC)
Order (GraphQL)
Event for order updates, both new and existing orders.
See API reference for gRPC or GraphQL.
BUS_EVENT_TYPE_ACCOUNT (gRPC)
Account (GraphQL)
Event for account updates.
See API reference for gRPC or GraphQL.
BUS_EVENT_TYPE_PARTY (gRPC)
Party (GraphQL)
Event for party updates.
See API reference for gRPC or GraphQL.
BUS_EVENT_TYPE_TRADE (gRPC)
Trade (GraphQL)
Event indicating a new trade has occurred.
See API reference for gRPC or GraphQL.
BUS_EVENT_TYPE_MARGIN_LEVELS (gRPC)
MarginLevels (GraphQL)
Event indicating margin levels have changed for a party.
See API reference for gRPC or GraphQL.
BUS_EVENT_TYPE_PROPOSAL (gRPC)
Proposal (GraphQL)
Event for proposal updates (for governance).
See API reference for gRPC or GraphQL.
BUS_EVENT_TYPE_VOTE (gRPC)
Vote (GraphQL)
Event indicating a new vote has occurred (for governance).
See API reference for gRPC or GraphQL.
BUS_EVENT_TYPE_MARKET_DATA (gRPC)
MarketData (GraphQL)
Event for when market data updates.
See API reference for gRPC or GraphQL.
BUS_EVENT_TYPE_NODE_SIGNATURE (gRPC)
NodeSignature (GraphQL)
Event for a new signature for a Vega node.
See API reference for gRPC or GraphQL.
BUS_EVENT_TYPE_LOSS_SOCIALIZATION (gRPC)
LossSocialization (GraphQL)
Event indicating loss socialisation occurred for a party.
See API reference for gRPC or GraphQL.
BUS_EVENT_TYPE_SETTLE_POSITION (gRPC)
SettlePosition (GraphQL)
Event for when a position is being settled.
See API reference for gRPC or GraphQL.
BUS_EVENT_TYPE_SETTLE_DISTRESSED (gRPC)
SettleDistressed (GraphQL)
Event for when a position is distressed.
See API reference for gRPC or GraphQL.
BUS_EVENT_TYPE_MARKET_CREATED (gRPC)
MarketCreated (GraphQL)
Event indicating a new market was created.
See API reference for gRPC or GraphQL.
BUS_EVENT_TYPE_ASSET (gRPC)
Asset (GraphQL)
Event for when an asset is added to Vega.
See API reference for gRPC or GraphQL.
BUS_EVENT_TYPE_MARKET_TICK (gRPC)
MarketTick (GraphQL)
Event indicating a market tick event.
See API reference for gRPC or GraphQL.
BUS_EVENT_TYPE_WITHDRAWAL (gRPC)
Withdrawal (GraphQL)
Event for when a withdrawal occurs.
See API reference for gRPC or GraphQL.
BUS_EVENT_TYPE_DEPOSIT (gRPC)
Deposit (GraphQL)
Event for when a deposit occurs.
See API reference for gRPC or GraphQL.
BUS_EVENT_TYPE_AUCTION (gRPC)
Auction (GraphQL)
Event indicating a change in auction state, for example starting or ending an auction.
See API reference for gRPC or GraphQL.
BUS_EVENT_TYPE_RISK_FACTOR (gRPC)
RiskFactor (GraphQL)
Event indicating a risk factor has been updated.
See API reference for gRPC or GraphQL.
BUS_EVENT_TYPE_NETWORK_PARAMETER (gRPC) Event indicating a network parameter has been added or updated.
BUS_EVENT_TYPE_LIQUIDITY_PROVISION (gRPC)
LiquidityProvision (GraphQL)
Event indicating a liquidity provision commitment has been created or updated.
BUS_EVENT_TYPE_MARKET (gRPC)
Market (GraphQL)
Event indicating a market related event, for example when a market opens.
See API reference for gRPC or GraphQL.

Streaming from the event bus

The following example describes how to subscribe to and receive a stream of events using Vega’s APIs. Streaming is only supported on gRPC and GraphQL.

There are three request parameters that control the output on the stream from the Vega API:

Field Description
type Required field. An event type code (from table above), for example, to receive a stream with no filtering, specify BUS_EVENT_TYPE_ALL for gRPC (Note: ALL events not supported on GraphQL).

To receive only blockchain time updates, specify BUS_EVENT_TYPE_TIME_UPDATE for gRPC or TimeUpdate on GraphQL.

The event types are named differently to fit in with GraphQL conventions, please see the table above or the schema documentation for the full list.
batchSize Required field. The total number of events to batch up on the server before sending to the client. The default value is 0 which will send any and all events when they are available. If the client is not ready for the next data-set, data may be dropped a number of times, and eventually the stream will be closed.

For high traffic event types, it is advised to fine tune your client for receiving events, a good starting point is 5000 and then adjust this figure up or down based on real world results.
marketId Optional field. Specify a valid market identifier to receive events for this market only.
partyId Optional field. Specify a valid party identifier to receive events for this party only.

Connect to a Vega API server, and request to stream from the event bus:

Gitpod ready-to-code What’s Gitpod?

Make sure graphqurl is installed (from GitHub):

npm install -g graphqurl

This snippet code shows how to subscribe to ALL events for a particular market:

See also GraphQL API reference for further query detail.

Make sure vegaapiclient is installed (from PyPI):

pip install --upgrade Vega-API-client

This Python snippet code shows how to receive a stream of *ALL events for a particular market:

See also gRPC API reference for further query detail.

If successful, the response will include:

Field Description
events A list of zero or more events. If the BUS_EVENT_TYPE_ALL types filter is specified the type field returned in each event will give the event type code (see above), a unique identifier for the event in an id field and a payload which can be one of the data records associated with the type, for example, an Account for BUS_EVENT_TYPE_ACCOUNT or an AuctionEvent for BUS_EVENT_TYPE_AUCTION (see above). See example response (below) which shows different payloads for bus event types returned.
For full example code, please visit the repo on GitHub.

Are there any limitations to this API?

If you are looking to access streams of single data records such as orders, trades, positions etc. then please refer to the API reference documentation to stream the individual data source. Sample scripts for streaming orders and trades are available on GitHub.

As mentioned earlier, the GraphQL API does not currently support streaming BUS_EVENT_TYPE_ALL events, however this is fully supported by the gRPC API.

What’s next?