Ubiquity WebSockets API

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

It is currently available for the bitcoin, ethereumstellar and xrp platforms:

  1. wss://ubiquity.api.blockdaemon.com/v2/bitcoin/websocket

  2. wss://ubiquity.api.blockdaemon.com/v2/ethereum/websocket

  3. wss://ubiquity.api.blockdaemon.com/v2/xrp/websocket

  4. wss://ubiquity.api.blockdaemon.com/v2/stellar/websocket

Quick Start

Create a WebSocket connection with your preferred tool.

wsdump \
--headers 'Authorization: Bearer <token>' \
wss://ubiquity.api.blockdaemon.com/v2/ethereum/websocket/

Subscribe to new block notifications.

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

From then on, the server will return subscription notifications for new blocks.

Protocol

The WebSockets API requires authentication, by setting the Authorization header to Bearer <token>.

Client-to-server requests

Subscribe to channel

Creates a new subscription to a channel, after which the server will asynchronously push subscription notifications to the client.

Request

  • id (int64)Request ID

  • method: ubiquity.subscribe

  • params

    • channelChannel ID to subscribe

    • detailSubscription details

{
"id": 1,
"method": "ubiquity.subscribe",
"params": {
"channel": "ubiquity.txs",
"detail": {
"addresses": ["0x123"]
}
}
}

Response

  • id (int64): Request ID

  • result: On success

    • subID (int64): ID of newly created subscription

  • error: On failure

{
"id": 1,
"result": {
"subID": 123
}
}
Unsubscribe from channel

Terminates an existing subscription.

Request

  • id (int64)Request ID

  • method: ubiquity.subscribe

  • params

    • subIDSubscription ID

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

Response

  • id (int64): Request ID

  • result: On success

    • removed (bool): Whether subscription got removed, false if subscription at subID does not exist.

  • error: On failure

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

Server-to-client notifications

The server sends asynchronous notifications to the client for existing subscriptions.

  • method: ubiquity.subscription

  • params

    • items (array)

      • subIDSubscription ID

      • channel: Channel ID to subscribe

      • revertWhether event got reverted (blockchain reorganization)

      • content: Subscription content

{
"method": "ubiquity.subscription",
"params": {
"items": [
{
"subID": 1,
"channel": "ubiquity.block_identifiers",
"revert": false,
"content": {
"number": 11113299,
"id": "0x910daa8859d98bb683cdca5073bf8daabc70d3bef09ddab4d2b8b7a581e00572",
"parent_id": "0x43d2f3b139b3fff59d378c74aa3695ad0edb2664e69b155e8538545c050643e1"
}
}
]
}
}

Channels

Block identifiers

Channel with identifiers of new blocks.

Subscription params

  • channel: "ubiquity.block_identifiers"

Subscription results

Instance of types.BlockIdentifier

{
"number": 11114376,
"id": "0xee98e96146a980e9fdebbaca0aff6cb727f3ec3efe18d377597aaf7cf00502cb",
"parent_id": "0xb491092a8cd2b6689b42d87c76697c1729c9141054af9d4bd810ba6d8e82d86e"
}

Blocks

Channel of new blocks.

Subscription params

  • channel: "ubiquity.blocks"

Subscription results

Instance of types.Block

{
"number": 11114376,
"id": "0xee98e96146a980e9fdebbaca0aff6cb727f3ec3efe18d377597aaf7cf00502cb",
"parent_id": "0xb491092a8cd2b6689b42d87c76697c1729c9141054af9d4bd810ba6d8e82d86e",
"txs": [...]
}

Transactions

Channel of new transactions.

Subscription params

  • channel: "ubiquity.txs"

  • detail

    • addresses: List of addresses to filter for

    • assets: List of assets to filter for

Subscription results

Instance of types.Tx

{
"id": "0e3e2357e806b6cdb1f70b54c3a3a17b6714ee1f0e68bebb44a74b1efd512098",
"slip44": 0,
"addresses": [
"12c6DSiU4Rq3P4ZxziKxzrL5LmMBrzjrJX",
"coinbase"
],
"assets": ["bitcoin/native/btc"],
"date": 1231469665,
"height": 1,
"block_id": "00000000839a8e6886ab5951d76f411475428afc90947ee320161bbf18eb6048",
...
}