# UTXO WebSockets

> Stream block, transaction, address, and fiat rate updates from Bitcoin Cash over a persistent WebSocket connection.

> For the complete documentation index, see [llms.txt](/docs/llms.txt).

The UTXO WebSockets API streams real-time events from Bitcoin Cash over a persistent connection, powered by [Trezor Blockbook](https://github.com/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](/docs/bitcoincash/utxo).

<Info>
  When the chain reorganizes, the server emits new block events for the new chain. You may see multiple events at the same height; treat the latest one as canonical.
</Info>

# Supported Networks

* `bitcoincash-mainnet`
* `bitcoincash-testnet`

# Connection

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

<CodeGroup>
  ```shell wscat
  wscat -c wss://bitcoincash-mainnet.g.alchemy.com/v2/{apiKey}
  ```
</CodeGroup>

Replace `{apiKey}` with your Alchemy API key from the [Alchemy Dashboard](https://dashboard.alchemy.com/). 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:

```json
{
  "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

<CodeGroup>
  ```shell wscat
  // open the websocket
  wscat -c wss://bitcoincash-mainnet.g.alchemy.com/v2/{apiKey}

  // then send the subscription
  {"id":"1","method":"subscribeNewBlock","params":{}}
  ```
</CodeGroup>

### Result

<CodeGroup>
  ```json result
  {"id":"1","data":{"subscribed":true}}

  {
    "id":"1",
    "data":{
      "height":860730,
      "hash":"000000000000000000a2b67ec3ea0b3a3a3a3b3a3a3a3a3a3a3a3a3a3a3a3a3a"
    }
  }
  ```
</CodeGroup>

## subscribeNewTransaction

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

<Info>
  This subscription is a high-volume firehose and requires the backend to be running with the `-enablesubnewtx` flag. It may not be enabled on all networks. If you do not receive events after subscribing, fall back to `subscribeAddresses` for targeted updates.
</Info>

### 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](https://github.com/trezor/blockbook/blob/master/docs/api.md#get-transaction) for the full field list.

### Request

<CodeGroup>
  ```shell wscat
  {"id":"2","method":"subscribeNewTransaction","params":{}}
  ```
</CodeGroup>

### Result

<CodeGroup>
  ```json 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"
    }
  }
  ```
</CodeGroup>

## 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

<CodeGroup>
  ```shell wscat
  {
    "id":"3",
    "method":"subscribeAddresses",
    "params":{
      "addresses":[
        "bitcoincash:qpm2qsznhks23z7629mms6s4cwef74vcwvy22gdx0",
        "bitcoincash:qq3vlashthktqpeppuv7trmw062vfqkfk5l6w0jcuv"
      ],
      "newBlockTxs":true
    }
  }
  ```
</CodeGroup>

### Result

<CodeGroup>
  ```json 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"
      }
    }
  }
  ```
</CodeGroup>

## 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

<CodeGroup>
  ```shell wscat
  {"id":"4","method":"subscribeFiatRates","params":{"currency":"usd"}}
  ```
</CodeGroup>

### Result

<CodeGroup>
  ```json result
  {"id":"4","data":{"subscribed":true}}

  {"id":"4","data":{"rates":{"usd":312.45}}}
  ```
</CodeGroup>

# Request methods

In addition to subscriptions, the WebSocket connection accepts the same one-shot requests as the [UTXO REST API](/docs/chains/bitcoincash/utxo-api-endpoints/utxo-api-endpoints). 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.

| Method                       | REST equivalent                                  | Description                                                       |
| ---------------------------- | ------------------------------------------------ | ----------------------------------------------------------------- |
| `getInfo`                    | `GET /api/`                                      | Backend and Blockbook status                                      |
| `getBlockHash`               | `GET /api/v2/block-index/{block_height}`         | Block hash for a given height                                     |
| `getAccountInfo`             | `GET /api/v2/address/{address}`, `/xpub/{xpub}`  | Balances and transactions for an address or xpub                  |
| `getAccountUtxo`             | `GET /api/v2/utxo/{descriptor}`                  | UTXOs for an address or xpub                                      |
| `getTransaction`             | `GET /api/v2/tx/{txid}`                          | Normalized transaction data                                       |
| `getTransactionSpecific`     | `GET /api/v2/tx-specific/{txid}`                 | Coin-specific raw transaction                                     |
| `getBalanceHistory`          | `GET /api/v2/balancehistory/{address}`           | Address balance history grouped by time                           |
| `estimateFee`                | n/a                                              | Fee estimate for a target confirmation depth                      |
| `sendTransaction`            | `POST /api/v2/sendtx/`                           | Broadcast a signed raw transaction                                |
| `getCurrentFiatRates`        | `GET /api/v2/tickers/`                           | Current fiat rates                                                |
| `getFiatRatesTickersList`    | `GET /api/v2/tickers-list/`                      | List of available fiat tickers for a timestamp                    |
| `getFiatRatesForTimestamps`  | n/a                                              | Historical fiat rates for specific timestamps                     |
| `getMempoolFilters`          | n/a                                              | Compact block filters for the mempool (for light clients)         |
| `getBlockFilter`             | n/a                                              | Compact block filter for a given block                            |
| `ping`                       | n/a                                              | Connection health check                                           |

For request and response payload shapes, see the [Trezor Blockbook WebSocket API reference](https://github.com/trezor/blockbook/blob/master/docs/api.md#websocket-api). 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](/docs/reference/best-practices-for-using-websockets-in-web3) for connection-management tips and [Compute Unit Costs](/docs/reference/compute-unit-costs) for billing details.

# See also

* [UTXO Overview](/docs/bitcoincash/utxo)
* [UTXO API Endpoints](/docs/chains/bitcoincash/utxo-api-endpoints/utxo-api-endpoints)
* [UTXO Migration Guide](/docs/bitcoin/utxo-migration-guide)