LLM Notice: This documentation site supports content negotiation for AI agents. Request any page with Accept: text/markdown or Accept: text/plain header to receive Markdown instead of HTML. Alternatively, append ?format=md to any URL. All markdown files are available at /md/ prefix paths. For all content in one file, visit /llms-full.txt
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:

    • Mainnet: wss://rest-mainnet.onflow.org/v1/ws
    • Testnet: wss://rest-testnet.onflow.org/v1/ws

  • Limits:

    • Each connection supports up to 20 concurrent subscriptions. Exceeding this limit will result in an error.
    • Each subscription may provide up to 20 responses per second.
    • After 1 minute of inactivity (no data sent or received) the connection is closed.

  • Supported Topics: See more details on Supported Topics page.

  • 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://rest-mainnet.onflow.org/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-id-42",
_10
"action": "subscribe",
_10
"topic": "blocks",
_10
"arguments": {
_10
"block_status": "sealed",
_10
"start_block_height": "123456789"
_10
}
_10
}

  • subscription_id(optional): A unique identifier for the subscription (a string with maximum length constraint of 20 characters). 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 topic specific arguments for subscriptions, such as start_block_height, start_block_id, and others. See more details about arguments for each topic on Supported Topics page.

Successful Response Format​


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

Unsubscribing from Topics​

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

Request Format​


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

Successful Response Format​


_10
{
_10
"subscription_id": "some-id-42",
_10
"action": "unsubscribe"
_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
}

Successful Response Format​


_17
{
_17
"subscriptions": [
_17
{
_17
"subscription_id": "some-id-1",
_17
"topic": "blocks",
_17
"arguments": {
_17
"block_status": "sealed",
_17
"start_block_height": "123456789"
_17
}
_17
},
_17
{
_17
"subscription_id": "some-id-2",
_17
"topic": "events",
_17
"arguments": {}
_17
}
_17
]
_17
}

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-id-42",
_10
"topic": "block_digests",
_10
"payload": {
_10
"id": "0x1234...",
_10
"height:": "123456789",
_10
"timestamp": "2025-01-02T10:00:00Z"
_10
}
_10
}

Error Response​


_10
{
_10
"subscription_id": "some-id-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, the Streaming API ensures first-in first-out message processing, so responses will be returned in the same order the requests were received over the connection. You can leverage this feature to simplify your code and maintain consistency.

Additionally, you can specify a custom subscription_id in the subscribe request to easily identify the correct response. It must not be an empty string and must follow a maximum length constraint of 20 characters.

Rate this page