Bitcoin Node API v1.0.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

API gateway for interacting with a Bitcoin node via standardized JSON-RPC methods

Base URLs:

Authentication

API Key (ApiKeyAuth)
- Parameter Name: X-API-Key, in: header. API key for authentication. Include your API key in the X-API-Key header.

Bitcoin

Bitcoin JSON-RPC gateway and helper endpoints

Check BTC node health

Code samples

GET /api/v1/btc/health

Performs a lightweight getblockchaininfo JSON-RPC call to the configured BTC node and returns basic health information.

Example responses

200 Response

{
  "status": "ok",
  "time": "2025-07-23T15:16:00Z",
  "chain": "main",
  "blocks": 840000,
  "headers": 840005,
  "verificationProgress": 0.99999
}

Responses

Status	Meaning	Description	Schema
200	OK	BTC node is reachable and responding	Inline
500	Internal Server Error	BTC node URL or credentials are not configured, or node is not reachable	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» status	string	false	none	none
» time	string(date-time)	false	none	none
» chain	string	false	none	Active chain type reported by `getblockchaininfo` (e.g. main, test, regtest, signet).
» blocks	integer(int64)	false	none	Current block height.
» headers	integer(int64)	false	none	Current number of block headers known.
» verificationProgress	number(float)	false	none	Blockchain verification progress from 0.0 to 1.0.

Status Code 500

Name	Type	Required	Restrictions	Description
» status	string	false	none	none
» message	string	false	none	none

Get latest Bitcoin block

Code samples

GET /api/v1/btc/block/last

Returns the most recent block from the Bitcoin blockchain using getbestblockhash followed by getblock with verbosity 2.

Example responses

200 Response

{
  "hash": "string",
  "confirmations": 0,
  "height": 0,
  "version": 0,
  "versionHex": "string",
  "merkleroot": "string",
  "time": 0,
  "mediantime": 0,
  "nonce": 0,
  "bits": "string",
  "difficulty": 0.1,
  "chainwork": "string",
  "nTx": 0,
  "strippedsize": 0,
  "size": 0,
  "weight": 0,
  "previousblockhash": "string",
  "nextblockhash": "string",
  "tx": [
    "string"
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Latest Bitcoin block	BtcBlock
500	Internal Server Error	Could not connect to BTC node	None

Get Bitcoin block by height

Code samples

GET /api/v1/btc/block/{blockNumber}

Returns a specific block by its height using getblockhash followed by getblock with verbosity 2.

Parameters

Name	In	Type	Required	Description
blockNumber	path	integer(int64)	true	Block height in the best chain (non-negative integer).

Example responses

200 Response

{
  "hash": "string",
  "confirmations": 0,
  "height": 0,
  "version": 0,
  "versionHex": "string",
  "merkleroot": "string",
  "time": 0,
  "mediantime": 0,
  "nonce": 0,
  "bits": "string",
  "difficulty": 0.1,
  "chainwork": "string",
  "nTx": 0,
  "strippedsize": 0,
  "size": 0,
  "weight": 0,
  "previousblockhash": "string",
  "nextblockhash": "string",
  "tx": [
    "string"
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Bitcoin block	BtcBlock
400	Bad Request	Invalid block number (negative)	Inline
500	Internal Server Error	Could not connect to BTC node	None

Response Schema

Status Code 400

Name	Type	Required	Restrictions	Description
» error	string	false	none	none

Get Bitcoin block by hash

Code samples

GET /api/v1/btc/block/hash/{blockHash}

Returns a block by its hash using getblock with verbosity 2.

Parameters

Name	In	Type	Required	Description
blockHash	path	string	true	Bitcoin block hash.

Example responses

200 Response

{
  "hash": "string",
  "confirmations": 0,
  "height": 0,
  "version": 0,
  "versionHex": "string",
  "merkleroot": "string",
  "time": 0,
  "mediantime": 0,
  "nonce": 0,
  "bits": "string",
  "difficulty": 0.1,
  "chainwork": "string",
  "nTx": 0,
  "strippedsize": 0,
  "size": 0,
  "weight": 0,
  "previousblockhash": "string",
  "nextblockhash": "string",
  "tx": [
    "string"
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Bitcoin block	BtcBlock
500	Internal Server Error	Could not connect to BTC node	None

Get transaction count in block by height

Code samples

GET /api/v1/btc/block/{blockNumber}/transactions/count

Returns the number of transactions in a block identified by height using getblockhash followed by getblock (verbosity 1).

Parameters

Name	In	Type	Required	Description
blockNumber	path	integer(int64)	true	Block height in the best chain (non-negative integer).

Example responses

200 Response

{
  "transactionCount": 2500
}

Responses

Status	Meaning	Description	Schema
200	OK	Number of transactions in the block	Inline
400	Bad Request	Invalid block number (negative)	Inline
500	Internal Server Error	Could not connect to BTC node	None

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» transactionCount	integer(int64)¦null	false	none	Number of transactions (`nTx`) in the block, or null if unavailable.

Status Code 400

Name	Type	Required	Restrictions	Description
» error	string	false	none	none

Get transaction count in block by hash

Code samples

GET /api/v1/btc/block/hash/{blockHash}/transactions/count

Returns the number of transactions in a block identified by hash using getblock with verbosity 1.

Parameters

Name	In	Type	Required	Description
blockHash	path	string	true	Bitcoin block hash.

Example responses

200 Response

{
  "transactionCount": 2500
}

Responses

Status	Meaning	Description	Schema
200	OK	Number of transactions in the block	Inline
500	Internal Server Error	Could not connect to BTC node	None

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» transactionCount	integer(int64)¦null	false	none	Number of transactions (`nTx`) in the block, or null if unavailable.

List BTC addresses managed by node wallet

Code samples

GET /api/v1/btc/account

Returns a list of wallet addresses and their received amounts using the listreceivedbyaddress Bitcoin JSON-RPC method.

Parameters

Name	In	Type	Required	Description
minconf	query	integer(int32)	false	Minimum number of confirmations required for payments.
includeEmpty	query	boolean	false	Whether to include addresses with no transactions.
includeWatchOnly	query	boolean	false	Whether to include watch-only addresses.

Example responses

200 Response

[
  {
    "address": "string",
    "amount": 0.1,
    "confirmations": 0,
    "label": "string",
    "txids": [
      "string"
    ]
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	Array of addresses known to the node wallet	Inline
400	Bad Request	Invalid `minconf` parameter (negative)	Inline
500	Internal Server Error	Could not connect to BTC node	None

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
anonymous	[BtcReceivedByAddress]	false	none	[Entry returned by `listreceivedbyaddress`.]
» address	string	false	none	Bitcoin address.
» amount	number(double)	false	none	Total amount received by this address in BTC.
» confirmations	integer(int64)	false	none	none
» label	string¦null	false	none	none
» txids	[string]	false	none	none

Status Code 400

Name	Type	Required	Restrictions	Description
» error	string	false	none	none

Get BTC received amount for address

Code samples

GET /api/v1/btc/account/{address}/balance

Returns the total amount received by a given address using getreceivedbyaddress. Note that this requires the address to belong to the node's wallet.

Parameters

Name	In	Type	Required	Description
address	path	string	true	Bitcoin address (Base58 or Bech32) managed by the node wallet.
minconf	query	integer(int32)	false	Minimum number of confirmations required for payments.

Example responses

200 Response

{
  "address": "bc1qexampleaddress0000000000000000000000000",
  "minconf": 1,
  "balance": 0.12345678
}

Responses

Status	Meaning	Description	Schema
200	OK	BTC received amount for the address	Inline
400	Bad Request	Invalid `minconf` parameter (negative)	Inline
500	Internal Server Error	Could not connect to BTC node	None

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» address	string	false	none	none
» minconf	integer(int32)	false	none	none
» balance	number(double)	false	none	Total amount received by the address in BTC.

Status Code 400

Name	Type	Required	Restrictions	Description
» error	string	false	none	none

Get Bitcoin transaction by hash

Code samples

GET /api/v1/btc/transactions/{hash}

Returns transaction details using the getrawtransaction method with verbose output.

Parameters

Name	In	Type	Required	Description
hash	path	string	true	Bitcoin transaction hash (txid).

Example responses

200 Response

{
  "txid": "string",
  "hash": "string",
  "version": 0,
  "size": 0,
  "vsize": 0,
  "weight": 0,
  "locktime": 0,
  "blockhash": "string",
  "confirmations": 0,
  "time": 0,
  "blocktime": 0,
  "hex": "string",
  "vin": [
    {
      "txid": "string",
      "vout": 0,
      "coinbase": "string",
      "scriptSig": {
        "asm": "string",
        "hex": "string"
      },
      "sequence": 0
    }
  ],
  "vout": [
    {
      "value": 0.1,
      "n": 0,
      "scriptPubKey": {
        "asm": "string",
        "hex": "string",
        "type": "string",
        "reqSigs": 0,
        "addresses": [
          "string"
        ]
      }
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Bitcoin transaction	BtcTransaction
404	Not Found	Transaction not found	Inline
500	Internal Server Error	Could not connect to BTC node	None

Response Schema

Status Code 404

Name	Type	Required	Restrictions	Description
» error	string	false	none	none

Send pre-signed raw Bitcoin transaction

Code samples

POST /api/v1/btc/transactions/send-raw

Sends a signed, hex-encoded Bitcoin transaction using the sendrawtransaction JSON-RPC method.

Body parameter

{
  "rawTransaction": "020000000001...",
  "signedTransaction": "020000000001..."
}

Parameters

Name	In	Type	Required	Description
body	body	object	true	none
» rawTransaction	body	string	true	Signed and hex-encoded Bitcoin transaction.
» signedTransaction	body	string	false	Alternative field name accepted by the API (alias of `rawTransaction`).

Example responses

200 Response

{
  "transactionHash": "4e3b5a8f5e6e2b1c9d0f4c2a1b0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2"
}

Responses

Status	Meaning	Description	Schema
200	OK	Transaction hash returned by node	Inline
422	Unprocessable Entity	Invalid request body (missing or invalid `rawTransaction`)	Inline
500	Internal Server Error	Could not connect to BTC node	None

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» transactionHash	string	false	none	Transaction hash (txid) returned by `sendrawtransaction`.

Status Code 422

Name	Type	Required	Restrictions	Description
» error	string	false	none	none

Generic JSON-RPC proxy to BTC node

Code samples

POST /api/v1/btc/jsonrpc

Proxies any valid Bitcoin JSON-RPC 1.0 request to the configured BTC node. The request body is forwarded as-is and the node's response is returned.

Body parameter

{
  "jsonrpc": "1.0",
  "method": "getblockchaininfo",
  "params": [
    null
  ],
  "id": null
}

Parameters

Name	In	Type	Required	Description
body	body	any	true	none

Example responses

200 Response

{}

Responses

Status	Meaning	Description	Schema
200	OK	JSON-RPC response from BTC node	Inline
500	Internal Server Error	BTC node URL or credentials are not configured	BtcJsonRpcError
502	Bad Gateway	Failed to connect to BTC node	BtcJsonRpcError

Response Schema

Schemas

BtcBlock

{
  "hash": "string",
  "confirmations": 0,
  "height": 0,
  "version": 0,
  "versionHex": "string",
  "merkleroot": "string",
  "time": 0,
  "mediantime": 0,
  "nonce": 0,
  "bits": "string",
  "difficulty": 0.1,
  "chainwork": "string",
  "nTx": 0,
  "strippedsize": 0,
  "size": 0,
  "weight": 0,
  "previousblockhash": "string",
  "nextblockhash": "string",
  "tx": [
    "string"
  ]
}

Bitcoin block object as returned by getblock with verbosity 1 or 2.

Properties

Name	Type	Required	Restrictions	Description
hash	string	false	none	Hash of the block.
confirmations	integer(int64)	false	none	Number of confirmations for the block.
height	integer(int64)	false	none	Block height.
version	integer	false	none	Block version.
versionHex	string	false	none	none
merkleroot	string	false	none	Merkle root of the block's transactions.
time	integer(int64)	false	none	Block time in seconds since Unix epoch.
mediantime	integer(int64)	false	none	none
nonce	integer(int64)	false	none	none
bits	string	false	none	none
difficulty	number(double)	false	none	none
chainwork	string	false	none	none
nTx	integer(int64)	false	none	Number of transactions in the block.
strippedsize	integer(int64)	false	none	none
size	integer(int64)	false	none	none
weight	integer(int64)	false	none	none
previousblockhash	string¦null	false	none	none
nextblockhash	string¦null	false	none	none
tx	[oneOf]	false	none	Transactions included in the block. When verbosity=2, this is an array of full transaction objects; otherwise it may be an array of transaction IDs.

oneOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false	none	none

xor

Name	Type	Required	Restrictions	Description
» anonymous	BtcTransaction	false	none	Bitcoin transaction object as returned by `getrawtransaction` with verbose=true.

BtcTransaction

{
  "txid": "string",
  "hash": "string",
  "version": 0,
  "size": 0,
  "vsize": 0,
  "weight": 0,
  "locktime": 0,
  "blockhash": "string",
  "confirmations": 0,
  "time": 0,
  "blocktime": 0,
  "hex": "string",
  "vin": [
    {
      "txid": "string",
      "vout": 0,
      "coinbase": "string",
      "scriptSig": {
        "asm": "string",
        "hex": "string"
      },
      "sequence": 0
    }
  ],
  "vout": [
    {
      "value": 0.1,
      "n": 0,
      "scriptPubKey": {
        "asm": "string",
        "hex": "string",
        "type": "string",
        "reqSigs": 0,
        "addresses": [
          "string"
        ]
      }
    }
  ]
}

Bitcoin transaction object as returned by getrawtransaction with verbose=true.

Properties

Name	Type	Required	Restrictions	Description
txid	string	false	none	Transaction ID.
hash	string	false	none	none
version	integer	false	none	none
size	integer	false	none	none
vsize	integer	false	none	none
weight	integer	false	none	none
locktime	integer	false	none	none
blockhash	string¦null	false	none	none
confirmations	integer(int64)¦null	false	none	none
time	integer(int64)¦null	false	none	none
blocktime	integer(int64)¦null	false	none	none
hex	string	false	none	Raw hex-encoded transaction.
vin	[BtcVin]	false	none	[Transaction input (vin) entry.]
vout	[BtcVout]	false	none	[Transaction output (vout) entry.]

BtcVin

{
  "txid": "string",
  "vout": 0,
  "coinbase": "string",
  "scriptSig": {
    "asm": "string",
    "hex": "string"
  },
  "sequence": 0
}

Transaction input (vin) entry.

Properties

Name	Type	Required	Restrictions	Description
txid	string¦null	false	none	none
vout	integer¦null	false	none	none
coinbase	string¦null	false	none	none
scriptSig	object¦null	false	none	none
» asm	string	false	none	none
» hex	string	false	none	none
sequence	integer(int64)	false	none	none

BtcVout

{
  "value": 0.1,
  "n": 0,
  "scriptPubKey": {
    "asm": "string",
    "hex": "string",
    "type": "string",
    "reqSigs": 0,
    "addresses": [
      "string"
    ]
  }
}

Transaction output (vout) entry.

Properties

Name	Type	Required	Restrictions	Description
value	number(double)	false	none	Value in BTC.
n	integer	false	none	Output index.
scriptPubKey	object	false	none	none
» asm	string	false	none	none
» hex	string	false	none	none
» type	string	false	none	none
» reqSigs	integer¦null	false	none	none
» addresses	[string]¦null	false	none	none

BtcReceivedByAddress

{
  "address": "string",
  "amount": 0.1,
  "confirmations": 0,
  "label": "string",
  "txids": [
    "string"
  ]
}

Entry returned by listreceivedbyaddress.

Properties

Name	Type	Required	Restrictions	Description
address	string	false	none	Bitcoin address.
amount	number(double)	false	none	Total amount received by this address in BTC.
confirmations	integer(int64)	false	none	none
label	string¦null	false	none	none
txids	[string]	false	none	none

BtcJsonRpcRequest

{
  "jsonrpc": "1.0",
  "method": "getblockchaininfo",
  "params": [
    null
  ],
  "id": null
}

Generic Bitcoin JSON-RPC 1.0 request.

Properties

Name	Type	Required	Restrictions	Description
jsonrpc	string	false	none	none
method	string	true	none	Bitcoin JSON-RPC method name (e.g. `getblockchaininfo`).
params	[any]	true	none	Positional parameters for the method.
id	any	false	none	Request identifier (string, number, or null).

BtcJsonRpcError

{
  "error": {
    "code": -32603,
    "message": "Failed to connect to BTC node"
  }
}

Error response used when BTC JSON-RPC proxy fails.

Properties

Name	Type	Required	Restrictions	Description
error	object	false	none	none
» code	integer	false	none	none
» message	string	false	none	none