WebSocket API

The WebSocket-based API fuses batch processing and streaming capabilities to give you one single endpoint with strong guarantees.

Note

For get_action_traces and get_table_rows streams, we strongly suggest to use the GraphQL Subscription searchTransactionsForward instead of get_action_traces and get_table_rows. Main advantages of using the GraphQL API:

  • Possibility to also perform a paginated query instead of streaming.
  • Possibility to greatly reduce bandwidth transfer & cost (ingress to your server) by specifying the exact trimmed down data payload you need (excellent for browser & mobile usage).
  • A much cleaner interface to query by block range (lowBlockNum and highBlockNum instead of harder to reason about startBlock and blockCount)
  • On-the-fly ABI decode to JSON smart contract database rows that changed due to the execution of the transaction.

And it’s quite easy to convert them to a GraphQL streaming call.

Most operations can fetch a first state (with fetch: true), and can then stream subsequent changes (with listen: true).

All of our WebSocket stream supports the following common features:

  • req_id: multiplex multiple stream within a single WebSocket connection, identifying each of them uniquely
  • with_progress: allowing you to keep tabs on what you have seen up to the second
  • start_block: allowing you to restart from where you left off

Requests

Sample request message:

{
 "type": "[REQUEST_NAME]",
 "req_id": "some-string-of-your-choosing",
 "fetch": true,
 "listen": true,
 "start_block": -500,
 "irreversible_only": true,
 "with_progress": 5,
 "data": {...}
}

All requests are formed with these parameters, where type is the type of the request, and req_id is a token referred to by future commands (client or server).

Request Format

type
required
String     The type of the message.
type
required
Object     A free-form object, specific to the type of request.
req_id
Optional
String     An ID to associate responses back with the request, required if multiplexing multiple stream inside a single WebSocket connection.
fetch
Optional
Boolean    

Defaults to false. Whether to fetch an initial snapshot of the requested entity.

Warning

Only supported on get_table_rows and get_transaction.
listen
Optional
Boolean     Defaults to false. Whether to start listening on changes to the requested entity.
start_block
Optional
Number     Block at which you want to start processing. It can be an absolute block number, or a negative value, meaning how many blocks from the current head block on the chain. Ex: -2500 means 2500 blocks in the past, relative to the head block. 0 means the beginning of the chain. See the Using start_block section on usage pattern.
with_progress
Optional
Number     Frequency of the progress of blocks processing (within the scope of a req_id). See the Using with_progress section on usage pattern.
irreversible_only
Optional
Boolean    

Defaults to false. Limits output to events that happened in irreversible blocks.

Warning

Only supported on get_action_traces.

Responses

These are the messages you can receive from the server.

listening

{
  "type":"listening",
  "req_id": "your-request-id",
  "data":{
   "next_block":26736683
  }
}

Confirmation that server will continue processing block with height starting at next_block and emit more messages on current stream.

Use unlisten request to stop streaming for req_id

progress

{
 "type":"progress",
 "req_id": "your-request-id",
 "data": {
    "block_num": 29351730,
    "block_id": "01bfdf32469f6f48ca2e5e5c755422c7da0bbc33f1e470c034daffd460a2a58d"
 }
}

Confirmation that server will continue processing block with height starting at next_block and emit more messages on current stream.

Use unlisten request to stop streaming for req_id

error

{
  "type": "error",
  "data": {
   "code": "tx_not_found",
   "message": "transaction_lifecycle 'abcdef123123123...' not found, or error fetching transaction",
   "details": {"tx_id": "abcdef123123123..."}
  }
}

If an error occurs during the request, you’ll get an error response

ping

Once connected to the WebSocket, every 10 seconds, you get a ping response from the server.

Note

Please note that each ping response is billed as one document. 
{"type":"ping","data":"2018-01-01T00:00:10.526391919Z"}

Using with_progress

When you specify with_progress as part of the request message, you will start receiving messages of type progress when blocks arrive. The value you pass is interval of blocks you want to get that message, or the precision. A value of 5 means you will receive one progress message each 5 blocks. Set it to 1 to receive a message for each block.

For a given req_id stream, you are guaranteed to see the progress message after you have received any matching data within that block.

Also, you will receive one notification each 250 milliseconds at maximum. This means you will not get one progress message per block when doing massive historical reprocessing.

Warning

Even with a value of 1, it is possible that you do not get a message for each block, if there is a slight network congestion which brings two blocks within 250ms of propagation.

Using start_block

By specifying start_block, you can request that the stream of events starts in the past. You might need API keys that allow such reprocessing (until we have a self-serve portal, contact us if such is the case).

Possible values:

  • A negative value will start you in the past, relative to the current head block of the chain. Ex: -50 would start at block 25000100 if the head block was 25000150

  • A value of 0 means to start streaming at the head block, feeding real-time data through the socket.

  • A positive value will start at the given block. Ex: 10000 will start feeding (almost) the whole chain history into your socket. Contact us for keys with that feature enabled.

Standard keys can process 3600 blocks in the past by default.

Last modified February 18, 2024

 Edit this page