Skip To Content

Blockdaemon Documentation

WebSockets

Overview
Supported Protocols
URI Format
Authentication
Quick Start
Subscribing to a Channel
Client-to-Server Notifications
Channels
Unsubscribing from a Channel

Overview

Ubiquity provides a WebSockets endpoint for streaming a live feed of blockchain data.

You can subscribe to the available channels and receive server-to-client notifications containing

Supported Protocols

URI Format

Use the following URI to connect to your chosen protocol via WebSockets:

wss://svc.blockdaemon.com/universal/v1/{protocol}/{network}/websocket

Note: If you created your Ubiquity API Key before September 2022, use the legacy Ubiquity URL:

wss://ubiquity.api.blockdaemon.com/v2/{protocol}/{network}/websocket

You can also use the Ubiquity V2 WebSockets endpoint:

wss://ubiquity.api.blockdaemon.com/v2/{protocol}/{network}/websocket

This endpoint is deprecated. Please migrate to V1.

Example

To connect to Ethereum Mainnet, use:

wss://svc.blockdaemon.com/universal/v1/ethereum/mainnet/websocket

Authentication

The WebSockets API requires authentication. This is achieved by setting the bearer token in the authorization header:

--headers 'Authorization: Bearer YOUR_API_KEY'

See also: Authentication Guide

Quick Start

Create a WebSocket connection with your preferred tool, for example websocket-client (python):

wsdump --headers 'Authorization: Bearer YOUR_API_KEY' wss://ubiquity.api.blockdaemon.com/v1/ethereum/mainnet/websocket

Send a request to subscribe to a channel with block identifiers:

{"id": 1, "method": "ubiquity.subscribe", "params": {"channel": "ubiquity.block_identifiers"}}

From then on, the server will return subscription notifications containing identifiers of new blocks.

Subscribing to a Channel

To subscribe to a channel, send a request containing the channel ID and other parameters.

The server will return a response with the subscription ID. Then it will asynchronously push notifications with blockchain data (their content depending on the selected channel).

It is possible to create multiple subscriptions.

Request

In your request, specify the following parameters:

id (int64): request ID
method: ubiquity.subscribe
params
├── channel: channel ID (blocks / block_identifiers / txs)
└── detail: filters by addresses and assets (available only for transactions)

For example, this request creates a subscription to identifiers of new blocks:

{"id": 1, "method": "ubiquity.subscribe", "params": {"channel": "ubiquity.block_identifiers"}}

Response

The server will return a response containing the subscription ID (subID). It is included in all notifications and is required for unsubscribing.

id (int64): request ID
result: on success
└── subID (int64): ID of the subscription
error: on failure

{
    "id": 1, 
    "result": { 
        "subID": 1
    } 
}

Server-to-Client Notifications

After a subscription is created, server-to client notifications are automatically triggered.

The client receives JSON objects with the following properties:

method: ubiquity.subscription
params
└── items
├── subID: subscription ID (previously returned by the server)
├── channel: channel ID (blocks / block_identifiers / txs)
├── revert (bool): whether an event got reverted (blockchain reorganization)
└── content: subscription content (depends on the channel)

Please note that one notification may contain several items, related either to the same subscription or to different ones.

This is an example of notifications for the channel with block identifiers:

{
    "method": "ubiquity.subscription",
    "params": {
        "items": [
            {
                "subID": 1,
                "channel": "ubiquity.block_identifiers",
                "revert": false,
                "content": {
                    "number": 14872378,
                    "id": "0xe5d988afdbb8b10e5e7fcfa9d375e7c5f0ca4931234c87a47bdeb8e8ac854c8d",
                    "parent_id": "0xd31b49be0174a30fb4f1c1265debf4c703511ff2c0b81bfbbe133075436b7d6e",
                    "date": 0,
                    "num_txs": 433
                }
        ]
    }
}

Channels

Depending on the channel you subscribe to, the server returns different blockchain data. It is shown in the params.items.content section of notifications.

Each channel has a channel ID, which you need to specify in the channel section of your subscription request.

Block Identifiers

Channel ID: ubiquity.block_identifiers
Content: identifiers of new blocks

Content Example


{
    "number": 14872378,
    "id": "0xe5d988afdbb8b10e5e7fcfa9d375e7c5f0ca4931234c87a47bdeb8e8ac854c8d",
    "parent_id": "0xd31b49be0174a30fb4f1c1265debf4c703511ff2c0b81bfbbe133075436b7d6e",
    "date": 0,
    "num_txs": 433
}

Blocks

Channel ID: ubiquity.blocks
Content: new blocks

Content Example


{
    "number": 14210527,
    "id": "0x2cca58803681fe5e1bc4ecee30b9227a66bdd55e014dcc95e7610cc5f1aeb636",
    "parent_id": "0x1490e2347a56375937588fa9c403e31440b9b843c0f75bfe8487bdabb0bdf7de",
    "date": 1644925705,
    "txs_ids": [ ... ],
    "txs": [ ... ]
}

Please note: this channel is currently supported only by the Ubiquity API V2.

If you are using Ubiquity V1, you can listen to block identifiers and then get blocks with the following Ubiquity REST API endpoint: GET Block by Number/Hash (V1)

You can also subscribe to transactions. For each transaction, its block hash and number are returned: see the block_id and block_number fields.

Transactions

Channel ID: ubiquity.txs
Content: new transactions

Request Parameters

In the detail section of the subscription request, you can specify additional parameters to filter transactions by given addresses and assets:

detail
├── addresses (array): list of addresses
└── assets (array): list of asset paths


{"id": 1, "method": "ubiquity.subscribe", "params":  {"channel": "ubiquity.txs", "detail": {"addresses": ["0xF5c6376D88033cfA67A442893F77cbC27A563Dd1"], "assets": ["ethereum/native/eth"]}}}

See also: Available Currencies and Tokens
Note: Assets associated with transactions are returned in the denomination field of the content.

Content Example


{
    "id": "0x0e12ac45c8695924b4388f8dd583db06f650c497d1f88131e1113ed9f1afc197",
    "block_id": "0xb293a98ea2f90b3ebe9bb304306fcacda696cc4b580671022aedb5fd676174d3",
    "date": 1653911704,
    "status": "completed",
    "num_events": 4,
    "block_number": 14872387,
    "events": [
        {
            "id": "0x0e12ac45c8695924b4388f8dd583db06f650c497d1f88131e1113ed9f1afc197-fee",
            "transaction_id": "0x0e12ac45c8695924b4388f8dd583db06f650c497d1f88131e1113ed9f1afc197",
            "type": "fee",
            "denomination": "ETH",
            "source": "0x60b86AF869f23aEb552fB7F3CaBD11B829f6Ab2F",
            "date": 1653911704,
            "amount": 5031848836797730,
            "decimals": 18
        },
        {...more events...}
    ]
}

Unsubscribing from a Channel

To cancel a previously created subscription, send a request containing the channel and subscription IDs.

The server will return a response confirming that the subscription is terminated. The client will no longer receive notifications.

Request

In your request, specify the following parameters:

id (int64): request ID
method: ubiquity.unsubscribe
params
├── channel: channel ID (blocks / block_identifiers / txs)
└── subID: subscription ID (previously returned by the server)


{"id": 2, "method": "ubiquity.unsubscribe", "params": {"channel": "ubiquity.txs", "subID": 1}}

Response

id (int64): request ID
result: on success
└── removed (bool): true if the subscription got removed, false if there is no subscription with the given subID
error: on failure

{ 
    "id": 2,
    "result": {
        "removed": true
    }
}

We don't support Internet Explorer

Please use Chrome, Safari, Firefox, or Edge to view this site.