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/v1/{protocol}/{network}/websocket
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 (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 (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
}
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 (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
}
}