RPC API Reference

BLVM node provides both a JSON-RPC 2.0 interface (conventional Bitcoin RPC surface) and a modern REST API for interacting with the node.

API Overview

• JSON-RPC 2.0: Methods aligned with widely documented Bitcoin node RPC docs. The blvm binary binds JSON-RPC to --rpc-addr / BLVM_RPC_ADDR. When omitted, RPC is network-aware: mainnet 127.0.0.1:8332, testnet and regtest 127.0.0.1:18332 (not Bitcoin Core’s regtest port 18443).
• REST API (optional): Served only when blvm-node is built with the rest-api feature and your runner enables it with a bind address. There is no separate fixed port in a minimal blvm deployment; examples below use http://localhost:8080 only as an illustration.

JSON-RPC is the portable operator surface. REST availability depends on build and wiring.

Connection

Use the same host:port you configure as --rpc-addr / BLVM_RPC_ADDR. The default is http://127.0.0.1:8332 (mainnet). Use http://127.0.0.1:18332 for testnet or regtest. There is no separate RPC port key in NodeConfig. See Node Configuration.

Authentication

Configure RPC authentication with [rpc_auth]. Two common patterns:

Bearer tokens (wallets, automation):

[rpc_auth]
required = true
tokens = ["your-long-random-token"]
admin_tokens = ["admin-token-for-mining-rpcs"]  # optional; mining/destructive methods

Pass Authorization: Bearer <token> on each request. Tokens in tokens alone are read-only unless also listed in admin_tokens.

HTTP Basic (ckpool, Bitcoin Core–style tools, curl -u):

[rpc_auth]
required = true
username = "ckpool"
password = "your-long-random-secret"

The password is registered as admin automatically (required for getblocktemplate / submitblock). Bind RPC to loopback (--rpc-addr 127.0.0.1:8332) — Basic auth is cleartext on the wire.

Optional: token_file, certificates, RPC_AUTH_TOKENS. [rpc] in NodeConfig is only for limits / rate limits, not credentials.

See RPC transport × authentication and Deployment posture.

Example Requests

Get Blockchain Info

# Mainnet uses port 8332, testnet/regtest use 18332
curl -X POST http://localhost:8332 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "getblockchaininfo",
    "params": [],
    "id": 1
  }'

Get Block

# Mainnet uses port 8332, testnet/regtest use 18332
curl -X POST http://localhost:8332 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "getblock",
    "params": ["000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f"],
    "id": 1
  }'

Get Network Info

# Mainnet uses port 8332, testnet/regtest use 18332
curl -X POST http://localhost:8332 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "getnetworkinfo",
    "params": [],
    "id": 1
  }'

Available Methods

Methods Implemented: Multiple RPC methods

Blockchain Methods

• getblockchaininfo - Get blockchain information
• getblock - Get block by hash
• getblockhash - Get block hash by height
• getblockheader - Get block header by hash
• getbestblockhash - Get best block hash
• getblockcount - Get current block height
• getdifficulty - Get current difficulty
• gettxoutsetinfo - Get UTXO set statistics
• verifychain - Verify blockchain database
• getblockfilter - Get block filter (BIP158)
• getindexinfo - Get index information
• getblockchainstate - Get blockchain state
• invalidateblock - Invalidate a block
• reconsiderblock - Reconsider a previously invalidated block
• waitfornewblock - Wait for a new block
• waitforblock - Wait for a specific block
• waitforblockheight - Wait for a specific block height

Raw Transaction Methods

• getrawtransaction - Get transaction by txid
• sendrawtransaction - Submit transaction to mempool
• testmempoolaccept - Test if transaction would be accepted
• decoderawtransaction - Decode raw transaction hex
• createrawtransaction - Create a raw transaction
• gettxout - Get UTXO information
• gettxoutproof - Get merkle proof for transaction
• verifytxoutproof - Verify merkle proof

Mempool Methods

• getmempoolinfo - Get mempool statistics
• getrawmempool - List transactions in mempool
• savemempool - Persist mempool to disk
• getmempoolancestors - Get mempool ancestors of a transaction
• getmempooldescendants - Get mempool descendants of a transaction
• getmempoolentry - Get mempool entry for a transaction

Network Methods

• getnetworkinfo - Get network information
• getpeerinfo - Get connected peers
• getconnectioncount - Get number of connections
• ping - Ping connected peers
• addnode - Add/remove node from peer list
• disconnectnode - Disconnect specific node
• getnettotals - Get network statistics
• clearbanned - Clear banned nodes
• setban - Ban/unban a subnet
• listbanned - List banned nodes
• getaddednodeinfo - Get information about manually added nodes
• getnodeaddresses - Get known node addresses
• setnetworkactive - Enable or disable network activity

Mining Methods

• getmininginfo - Get mining information
• getblocktemplate - Get block template for mining
• submitblock - Submit a mined block
• estimatesmartfee - Estimate smart fee rate
• prioritisetransaction - Prioritize a transaction in mempool

Control Methods

• stop - Stop the node
• uptime - Get node uptime
• getmemoryinfo - Get memory usage information
• getrpcinfo - Get RPC server information
• help - Get help for RPC methods
• logging - Control logging levels
• gethealth - Get node health status
• getmetrics - Get node metrics

Mesh Methods

Requires: blvm-mesh loaded and its ModuleAPI registered (spawned module with register_module_api capability).

• meshsendpacket - Forward a hex-encoded bincode SendPacketRequest to the mesh module (request_hex, optional mesh_module_id, default blvm-mesh)
• meshpollreceived - Poll locally delivered mesh app payloads (protocol_id, optional max_packets, optional mesh_module_id)

Code: control.rs (meshsendpacket, meshpollreceived)

Address Methods

• validateaddress - Validate a Bitcoin address
• getaddressinfo - Get detailed address information

Transaction Methods

• gettransactiondetails - Get detailed transaction information

Payment Methods (BIP70)

• createpaymentrequest - Create a BIP70 payment request (requires bip70-http feature)
• verifyonchainpayment - Verify on-chain payment state for a payment request (payment_request_id, tx_hash hex)
• verifycovenantproof - Verify a covenant proof for instant settlement (requires ctv feature)

Error Codes

The RPC API uses conventional JSON-RPC 2.0 error codes (same families as common Bitcoin node docs):

Standard JSON-RPC Errors

Bitcoin-Specific Errors

Code: errors.rs

Error Response Format

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "param": "blockhash",
      "reason": "Invalid hex string"
    }
  },
  "id": 1
}

Code: errors.rs

Authentication

RPC authentication is optional but recommended for production:

Token-Based Authentication

# Mainnet uses port 8332, testnet/regtest use 18332
curl -X POST http://localhost:8332 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "getblockchaininfo", "params": [], "id": 1}'

Certificate-Based Authentication

TLS client certificates can be used for authentication when QUIC transport is enabled.

Code: auth.rs

Rate Limiting

Rate limiting is enforced per IP, per user, and per method:

• Authenticated users: 100 burst, 10 req/sec
• Unauthenticated: 50 burst, 5 req/sec
• Per-method limits: May override defaults for specific methods

Code: server.rs

Request/Response Format

Request Format

{
  "jsonrpc": "2.0",
  "method": "getblockchaininfo",
  "params": [],
  "id": 1
}

Response Format

Success Response:

{
  "jsonrpc": "2.0",
  "result": {
    "chain": "regtest",
    "blocks": 123456,
    "headers": 123456,
    "bestblockhash": "0000...",
    "difficulty": 4.656542373906925e-10
  },
  "id": 1
}

Error Response:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params"
  },
  "id": 1
}

Code: types.rs

Batch Requests

Multiple requests can be sent in a single batch:

[
  {"jsonrpc": "2.0", "method": "getblockchaininfo", "params": [], "id": 1},
  {"jsonrpc": "2.0", "method": "getblockhash", "params": [100], "id": 2},
  {"jsonrpc": "2.0", "method": "getblock", "params": ["0000..."], "id": 3}
]

Responses are returned in the same order as requests.

Implementation Status

The RPC API implements JSON-RPC 2.0 methods documented in the Available Methods section above.

REST API

Overview

The REST API provides a modern, developer-friendly interface alongside JSON-RPC when enabled. It uses standard HTTP methods and status codes, with JSON request/response bodies.

Base URL (illustrative bind): http://localhost:8080/api/v1/ — replace host/port with your REST bind address.

Code: rest/mod.rs

Authentication

REST uses the same RpcAuthConfig manager as JSON-RPC when enabled:

curl -H "Authorization: Bearer <token>" http://localhost:8080/api/v1/node/uptime

Rate Limiting

Rate limiting is enforced per IP, per user, and per endpoint:

• Authenticated users: 100 burst, 10 req/sec
• Unauthenticated: 50 burst, 5 req/sec
• Per-endpoint limits: Stricter limits for write operations

Code: rest/server.rs

Response Format

All REST API responses follow a consistent format:

Success Response:

{
  "status": "success",
  "data": {
    "chain": "regtest",
    "blocks": 123456
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Error Response:

{
  "status": "error",
  "error": {
    "code": "NOT_FOUND",
    "message": "Block not found",
    "details": "Block hash 0000... does not exist"
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Code: rest/types.rs

Endpoints

Node Endpoints

Code: rest/node.rs

• GET /api/v1/node/uptime - Get node uptime
• GET /api/v1/node/memory - Get memory information
• GET /api/v1/node/memory?mode=detailed - Get detailed memory info
• GET /api/v1/node/rpc-info - Get RPC server information
• GET /api/v1/node/help - Get help for all commands
• GET /api/v1/node/help?command=getblock - Get help for specific command
• GET /api/v1/node/logging - Get logging configuration
• POST /api/v1/node/logging - Update logging configuration
• POST /api/v1/node/stop - Stop the node

Example:

curl http://localhost:8080/api/v1/node/uptime

Chain Endpoints

• GET /api/v1/chain/info - Get blockchain information
• GET /api/v1/chain/blockhash/{height} - Get block hash by height
• GET /api/v1/chain/blockcount - Get current block height
• GET /api/v1/chain/difficulty - Get current difficulty
• GET /api/v1/chain/txoutsetinfo - Get UTXO set statistics
• POST /api/v1/chain/verify - Verify blockchain database

Example:

curl http://localhost:8080/api/v1/chain/info

Block Endpoints

Code: rest/blocks.rs

• GET /api/v1/blocks/{hash} - Get block by hash
• GET /api/v1/blocks/{hash}/transactions - Get block transactions
• GET /api/v1/blocks/{hash}/header - Get block header
• GET /api/v1/blocks/{hash}/header?verbose=true - Get verbose block header
• GET /api/v1/blocks/{hash}/stats - Get block statistics
• GET /api/v1/blocks/{hash}/filter - Get BIP158 block filter
• GET /api/v1/blocks/{hash}/filter?filtertype=basic - Get specific filter type
• GET /api/v1/blocks/height/{height} - Get block by height
• POST /api/v1/blocks/{hash}/invalidate - Invalidate block
• POST /api/v1/blocks/{hash}/reconsider - Reconsider invalidated block

Example:

curl http://localhost:8080/api/v1/blocks/000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f

Transaction Endpoints

• GET /api/v1/transactions/{txid} - Get transaction by txid
• GET /api/v1/transactions/{txid}?verbose=true - Get verbose transaction
• POST /api/v1/transactions - Submit raw transaction
• POST /api/v1/transactions/test - Test if transaction would be accepted
• GET /api/v1/transactions/{txid}/out/{n} - Get UTXO information

Example:

curl -X POST http://localhost:8080/api/v1/transactions \
  -H "Content-Type: application/json" \
  -d '{"hex": "0100000001..."}'

Address Endpoints

• GET /api/v1/addresses/{address}/balance - Get address balance
• GET /api/v1/addresses/{address}/transactions - Get address transaction history
• GET /api/v1/addresses/{address}/utxos - Get address UTXOs

Example:

curl http://localhost:8080/api/v1/addresses/1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa/balance

Mempool Endpoints

• GET /api/v1/mempool/info - Get mempool information
• GET /api/v1/mempool/transactions - List transactions in mempool
• GET /api/v1/mempool/transactions?verbose=true - List verbose transactions
• POST /api/v1/mempool/save - Persist mempool to disk

Example:

curl http://localhost:8080/api/v1/mempool/info

Network Endpoints

Code: rest/network.rs

• GET /api/v1/network/info - Get network information
• GET /api/v1/network/peers - Get connected peers
• GET /api/v1/network/connections/count - Get connection count
• GET /api/v1/network/totals - Get network statistics
• GET /api/v1/network/nodes - Get added node information
• GET /api/v1/network/nodes?dns=true - Get added nodes with DNS lookup
• GET /api/v1/network/nodes/addresses - Get node addresses
• GET /api/v1/network/nodes/addresses?count=10 - Get N node addresses
• GET /api/v1/network/bans - List banned nodes
• POST /api/v1/network/ping - Ping connected peers
• POST /api/v1/network/nodes - Add node to peer list
• POST /api/v1/network/active - Activate node connection
• POST /api/v1/network/bans - Ban/unban a subnet
• DELETE /api/v1/network/nodes/{address} - Remove node from peer list
• DELETE /api/v1/network/bans - Clear all banned nodes

Example:

curl http://localhost:8080/api/v1/network/info

Fee Estimation Endpoints

• GET /api/v1/fees/estimate - Estimate fee rate
• GET /api/v1/fees/estimate?blocks=6 - Estimate fee for N blocks
• GET /api/v1/fees/smart - Get smart fee estimate

Example:

curl http://localhost:8080/api/v1/fees/estimate?blocks=6

Payment Endpoints (BIP70 HTTP)

Requires: --features bip70-http

Code: rest/payment.rs

• GET /api/v1/payments/{payment_id} - Get payment status
• POST /api/v1/payments - Create payment request
• POST /api/v1/payments/{payment_id}/pay - Submit payment
• POST /api/v1/payments/{payment_id}/cancel - Cancel payment

Vault Endpoints (CTV)

Requires: --features ctv

Code: rest/vault.rs

• GET /api/v1/vaults - List vaults
• GET /api/v1/vaults/{vault_id} - Get vault information
• POST /api/v1/vaults - Create vault
• POST /api/v1/vaults/{vault_id}/deposit - Deposit to vault
• POST /api/v1/vaults/{vault_id}/withdraw - Withdraw from vault

Pool Endpoints (CTV)

Requires: --features ctv

Code: rest/pool.rs

• GET /api/v1/pools - List pools
• GET /api/v1/pools/{pool_id} - Get pool information
• POST /api/v1/pools - Create pool
• POST /api/v1/pools/{pool_id}/join - Join pool
• POST /api/v1/pools/{pool_id}/leave - Leave pool

Congestion Control Endpoints (CTV)

Requires: --features ctv

Code: rest/congestion.rs

• GET /api/v1/congestion/status - Get congestion status
• GET /api/v1/batches - List pending batches
• POST /api/v1/batches - Create batch
• POST /api/v1/batches/{batch_id}/submit - Submit batch

Security Headers

The REST API includes security headers by default:

• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY
• X-XSS-Protection: 1; mode=block
• Strict-Transport-Security: max-age=31536000 (when TLS enabled)

Code: rest/server.rs

Error Codes

REST API uses standard HTTP status codes:

See Also

• Node Overview - Node implementation details
• Node Configuration - RPC configuration options
• Node Operations - Node management
• Getting Started - Quick start guide
• API Index - Cross-reference to all APIs
• Troubleshooting - Common RPC issues
• Commons Mesh Module - Payment endpoints and mesh networking
• Module System - Module architecture and IPC