Events API
The Events API provides streams of real-time events in different channels over WebSocket and Sever-Sent-Event transports. Events can be used to observe activity on addresses and smart contracts, listen for new blocks, new and finalized operations or other network events like chain reorganizations. The Events API is subject to the same free call limits and fee schedule as other TzPro APIs. Each delivered event message counts the same way as a REST API call.
To receive event messages you need to subscribe to one or more channels. Subscription method and message framing depend on the transport protocol as described below. Each channel carries a specific message type and allows you to install an event filter to limit the amount of forwarded messages. The following channels are supported
- block hashes – hashes of new appended blocks
- blocks – full block detail in the same format as blocks on the Explorer API
- operation hashes – hashes of operations found in new blocks
- operations – full operation detail in the same format as operations on the Explorer API
- pending operation hashes – hashes of new operations entering the mempool
- pending operations – full operation detail of new operations entering the mempool
- head – short info about the latest block appended to the main chain
- status – indexer and upstream Tezos node status updates
- tickers – market price tickers
Messages are encoded in JSON format and share some common header fields to uniquely identify their type and position in the event stream as well as a type specific message body. Message headers differ between transports, but in general, they contain the following info
- a unique message id that can be used for gap-free message replay after client disconnect
- an event type which is either
data,errororstatus
As long as the chain makes forward progress new event messages are sent over a channel in order of on-chain appearance. During chain reorganizations, side chain data is rolled back in reverse order first, before new main chain data is appended in forward order. We either add a
rollback=true field to the message header (WebSocket API) or send rollback as event type (SSE API) when an event was part of a rollback.The API supports gap-free replay of the most recent message history in case a client went offline and reconnects shortly thereafter (within the next 100 blocks). Each message contains a unique
message_id that can be used as cursor into the event stream. When reconnecting (re-subscribing) simply add the last seen message id and the API will respond with the most recent messages immediately following this id. In case the last message was part of a chain reorganization and the related block is no longer part of the main chain, the API will return an error instead. In this case client state should be re-synchronized using the REST API.The
operation* and ticker channels support additional message filters to limit the amount of data. You may use filters to subscribe to events from specific operation types, addresses, entrypoints or trading pairs. Filters are optional and when set they form a logical AND across fields that are defined. It's possible to express a logical OR by adding multiple comma-separated values to a filter field. Field | Comment |
|---|---|
type enum | Comma separated list of operation types. |
address hash | Comma separated list of addresses appearing as operation sender, receiver, creator or delegate. |
entrypoint string | Comma separated list of smart contract call entrypoints. |
market string | Comma separated list of exchanges for market tickers. |
pair string | Comma separated list of trading pairs for market tickers. |
Filter examples
type=transaction– matches all transaction operationstype=transaction&entrypoint=mint– matches all smart contract calls to entrypoint mint regardless of sender or receiveraddress=A,B– will match all operations where either address A or B is presentmarket=coinbasepro&pair=xtz_usd– matches tickers from the XTZ/USD market on Coinbase
Last modified 3mo ago