This guide provides Blockdaemon-specific JSON-RPC methods that extend [standard Bitcoin methods](https://docs.blockdaemon.com/reference/bitcoin-methods-rpc-api), with functionalities such as balance queries and transaction handling. These endpoints are available via our RPC API and return data in JSON-RPC format.

Bitcoin custom methods support the following networks:

- `mainnet`
- `testnet3` (referred to as testnet)
- `testnet4`

> 📘  
> See the [Bitcoin RPC API connection guide](https://docs.blockdaemon.com/docs/access-bitcoin-rpc).

* * *

## Balance API

### `bd_getbalances`

Returns confirmed (`trusted`) and mempool (`untrusted_pending`) balances for multiple Bitcoin addresses.

> 📘  
> ### Compute Unit Value  
> **5CU**

**Request Example**

```curl
{
  "jsonrpc": "1.0",
  "id": "curltest",
  "method": "bd_getbalances",
  "params": [
    [
      "bc1qaddress1...",
      "bc1qaddress2..."
    ]
  ]
}
```

**Request Parameter**

| Field | Type | Description |
| --- | --- | --- |
| `params`: Address | String | **(required)** One or more Bitcoin addresses. |

**Response Example**

```json
{
  "result": {
    "mine": {
      "trusted": "4535.02985542",
      "untrusted_pending": "4541.38229464"
    }
  }
}
```

**Response Object**

| Field | Type | Description |
| --- | --- | --- |
| `mine` | Object | Balances from outputs that the wallet can sign. |
| `trusted` | Int | Trusted balance (outputs created by the wallet or confirmed outputs) |
| `untrusted_pending` | Int | Untrusted pending balance (outputs created by others that are in the mempool) |

* * *

### `bd_getbalance`

Returns the balance for an address at the current block height, a specific height, or including mempool transactions.

> 📘  
> ### Compute Unit Value  
> **5 CU**

**Request Example**

Get balance at the latest block height

Get balance at a specific block height

Get balance including mempool transactions

```json
{
    "jsonrpc": "1.0",
    "id": "curltest",
    "method": "bd_getbalance",
    "params": [
        "bc1quhruqrghgcca950rvhtrg7cpd7u8k6svpzgzmrjy8xyukacl5lkq0r8l2d"
    ]
}
```

```json
{
    "jsonrpc": "1.0",
    "id": "curltest",
    "method": "bd_getbalance",
    "params": [
        "bc1quhruqrghgcca950rvhtrg7cpd7u8k6svpzgzmrjy8xyukacl5lkq0r8l2d", 900000
    ]
}
```

```json
{
    "jsonrpc": "1.0",
    "id": "curltest",
    "method": "bd_getbalance",
    "params": [
        "bc1quhruqrghgcca950rvhtrg7cpd7u8k6svpzgzmrjy8xyukacl5lkq0r8l2d", -1
    ]
}
```

**Request Parameters**

| Field | Type | Description |
| --- | --- | --- |
| `params`: Address | String | - _(required)_* Address to retrieve the balance for. |
| Balance Context | Int | - _(optional)_* Determines how the balance is calculated:<br>- If set to **`-1`**, the balance is computed considering mempool transactions.<br>- If set to a number **bigger than or equal to 0**, the balance for the given address is fetched at this block number.<br>- If **omitted**, the balance at the latest block height is fetched. |

**Response Example**

```json
{
    "id": "curltest",
    "result": "4535.02985542"
}
```

* * *

## Fees API

### `bd_estimatefee`

Estimates current fee rates for Bitcoin transactions.

> 📘  
> ### Compute Unit Value  
> **10 CU**

**Request Example**

```curl
{
    "jsonrpc": "1.0",
    "id": "curltest",
    "method": "bd_estimatefee",
    "params": ["sat/vb"]
}
```

**Request Parameter**

| Field | Type | Description |
| --- | --- | --- |
| Unit | String | - *(optional)* The unit of the fee rate, either `btc/kvb` or `sat/vb`. Defaults to `btc/kvb`. The unit is **case-insensitive**. |

**Response Example**

```json
{
    "id": "1",
    "result": {
        "fast_feerate": "28",
        "medium_feerate": "25",
        "slow_feerate": "17",
        "unit": "sat/vb"
    }
}
```

**Response Object**

| Field | Type | Description |
| --- | --- | --- |
| `fast_feerate` | Int | Fee rate (BTC/byte) for fastest confirmation. |
| `medium_feerate` | Int | Fee rate for medium-speed confirmation. |
| `slow_feerate` | Int | Fee rate for slower confirmation. |
| `unit` | String | The unit of the fee rate, either `btc/kvb` or `sat/vb`. Defaults to `btc/kvb`. |

* * *

## Transaction API

### `bd_listtransactions`

Retrieves transactions for a given address within a specified block range.

> 📘  
> ### Compute Unit Value  
> **10 CU**

**Request Example**

```curl
{
    "jsonrpc": "1.0",
    "id": "curltest",
    "method": "bd_listtransactions",
    "params": [
        "bc1q84e0f2qswgzth4tavedrv35f6fv9669ljww2ww", //address
        {
            "block_start": 850000,
            "block_end": 862810,
            "type": "all",
            "verbose": false,
            "page_size": 20,
            "page_token": "OTIyMzM3MjAzNjg1MzkxMzY5NCM1YmIyZWY3MjExYTgyNjE0ODkxZDAyNzQzYzUzYjZkNzU5ZTE2MmU2MTFiNGQxZjljMDYyOTM3YzdjMzdkNjA3",
            "order": "asc"
        }
    ]
}
```

**Request Parameter**

| Field | Type | Description |
| --- | --- | --- |
| `params`: Address | String | **(required)** Address to retrieve transactions for. |
| `block_start` | Int | **(optional)** Block height to start querying from. |
| `block_end` | Int | **(optional)** Block height to stop querying. |
| `type` | String | **(optional)** Transaction type: `all`, `inputs`, or `outputs`. Default: `all`. |
| `verbose` | Boolean | **(optional)** Whether to return detailed transaction information. Default: `false`. |
| `page_size` | Int | **(optional)** Number of results per page. |
| `page_token` | String | **(optional)** Token for paginated results. You can use this token in the request payload to get the next result. |
| `order` | String | **(optional)** Sorting order: `asc` or `desc`. Default: `desc`. |

**Response Example**

```json
{
    "id": "curltest",
    "result": {
        "transactions": [
            "74980dd4049324587471e266ff144f0d75d81f0f44767deaf6babdc9b8703c57",
            "08ba4c433016377851f2e5b4fdad14aa715cab8b2d6393828e1539775e5aabb2",
            "f594f9fbd52014308544030cdf154236b65f24b5ab832e5447fff1509decca9d"
        ],
        "page_token": "OTIyMzM3MjAzNjg1MzkxNzA2NSNmNTk0ZjlmYmQ1MjAxNDMwODU0NDAzMGNkZjE1NDIzNmI2NWYyNGI1YWI4MzJlNTQ0N2ZmZjE1MDlkZWNjYTlk"
    }
}
```

**Response Object**

| Field | Type | Description |
| --- | --- | --- |
| `transactions` | Array of strings | An array of transaction IDs. |
| `page_token` | String | Token for paginated results. You can use this token in the request payload to get the next result. |

* * *

### `bd_getspendingtx`

Checks if a TXO (transaction output) has been spent and returns the spending tx hash.

> 📘  
> ### Compute Unit Value  
> **5 CU**

**Request Example**

```curl
{
    "jsonrpc": "1.0",
    "id": "curltest",
    "method": "bd_getspendingtx",
    "params": [
        "b6127b392bd2e02971d7cdc416f16b9471530ac5fc3fd5cd5554a1093b31005c", 0
    ]
}
```

**Request Parameter**

| Field | Type | Description |
| --- | --- | --- |
| `params`: Address | `String` | **(required)** The transaction output (TXO) identifier, which includes the transaction hash and index. |

**Response Example**

If the TXO has been spent

```json
{
    "id": "curltest",
    "result": "d64a943e0c2035b7032c89e73c20ecf1596458fdca002600d8f450cebf69bbb0"
}
```

If the TXO is unspent or does not exist

```json
{
    "id": "curltest",
    "result": null
}
```

* * *

### `bd_listunspent`

Retrieves unspent outputs (UTXOs) for a given address.

> 📘  
> ### Compute Unit Value  
> **5 CU**

**Request Example**

```curl
{
    "jsonrpc": "1.0",
    "id": "curltest",
    "method": "bd_listunspent",
    "params": [
        "1HA1kDL993bdxvRH9KtrAh91Br4agzCYBt",
        {
            "include_mempool": true,
            "page_size": 100,
            "page_token": "OTIyMzM3MjAzNjg1MzkxMzY5NCM1YmIyZWY3MjExYTgyNjE0ODkxZDAyNzQzYzUzYjZkNzU5ZTE2MmU2MTFiNGQxZjljMDYyOTM3YzdjMzdkNjA3"
        }
    ]
}
```

**Request Parameters**

| Field | Type | Description |
| --- | --- | --- |
| `params`: Address | String \| Array of strings | **required** The address(es) to list UTXOs. |
| `include_mempool` | Boolean | **optional** Whether to include UTXOs from the mempool. |
| `page_size` | Int | **optional** The number of UTXOs to return per page. |
| `page_token` | String | **optional** Token for paginated results. You can use this token in the request payload to get the next result. |

**Response Example**

```json
{
    "id": "curltest",
    "result": {
        "data": [
            {
                "address": "138ky3HqkdEdJFqVqGwTGsQZGTZ2VyJw29",
                "index": 1,
                "mempool": false,
                "value": "0.00094262"
            },
            {
                "address": "13AbC9ufSMBaFeARs2YhAAQyU9dULcDmDp",
                "confirmations": 20957,
                "index": 133,
                "mempool": false,
                "ts": 1715993030,
                "txId": "59cdca9335dc720bcd32750e28a7d0808e483f5444cb3d256e38ca9e928149f8",
                "value": "0.00901766"
            },
           ......
        ],
        "page_token": "do#0000000000000000000000018aed923c250162fe3f058d6af0f3932d9d9aa08c#13gqBKGmRJc3gK7iysnjnK3oDcCcGo9mUH#721dd62c1ec80a604a0b0573092cd01928ed8e21f3c23a354284cdde1c1d47f6#1"
    }
}
```

**Response Object**

| Field | Type | Description |
| --- | --- | --- |
| `address` | String | The address associated with the UTXO. |
| `index` | Int | The index of the UTXO in the transaction. |
| `mempool` | Boolean | Indicates whether the UTXO is in the mempool. |
| `confirmations` | Int | The number of confirmations for the UTXO (if confirmed). |
| `ts` | Int | The timestamp of the transaction (if available). |
| `txId` | String | The transaction ID that created the UTXO. |
| `value` | String | The value of the UTXO in BTC or the respective currency. |

* * *

## Market Data API

### `bd_marketquote`

Returns the market price of BTC in one or more fiat currencies.

> 📘  
> ### Compute Unit Value  
> **10 CU**

**Request Example**

```curl
{
    "jsonrpc": "1.0",
    "id": "curltest",
    "method": "bd_marketquote",
    "params": [
        "USD" // currencies
    ]
}
```

**Request Parameter**

| Filed | Type | Description |
| --- | --- | --- |
| `params`: Currencies | Array of strings | **(required)** List of fiat currencies (e.g., USD, EUR, GBP). |

**Response Example**

```json
{
    "id": "curltest",
    "result": {
        "timestamp": 1727795820,
        "unit": "USD",
        "price": "62090.55536814973"
    }
}
```

**Response Object**

| Field | Type | Description |
| --- | --- | --- |
| `timestamp` | Int | The Unix timestamp when the price was retrieved. |
| `unit` | String | The fiat currency unit (e.g., USD). |
| `price` | String | The current price of BTC in the specified currency. |

* * *

## Blocks API

### `bd_getblockheaderbydate`

Returns basic block header information for a specified date.

> 📘  
> ### Compute Unit Value  
> **5 CU**

**Request Example**

```curl
{
    "jsonrpc": "1.0",
    "id": "curltest",
    "method": "bd_getblockheaderbydate",
    "params": [
        1725584753 // unix time
    ]
}
```

**Request Parameter**

| Filed | Type | Description |
| --- | --- | --- |
| `params`: Time | Int | **(required)** The Unix timestamp for the desired date. |

**Response Example**

```json
{
    "id": "curltest",
    "result": {
        "time": 1725584753,
        "height": 860072,
        "hash": "00000000000000000000e729cfc01f3300341d07f14f2a9aa45eb2a31d2cb9d3"
    }
}
```

**Response Object**

| Field | Type | Description |
| --- | --- | --- |
| `time` | Int | The Unix timestamp for the block header. |
| `height` | Int | The block height (number). |
| `hash` | String | The hash of the block header.