Skip to main content

Websockets Stream API

Overview​

The Stream API allows clients to receive real-time updates from the Flow blockchain via WebSocket connections. It supports subscribing to various topics, such as blocks, events, and transactions, enabling low-latency access to live data.

Important Information​

  • Endpoint: The WebSocket server is available at:

    _10
    wss://api.flow.com/ws

  • Limits:
    • Each connection supports up to 50 concurrent subscriptions. Exceeding this limit will result in an error.
    • TODO: list all limits here
  • Supported Topics:
    • blocks
    • block_headers
    • block_digests
    • events
    • transaction_statuses
    • account_statuses
  • Notes: Always handle errors gracefully and close unused subscriptions to maintain efficient connections.

Setting Up a WebSocket Connection​

Use any WebSocket client library to connect to the endpoint. Below is an example using JavaScript:


_13
const ws = new WebSocket('wss://api.flow.com/ws');
_13
_13
ws.onopen = () => {
_13
console.log('Connected to WebSocket server');
_13
};
_13
_13
ws.onclose = () => {
_13
console.log('Disconnected from WebSocket server');
_13
};
_13
_13
ws.onerror = (error) => {
_13
console.error('WebSocket error:', error);
_13
};

Subscribing to Topics​

To receive data from a specific topic, send a subscription request in JSON format over the WebSocket connection.

Request Format​


_10
{
_10
"subscription_id": "some-uuid-42",
_10
"action": "subscribe",
_10
"topic": "blocks",
_10
"arguments": {
_10
"start_block_height": "123456789"
_10
}
_10
}

  • subscription_id: A unique identifier for the subscription (UUID string). If omitted, the server generates one.
  • action: The action to perform. Supported actions include: subscribe, unsubscribe, list_subscriptions.
  • topic: The topic to subscribe to. See the supported topics in the Overview.
  • arguments: Additional arguments for subscriptions, such as start_block_height, start_block_id, and others.

Response Format​


_10
{
_10
"subscription_id": "some-uuid-42"
_10
}

Unsubscribing from Topics​

To stop receiving data from a specific topic, send an unsubscribe request.

Request Format​


_10
{
_10
"subscription_id": "some-uuid-42",
_10
"action": "unsubscribe"
_10
}

Response Format​


_10
{
_10
"subscription_id": "some-uuid-42"
_10
}

Listing Active Subscriptions​

You can retrieve a list of all active subscriptions for the current WebSocket connection.

Request Format​


_10
{
_10
"action": "list_subscriptions"
_10
}

Response Format​


_16
{
_16
"subscriptions": [
_16
{
_16
"subscription_id": "uuid-1",
_16
"topic": "blocks",
_16
"arguments": {
_16
"start_block_height": "123456789"
_16
}
_16
},
_16
{
_16
"subscription_id": "uuid-2",
_16
"topic": "events",
_16
"arguments": {}
_16
}
_16
]
_16
}

Errors Example​

If a request is invalid or cannot be processed, the server responds with an error message.

OK Response​


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

Error Response​


_10
{
_10
"subscription_id": "some-uuid-42",
_10
"error": {
_10
"code": 500,
_10
"message": "Access Node failed"
_10
}
_10
}

Common Error Codes​

  • 400: Invalid message format or arguments
  • 404: Subscription not found
  • 500: Internal server error

Asynchronous environments​

If you're working in an asynchronous environment, our Stream API ensures in-order message delivery. You can leverage this feature to simplify your code and maintain consistency.

Additionally, you can use the subscription_id as a message identifier to manage subscriptions effectively.

Rate this page