Get Help

WebSockets API

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

WebSockets endpoints are available for all Blockdaemon support protocols.

How to Connect

To connect to WebSockets use the following code:

wss://ubiquity.api.blockdaemon.com/v2/{PROTOCOL}/{NETWORK}/websocket
e.g. wss://ubiquity.api.blockdaemon.com/v2/ethereum/mainnet/websocket

Quick Start

Create a WebSocket connection with your preferred tool.

wsdump
--headers 'Authorization: Bearer <token>'
wss://ubiquity.api.blockdaemon.com/v2/ethereum/mainnet/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",
  ...
}