Skip to content

WebSockets⚓︎

To get live updates when an event occurs on the blockchain, Symbol publishes WebSockets.

Client applications can open a WebSocket connection and get a unique identifier. With this identifier, applications can subscribe to any of the available channels instead of needing to constantly poll the REST API for updates.

When an event occurs in a channel, the REST Gateway sends a notification to every subscribed client in real-time.

WebSocket URIs share the same host and port as the HTTP requests URIs, but use the ws:// protocol. The endpoint is /ws, for example: ws://localhost:3001/ws

Both outgoing subscription messages and incoming updates use the JSON format and are described next.

Warning

The WebSocket connection is dropped silently if idle for too long.

Channels are not automatically resubscribed on reconnection.

Response Format⚓︎

All channels share the same response format, which is:

Response body
{
    "topic": "{subscribed-channel}",
    "data": { ... }
}
  • topic contains the name of the subscribed channel, so the same websocket can be used to monitor multiple channels (topic matches the subscribe field provided in the request body when subscribing).
  • data is a channel-specific object. Each channel listed below describes the data object it returns.

Channels⚓︎

block⚓︎

block
Notifies subscribed clients every time a new block is created. Each returned message contains information about one block.
{
    "uid": "{uid}",
    "subscribe": "block"
}

BlockInfoDTO

finalizedBlock⚓︎

finalizedBlock
Notifies subscribed clients every time a set of blocks is . Each returned message contains information about the highest block in the finalization round. All blocks with a smaller height are assumed finalized.
    {
        "uid": "{uid}",
        "subscribe": "finalizedBlock"
    }

FinalizedBlockDTO

confirmedAdded⚓︎

ws:confirmedAdded/{address}
Notifies subscribed clients when a transaction related to the given address is included in a block. Each returned message contains information about one confirmed transaction.
{
    "uid": "{uid}",
    "subscribe": "confirmedAdded/{address}"
}

TransactionInfoDTO

unconfirmedAdded⚓︎

ws:unconfirmedAdded/{address}
Notifies subscribed clients when a transaction related to the given address enters the unconfirmed state, waiting to be included in a block. Each returned message contains information about one unconfirmed transaction.

Possible scenarios when this message is received are: a transaction is announced to the network via the /transactions PUT HTTP endpoint or a bonded aggregate transaction has all required cosigners and changes its state from partial to unconfirmed.

{
    "uid": "{uid}",
    "subscribe": "unconfirmedAdded/{address}"
}

TransactionInfoDTO

unconfirmedRemoved⚓︎

ws:unconfirmedRemoved/{address}
Notifies subscribed clients when a transaction related to the given address exits the unconfirmed state. Each returned message contains a no-longer-unconfirmed transaction hash.

Possible scenarios when this message is received are: the transaction is now confirmed, or the deadline was reached and the transaction was not included in a block.

{
    "uid":"{uid}",
    "subscribe":"unconfirmedRemoved/{address}"
}

Hash of the transaction.

partialAdded⚓︎

ws:partialAdded/{address}
Notifies subscribed clients when a bonded aggregate transaction related to the given address enters the partial state, waiting for all required cosignatures to complete. Each returned message contains information about one added partial transaction.
{
    "uid": "{uid}",
    "subscribe": "partialAdded/{address}"
}

TransactionInfoDTO

partialRemoved⚓︎

ws:partialRemoved/{address}
Notifies subscribed clients when a bonded aggregate transaction related to the given address exits the partial state. Each returned message contains one removed partial transaction hash.

Possible scenarios when this message is emitted are: all required cosignatures were received and the transaction is now unconfirmed, or the deadline was reached and the transaction was not included in a block.

{
    "uid": "{uid}",
    "subscribe": "partialRemoved/{address}"
}

Hash of the transaction.

cosignature⚓︎

ws:cosignature/{address}
Notifies subscribed clients when a cosignature related to the given address is added to a bonded aggregate transaction in the partial state. Each returned message contains one cosignature-signed transaction.
{
    "uid": "{uid}",
    "subscribe": "cosignature/{address}"
}

CosignatureDTO

status⚓︎

ws:status/{address}
Notifies subscribed clients when a transaction related to the given address signals an error. Each returned message contains one error message and a transaction hash.
{
    "uid": "{uid}",
    "subscribe": "status/{address}"
}

TransactionStatusDTO