The UTXO WebSockets API streams real-time events from Bitcoin Cash over a persistent connection, powered by Trezor Blockbook. Use it to push-subscribe to new blocks, new transactions, transactions affecting specific addresses, and fiat rate updates, with the same data shapes returned by the UTXO REST API.

Supported Networks

• bitcoincash-mainnet
• bitcoincash-testnet

Connection

Open a WebSocket connection using the standard Alchemy WebSocket URL for the network:

wscat -c wss://bitcoincash-mainnet.g.alchemy.com/v2/{apiKey}

Replace {apiKey} with your Alchemy API key from the Alchemy Dashboard. The WebSocket URL for an app uses the same host as its HTTPS URL, just with the wss:// scheme.

Message format

Every client message uses the following envelope:

{
  "id": "1",
  "method": "<request or subscription name>",
  "params": { ... }
}

• id: a client-chosen string. The server echoes it back on every response so you can correlate.
• method: the request method or subscription name.
• params: method-specific arguments. Use {} when none.

A connection can hold only one active subscription per event type. Sending a second subscribeAddresses replaces the previous address list. To stop receiving events, close the connection.

Subscriptions

subscribeNewBlock

Emits an event each time a new block is added to the chain.

Parameters

• None.

Response

• id: string - The id you sent on the request.
• data:
  • height: number - Block height.
  • hash: string - Block hash.

Request

// open the websocket
wscat -c wss://bitcoincash-mainnet.g.alchemy.com/v2/{apiKey}
 
// then send the subscription
{"id":"1","method":"subscribeNewBlock","params":{}}

Result

{"id":"1","data":{"subscribed":true}}
 
{
  "id":"1",
  "data":{
    "height":860730,
    "hash":"000000000000000000a2b67ec3ea0b3a3a3a3b3a3a3a3a3a3a3a3a3a3a3a3a3a"
  }
}

subscribeNewTransaction

Emits every new transaction added to the blockchain, across all addresses.

Parameters

• None.

Response

• id: string - The id you sent on the request.
• data: a transaction object using the same shape as GET /api/v2/tx/{txid}. See the Get transaction reference for the full field list.

Request

{"id":"2","method":"subscribeNewTransaction","params":{}}

Result

{"id":"2","data":{"subscribed":true}}
 
{
  "id":"2",
  "data":{
    "txid":"<bch txid>",
    "version":2,
    "vin":[
      {
        "txid":"<input txid>",
        "vout":1,
        "n":0,
        "addresses":["bitcoincash:qpm2qsznhks23z7629mms6s4cwef74vcwvy22gdx0"],
        "isAddress":true,
        "value":"10106300"
      }
    ],
    "vout":[
      {
        "value":"175000",
        "n":0,
        "addresses":["bitcoincash:qq3vlashthktqpeppuv7trmw062vfqkfk5l6w0jcuv"],
        "isAddress":true
      }
    ],
    "blockHeight":-1,
    "confirmations":0,
    "value":"10063100",
    "valueIn":"10106300",
    "fees":"43200"
  }
}

subscribeAddresses

Emits an event when a new transaction touches any of the supplied addresses. Optionally also emits when those transactions confirm in a new block.

Parameters

• addresses: string[] - One or more addresses to watch. Sending a new subscribeAddresses request replaces the previous list. Both CashAddr (bitcoincash:q...) and legacy (1...) formats are accepted.
• newBlockTxs: boolean (optional) - When true, also emits an event when a watched transaction is included in a new block, not just when it enters the mempool. Defaults to false.

Response

• id: string - The id you sent on the request.
• data:
  • Initial: { "subscribed": true }.
  • On each event: { "address": <string>, "tx": <Tx> } where Tx follows the same shape as GET /api/v2/tx/{txid}.

Request

{
  "id":"3",
  "method":"subscribeAddresses",
  "params":{
    "addresses":[
      "bitcoincash:qpm2qsznhks23z7629mms6s4cwef74vcwvy22gdx0",
      "bitcoincash:qq3vlashthktqpeppuv7trmw062vfqkfk5l6w0jcuv"
    ],
    "newBlockTxs":true
  }
}

Result

{"id":"3","data":{"subscribed":true}}
 
{
  "id":"3",
  "data":{
    "address":"bitcoincash:qpm2qsznhks23z7629mms6s4cwef74vcwvy22gdx0",
    "tx":{
      "txid":"<bch txid>",
      "vin":[
        {
          "n":0,
          "addresses":["bitcoincash:qpm2qsznhks23z7629mms6s4cwef74vcwvy22gdx0"],
          "isAddress":true,
          "value":"10106300"
        }
      ],
      "vout":[
        {
          "value":"175000",
          "n":0,
          "addresses":["bitcoincash:qq3vlashthktqpeppuv7trmw062vfqkfk5l6w0jcuv"],
          "isAddress":true
        }
      ],
      "blockHeight":-1,
      "confirmations":0,
      "value":"10063100",
      "fees":"43200"
    }
  }
}

subscribeFiatRates

Emits an event when the fiat rate ticker for the chain's native asset updates.

Parameters

• currency: string (optional) - Filter to a single fiat currency (e.g. "usd", "eur"). When omitted, the server emits all available currencies on each update.

Response

• id: string - The id you sent on the request.
• data:
  • Initial: { "subscribed": true }.
  • On each event: { "rates": { "<currency>": <number>, ... } }.

Request

{"id":"4","method":"subscribeFiatRates","params":{"currency":"usd"}}

Result

{"id":"4","data":{"subscribed":true}}
 
{"id":"4","data":{"rates":{"usd":312.45}}}

Request methods

In addition to subscriptions, the WebSocket connection accepts the same one-shot requests as the UTXO REST API. They are useful when you have already opened a connection for subscriptions and want to fetch ad-hoc data without a separate HTTP round-trip.

For request and response payload shapes, see the Trezor Blockbook WebSocket API reference. The payloads are the same as the REST API; only the connection layer differs.

WebSocket limits

The following limits apply to Alchemy WebSocket connections:

• 100 concurrent connections per app on the FREE tier; 2,000 on all other tiers.
• 1,000 unique subscriptions per connection.

See Best Practices for Using WebSockets for connection-management tips and Compute Unit Costs for billing details.

See also

• UTXO Overview
• UTXO API Endpoints
• UTXO Migration Guide