Skip to main content

Subscribe request format

Subscribe requests must be sent as JSON in text frames, one request per frame.

Example of subscribe request​


_10
{
_10
"subscription_id": "some-id-1",
_10
"action": "subscribe",
_10
"topic": "block_digests",
_10
"arguments": {
_10
"block_status": "finalized",
_10
"start_block_height": "99416580"
_10
}
_10
}

Example of successful response​


_10
{
_10
"subscription_id": "some-id-1",
_10
"action": "subscribe"
_10
}

Example of failed response​


_10
{
_10
"subscription_id": "some-id-1",
_10
"error": {
_10
"code": 400,
_10
"message": "invalid message"
_10
}
_10
}

Example of messages provided by subscription (if successful)​


_10
{
_10
"subscription_id": "some-id-1",
_10
"topic": "block_digests",
_10
"payload": {
_10
"id": "0x1234...",
_10
"height:": "123456789",
_10
"timestamp": "2025-01-02T10:00:00Z"
_10
}
_10
}

Example of messages provided by subscription (if error)​


_10
{
_10
"subscription_id": "some-id-1",
_10
"error": {
_10
"code": 500,
_10
"message": "internal error"
_10
}
_10
}

Request fields:​

NameTypeRequiredDescription
subscription_idSTRINGNOOptional unique identifier for the subscription. Max length of ID generated by client is 20 characters. Server will generate a unique ID if omitted
actionSTRINGYESAction to perform. Must be subscribe to initiate a subscription
topicSTRINGYESThe topic to subscribe to, such as blocks, block_digests, etc. See more details on Supported Topics page.
argumentsSTRINGNOAdditional topic specific parameters for the subscription, such as start_block_id, start_block_height or other.

You can use subscription_id as a client-generated identifier to track responses asynchronously. If you don't provide subscription_id, the server will generate one and include it in the response.

Rate this page