Essential BCH Blockchain API Guide

The Bitcoin Cash (BCH) blockchain provides a powerful set of Remote Procedure Call (RPC) interfaces for developers to interact with nodes, retrieve data, and build applications. This guide covers the most commonly used APIs, their parameters, and practical examples.

Please note: The following examples and tests were performed on a development network.

Core Blockchain APIs

These interfaces allow you to retrieve fundamental blockchain data, including block information and transaction details.

Retrieving Block Information

Blockchain applications often need to access current chain state and historical block data. These APIs provide direct access to this critical information.

Get Current Block Height

The getblockcount method returns the current height of the blockchain, representing the number of blocks in the longest chain.

Example Request:

bitcoin-cli getblockcount

cURL Alternative:

curl --user username:password --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getblockcount", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:18443/

Retrieve Block Hash by Height

The getblockhash method returns the hash of the block at the specified height in the local best block chain.

Parameters:

BlockHeight: The height of the desired block

Example Request:

bitcoin-cli getblockhash 121

cURL Alternative:

curl --user username:password --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getblockhash", "params": [121] }' -H 'content-type: text/plain;' http://127.0.0.1:18443/

Returns: The block hash as a hexadecimal string

Access Detailed Block Data

The getblock method provides comprehensive information about a specified block, with formatting options for different use cases.

Parameters:

HeaderHash: The block hash
Format: Result format (0: serialized string, 1: JSON object, 2: JSON with decoded transactions)

Example Request:

bitcoin-cli getblock 176d9c775e14d6490ac30231dd7f10bced7f182d2525d362700951e1fda6e03e

Response varies by format parameter:

Format 0: Returns serialized block as hexadecimal string
Format 1: Returns JSON object with block metadata (hash, confirmations, size, etc.)
Format 2: Returns JSON object with fully decoded transactions

Mining Operations API

For development and testing environments, mining capabilities are essential for generating test blocks and receiving block rewards.

Generate Blocks to Address

The generatetoaddress method mines a specified number of blocks immediately to a designated address.

Parameters:

Blocks: Number of blocks to generate
Address: Receiving address for block rewards
Maxtries: Maximum attempts (default: 1000000)

Example Request:

bitcoin-cli generatetoaddress 5 "qpt20c6gpn7eq48ez0l22zeg7txnn8u0ky6g5lcdw4"

Returns: Array of block hashes for the generated blocks

Transaction Data Retrieval

Accessing raw transaction data is crucial for auditing, analysis, and building transaction processors.

Retrieve Raw Transaction Data

The getrawtransaction method returns detailed information about specific transactions, either in serialized or decoded format.

Parameters:

TXID: The transaction ID to query
Format: Return format (false: serialized string, true: decoded JSON object)
blockhash: Optional block hash for context

Example Request:

bitcoin-cli getrawtransaction b51cc630d326a6ba46fdb6ec7ce4f2a3800392dc811b4f08d315de5e75b783cc true

When Format is true, returns:

hex: Serialized transaction string
blockhash: Containing block hash
confirmations: Number of confirmations
time: Block timestamp
blocktime: Block timestamp (duplicate of time)

Wallet Management APIs

Wallet operations form the core of most BCH applications, from address management to balance tracking and transaction sending.

👉 Explore advanced wallet management tools

Generate New Addresses

The getnewaddress method creates a new receiving address for the wallet.

Parameters:

Account: Optional account name for organization
AddressType: Address format (legacy, p2sh-segwit, bech32)

Example Request:

bitcoin-cli getnewaddress test

Returns: A new BCH address string

Check Wallet Balances

Multiple methods provide different views of wallet balances for various use cases.

Get Available Balance

The getbalance method returns the wallet's spendable balance.

Parameters:

Confirmations: Minimum confirmations for UTXOs (default: 6)
WatchOnlyIncl: Include watch-only addresses (default: true)

Example Request:

bitcoin-cli getbalance

Returns: Total available balance in BCH

Get Detailed Balance Breakdown

The getbalances method provides a comprehensive view of wallet funds across different categories.

Example Request:

bitcoin-cli getbalances

Sample Response:

{
  "mine": {
    "trusted": 500.00000000,
    "untrusted_pending": 0.00000000,
    "immature": 5000.00000000
  }
}

Balance Categories:

trusted: Confirmed and spendable balance
untrusted_pending: Unconfirmed transactions from external sources
immature: Newly mined coins not yet spendable

List Address Groupings

The listaddressgroupings method displays balances for all addresses in the wallet.

Example Request:

bitcoin-cli listaddressgroupings

Returns: Array of address information including:

Address: The BCH address
Balance: Current balance (excluding unconfirmed)
Account: Associated account name

Send Transactions

Sending BCH to addresses is a fundamental operation for wallets and payment processors.

Send to Address

The sendtoaddress method sends BCH to a specified address.

Parameters:

ToAddress: Recipient address
Amount: BCH amount to send
Comment: Optional transaction memo
CommentTo: Optional recipient description
subtractfeefromamount: Deduct fee from amount (default: false)
avoid_reuse: Avoid spending from used addresses (default: true)

Example Request:

bitcoin-cli sendtoaddress "qqzgpjk7fsy5m4a90f22dnshlrhtsjf84sd0m4frvf" 5

Returns: Transaction ID of the sent funds

Transaction Details and History

Tracking transaction history and details is essential for accounting and user interfaces.

Get Transaction Information

The gettransaction method retrieves detailed information about a specific wallet transaction.

Parameters:

TXID: Transaction ID to query
include_watchonly: Include watch-only addresses (default: true)

Example Request:

bitcoin-cli gettransaction b51cc630d326a6ba46fdb6ec7ce4f2a3800392dc811b4f08d315de5e75b783cc

Returns comprehensive transaction details including:

amount: Net impact on wallet balance
fee: Transaction fee (for sent transactions)
confirmations: Number of confirmations
blockhash: Containing block hash
details: Input/output information
hex: Serialized transaction data

List Received Transactions by Address

The listreceivedbyaddress method shows receiving history for wallet addresses.

Parameters:

minconf: Minimum confirmations (default: 1)
include_empty: Include addresses with no receipts (default: false)
include_watchonly: Include watch-only addresses (default: false)
address_filter: Specific address to filter results

Example Request:

bitcoin-cli listreceivedbyaddress 6 true true qqzgpjk7fsy5m4a90f22dnshlrhtsjf84sd0m4frvf

Returns address receipt information including:

address: The BCH address
amount: Total received amount
confirmations: Confirmations of last transaction
txids: Array of receiving transaction IDs

Wallet Configuration and Maintenance

Proper wallet configuration ensures optimal operation and cost management.

Set Transaction Fee Rate

The settxfee method configures the transaction fee rate per kilobyte.

Parameters:

FeePerKB: Fee rate in BCH per kilobyte

Example Request:

bitcoin-cli settxfee 0.0008

Returns: true on success

Export Wallet Data

The dumpwallet method exports wallet contents to a text file for backup or analysis.

Parameters:

filename: Output file path

Example Request:

bitcoin-cli dumpwallet /opt/wallet.txt

Returns: Absolute path to the exported file

Frequently Asked Questions

What is the difference between getbalance and getbalances?

Getbalance returns a single total of spendable funds, while getbalances provides a detailed breakdown across trusted, untrusted pending, and immature categories. Use getbalance for simple balance checks and getbalances for detailed accounting purposes.

How do I choose between different address formats?

Legacy addresses (starting with 1) have widest compatibility, p2sh-segwit addresses (starting with 3) offer better security and efficiency, while bech32 addresses (starting with bc1) provide the lowest fees and error detection. Choose based on your application's requirements for compatibility versus efficiency.

Why would settxfee return false?

Setttxfee may return false if the specified fee rate is outside acceptable parameters or if the node has restrictions on minimum/maximum fees. Ensure your fee rate is reasonable and expressed in BCH per kilobyte.

What does "immature" balance mean?

Immature balance refers to coinbase transactions from mining that haven't reached the required 100 confirmations to become spendable. These funds are temporarily locked to prevent chain reorganization issues.

How can I track transactions for specific addresses?

Use listreceivedbyaddress with the address_filter parameter to monitor transactions for specific addresses, or regularly scan with listaddressgroupings to track all addresses in your wallet.

What security precautions should I take with these APIs?

Always use secure RPC authentication, restrict API access to trusted networks, and never expose your node to public internet without proper security measures. Regularly update your node software to patch vulnerabilities.

👉 Discover comprehensive blockchain development resources