WebSockets

The Blockdeamon API Suite 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 the following:

• Block Identifiers
• Transactions

1. Supported Protocols

• Algorand
• Bitcoin
• Bitcoincash
• Dogecoin
• Ethereum
• Litecoin
• NEAR
• Optimism
• Polkadot
• Polygon
• Stellar
• Tezos
• XRP

2. URI Format

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

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

If you created your Blockdeamon API Suite API Key before September 2022, use the legacy URL:

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

2.1. Example

To connect to Ethereum Mainnet, use:

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

3. Authentication

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

--headers 'Authorization: Bearer YOUR_API_KEY'

4. Quick Start

Create a WebSockets 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.

5. 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.

5.1. Request

In your request, specify the following parameters:

• id (int64): request ID
• method: ubiquity.subscribe
• params:
  ├── channel: channel ID (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"}}

5.2. 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
    } 
}

6. 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 (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 to the same subscription or 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
                }
        ]
    }
}

7. Channels

The server returns different blockchain data depending on the channel you subscribe to. 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.

8. Block Identifiers

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

8.1. Content Example

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

9. Transactions

Channel ID: ubiquity.txs
Content: new transactions

9.1. 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"]}}}

📘

Note!

Assets associated with transactions are returned in the denomination field of the content.

9.2. 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...}
    ]
}

10. 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.

10.1. Request

In your request, specify the following parameters:

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

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

10.2. 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
    }
}

👋 Need Help?

Contact us through email or our support page for any issues, bugs, or assistance you may need.