Reference
SupportStatus

Bitcoin Custom Methods

This guide provides Blockdaemon-specific JSON-RPC methods that extend standard Bitcoin methods, 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.

Stats API

bd_stats

Returns some stats for an address.

Request Example

{
  "jsonrpc": "2.0",
  "id": "curltest",
  "method": "bd_stats",
  "params": [
      "bc1quhruqrghgcca950rvhtrg7cpd7u8k6svpzgzmrjy8xyukacl5lkq0r8l2d"
  ]
}

Request Parameter

FieldTypeDescription
params: AddressString(required) A Bitcoin address.

Response Example

{
    "jsonrpc": "2.0",
    "id": "curltest",
    "result": {
        "txcount": {
            "confirmed": 2368,
            "unconfirmed": 0
        },
        "balances": {
            "confirmed": 86.70246607,
            "unconfirmed": 86.70246607
        },
        "utxos": {
            "confirmed": 114,
            "pending": 0
        }
    }
}

Response Object

FieldTypeDescription
txcountObjectShows the number of transactions associated, confirmed and unconfirmed.
balancesObjectIndicates the total balance, confirmed and unconfirmed.
utxosObjectShows the number of UTXOs, confirmed and unconfirmed.

Balance API

bd_getbalances

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


Compute Unit Value: 5 CU

Request Example

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

Request Parameter

FieldTypeDescription
params: AddressString(required) One or more Bitcoin addresses.

Response Example

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

Response Object

FieldTypeDescription
mineObjectBalances from outputs that the wallet can sign.
trustedIntTrusted balance (outputs created by the wallet or confirmed outputs)
untrusted_pendingIntUntrusted 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

{
    "jsonrpc": "1.0",
    "id": "curltest",
    "method": "bd_getbalance",
    "params": [
        "bc1quhruqrghgcca950rvhtrg7cpd7u8k6svpzgzmrjy8xyukacl5lkq0r8l2d"
    ]
}
{
    "jsonrpc": "1.0",
    "id": "curltest",
    "method": "bd_getbalance",
    "params": [
        "bc1quhruqrghgcca950rvhtrg7cpd7u8k6svpzgzmrjy8xyukacl5lkq0r8l2d", 900000
    ]
}
{
    "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:
  • If set to -1, the balance is computed considering mempool transactions.
  • If set to a number bigger than or equal to 0, the balance for the given address is fetched at this block number.
  • If omitted, the balance at the latest block height is fetched.

Response Example

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

bd_getbalanceatheight

Returns a balance object for the given address at the given height (or latest if no height provided).

Request Example

{
    "jsonrpc": "2.0",
    "id": "curltest",
    "method": "bd_getbalanceatheight",
    "params": [
        "tb1pwv6xu5xlv0puqdpxr2xjslh0mezm00cpcpnaq2ux77nqlxered9skmgty7", 4254432
    ]
}

Request Parameter

FieldTypeDescription
params: AddressString(required) Bitcoin address.
params: Block HeightInt(optional) The block height of the address.

Response Example

{
    "jsonrpc": "2.0",
    "id": "curltest",
    "result": {
        "address": "tb1pwv6xu5xlv0puqdpxr2xjslh0mezm00cpcpnaq2ux77nqlxered9skmgty7",
        "amount": 355524.310602360,
        "blockheight": 4254432
    }
}

Response Object

FieldTypeDescription
addressStringThe Bitcoin address queried.
amountIntThe balance as of the last block the address was active in.
blockheightIntThe block number at which this balance was last updated.

Transaction API

bd_listtransactions

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


Compute Unit Value: 10 CU

Request Example

{
    "jsonrpc": "1.0",
    "id": "curltest",
    "method": "bd_listtransactions",
    "params": [
        "bc1q84e0f2qswgzth4tavedrv35f6fv9669ljww2ww", //address
        {
            "block_start": 850000, 
            "block_end": 862810,   
            "from": 0,
            "to": 1000000000,
            "type": "all",       
            "verbose": false,   
            "page_size": 20,
            "page_token": "OTIyMzM3MjAzNjg1MzkxMzY5NCM1YmIyZWY3MjExYTgyNjE0ODkxZDAyNzQzYzUzYjZkNzU5ZTE2MmU2MTFiNGQxZjljMDYyOTM3YzdjMzdkNjA3",
            "order": "asc",
            "exclusive": true,
            "mempool": false
        }
    ]
}

Request Parameter

FieldTypeDescription
params: AddressString(required) Address to retrieve transactions for.
block_startInt(optional) Block height to start querying from.
block_endInt(optional) Block height to stop querying.
fromInt(optional) Timestamp to start looking for transactions from.
toInt(optional) Timestamp to stop looking for transactions at.
typeString(optional) Transaction type: all, inputs, or outputs. Default: all.
verboseBoolean(optional) Whether to return detailed transaction information. Default: false.
page_sizeInt(optional) Number of results per page.
page_tokenString(optional) Token for paginated results. You can use this token in the request payload to get the next result.
orderString(optional) Sorting order: asc or desc. Default: desc.
exclusiveBoolean(optional) Whether to exclude transactions on the start/end boundaries.
mempoolBoolean(optional) Whether to include mempool transactions.

Response Example

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

Response Object

FieldTypeDescription
transactionsArray of stringsAn array of transaction IDs.
page_tokenStringToken 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

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

Request Parameter

FieldTypeDescription
params: AddressString(required) The transaction output (TXO) identifier, which includes the transaction hash and index.

Response Example

{
    "id": "curltest",
    "result": "d64a943e0c2035b7032c89e73c20ecf1596458fdca002600d8f450cebf69bbb0"
}
{
    "id": "curltest",
    "result": null
}

bd_listunspent

Retrieves unspent outputs (UTXOs) for a given address.


Compute Unit Value: 5 CU

Request Example

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

Request Parameters

FieldTypeDescription
params: AddressString | Array of stringsrequired The address(es) to list UTXOs.
include_mempoolBooleanoptional Whether to include UTXOs from the mempool.
page_sizeIntoptional The number of UTXOs to return per page.
page_tokenStringoptional Token for paginated results. You can use this token in the request payload to get the next result.

Response Example

{
    "jsonrpc": "1.0",
    "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

FieldTypeDescription
addressStringThe address associated with the UTXO.
indexIntThe index of the UTXO in the transaction.
mempoolBooleanIndicates whether the UTXO is in the mempool.
confirmationsIntThe number of confirmations for the UTXO (if confirmed).
tsIntThe timestamp of the transaction (if available).
txIdStringThe transaction ID that created the UTXO.
valueStringThe value of the UTXO in BTC or the respective currency.

bd_gettxcount

Returns a count of confirmed and pending transactions for a given address.

Request Example

{
    "jsonrpc": "2.0",
    "id": "curltest",
    "method": "bd_gettxcount",
    "params": [
        "bc1quhruqrghgcca950rvhtrg7cpd7u8k6svpzgzmrjy8xyukacl5lkq0r8l2d", true
    ]
}

Request Parameter

FieldTypeDescription
params: AddressString(required) Bitcoin address.
params: MempoolBoolean(optional) Indicator to include mempool, defaults to true.

Response Example

{
    "jsonrpc": "2.0",
    "id": "curltest",
    "result": {
        "confirmed": 511779,
        "unconfirmed": 0
    }
}

Response Object

FieldTypeDescription
confirmedIntNumber of confirmed transactions for the given address.
unconfirmed IntNumber of unconfirmed transactions for the given address.

Blocks API

bd_getblockheaderbydate

Returns basic block header information for a specified date.


Compute Unit Value: 5 CU

Request Example

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

Request Parameter

FieldTypeDescription
params: TimeInt(required) The Unix timestamp for the desired date.

Response Example

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

Response Object

FieldTypeDescription
timeIntThe Unix timestamp for the block header.
heightIntThe block height (number).
hashStringThe hash of the block header.

bd_getblockbyheight

Gets a Bitcoin block by height.

Request Example

{
    "jsonrpc": "2.0",
    "id": "curltest",
    "method": "bd_getblockbyheight",
    "params": [
        123456, 1 
    ]
}

Request Parameter

Field

Type

Description

params: Block Height

Int

(required) The block height.

params: Verbosity

Int

(optional) Verbosity level.

  • 0: Returns hex-encoded serialized block.
  • 1: Returns an object with information.
  • 2: Returns an object with information and information about each transaction.

Response Example

{
  "jsonrpc": "2.0",
  "id": "curltest",
  "result": {
    "hash": "000000000003ba27aa200b1cecaad478d2b00432346c3f1f3986da1afd33e506",
    "confirmations": 789456,
    "size": 411264,
    "strippedsize": 289456,
    "weight": 1123456,
    "height": 123456,
    "version": 1,
    "versionHex": "00000001",
    "merkleroot": "d4e5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5",
    "tx": [
      "d4e5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5",
      "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
    ],
    "time": 1293623863,
    "mediantime": 1293622583,
    "nonce": 2951971998,
    "bits": "1b04864c",
    "difficulty": 14484.16432328,
    "chainwork": "0000000000000000000000000000000000000000000000000043b42a2a1a4d00",
    "nTx": 128,
    "previousblockhash": "000000000002d01d2ac4a86b4c4c950b0ea8b0c0a0b1c2d3e4f5a6b7c8d9e0f1",
    "nextblockhash": "000000000002d1a4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8"
  }
}

Response Object

FieldTypeDescription
hashStringThe block hash.
confirmationsIntNumber of confirmations.
sizeIntThe block size in bytes.
strippedsizeIntThe block size excluding witness data.
weightIntThe block weight.
heightIntThe block height.
versionIntThe block version number.
versionHexstringThe block version formatted in hexadecimal.
merklerootstringThe Merkle root of the block’s transactions.
txarrayVerbosity = 1: array of transaction IDs.
Verbosity = 2: array of full transaction objects.
timeIntBlock timestamp in UNIX epoch time.
mediantimeIntMedian timestamp of the last 11 blocks.
nonceIntThe nonce used in the block’s proof-of-work.
bitsstringCompact representation of the difficulty target.
difficultyIntThe difficulty at the time of block creation.
chainworkstringTotal work in the chain up to this block.
nTxIntNumber of transactions in the block.
previousblockhashstringHash of the previous block in the chain.
nextblockhashstringHash of the next block.

Updated 5 days ago

Did this page help you?

Updated 5 days ago

Did this page help you?