An application communicates with a node, wallet, indexer, Lightning implementation, or provider through an interface. The response reflects that system’s chain tip, configuration, indexes, policy, cache, software version, and local observations.
That distinction matters because different interfaces can return values that look similar while carrying different evidence. A block hash from a validating node, an address balance from an indexer, a fee estimate from a hosted service, and a transaction status from an application database are not interchangeable claims.
An API design begins by naming the producer of every response.
What “Bitcoin API” can mean
The term can refer to several interface families:
- Bitcoin Core JSON-RPC for node and wallet operations
- Bitcoin Core REST for limited read access
- Bitcoin Core ZMQ notifications
- The Bitcoin peer-to-peer protocol
- Electrum-protocol servers
- Esplora-style HTTP APIs
- Hosted block-explorer or infrastructure APIs
- Lightning node APIs
- An application-facing API built in front of any of the above
Each family has different authentication, data, state, and failure properties. An application should not expose a raw node-administration interface simply because it is convenient. It should translate node and wallet capabilities into a narrower API with explicit authorization and business rules.
Bitcoin Core JSON-RPC
Bitcoin Core JSON-RPC is a request-response interface served by bitcoind and, when enabled, bitcoin-qt. As of Bitcoin Core 31.1, the root endpoint handles node RPCs and can handle wallet RPCs when exactly one wallet is loaded. Wallet-specific endpoints use /wallet/<walletname>/.
Node RPCs include chain, mempool, peer, network, mining, raw-transaction, and administrative methods. Wallet RPCs operate on loaded wallet state, including addresses, balances, PSBTs, signing, transaction creation, locks, and fee bumping.
The distinction is important. A node RPC such as a block query reflects the node’s chain and optional indexes. A wallet RPC reflects a particular wallet database and its synchronization state. A wallet balance is not a universal property of the chain; it is the wallet’s interpretation of transactions relevant to its scripts.
Bitcoin Core’s RPC interface is implicitly versioned by the major release. Fields, defaults, deprecations, and method behavior can change. Clients should pin versions, test response schemas, and read release notes rather than assume indefinite compatibility.
Cookie authentication and `rpcauth`
Bitcoin Core can authenticate local RPC clients with a temporary cookie file. The cookie contains generated credentials and is replaced when the node restarts. File permissions and local process boundaries are therefore part of the security model.
The rpcauth configuration option supports salted password authentication without storing the plaintext password in the configuration file. Bitcoin Core also provides -rpcwhitelist and -rpcwhitelistdefault to restrict which RPC methods a credential may call.
Those method restrictions are useful operational controls, but they should not be treated as a robust security boundary for hostile multi-user or multi-wallet isolation. Public applications should still place Bitcoin Core behind a narrower service that performs application-specific authentication, authorization, validation, and rate limiting.
Network exposure and transport security
Bitcoin Core documentation explicitly warns against exposing RPC directly to the public internet. RPC authentication does not encrypt traffic, and the interface is not designed as a hardened public application endpoint.
Remote administration should be limited to secure private networks or protected tunnels, with firewalling and least-privilege credentials. A public web or mobile application should call an application service that performs authorization, validation, rate limiting, and response normalization. That service can then communicate with Bitcoin Core over a restricted internal boundary.
Bitcoin Core REST
Bitcoin Core provides an optional REST interface for selected read operations. It can return blocks, headers, transactions, chain information, UTXO information, and related data in defined encodings.
REST is narrower than RPC and does not replace wallet or administrative methods. It also does not add an address-history index. The availability of a REST endpoint does not mean its response is safe to expose without an application security layer.
Applications should identify whether a REST response comes directly from the validating node, whether it requires an optional index, and how it behaves during pruning or reorganization.
ZMQ notifications
Bitcoin Core ZMQ is a one-way publish-subscribe notification interface. Topics can announce raw or hashed blocks and transactions, sequence changes, mempool additions and removals, and block connections or disconnections.
ZMQ is useful when an application needs low-latency notification without polling every method. It is not a durable event log. Notifications can be lost during transport, a subscriber can disconnect, and the application can start after earlier events occurred.
Subscribers should track sequence information where available, detect gaps, and reconcile against RPC or another authoritative state query. The subscriber must retrieve the active chain from its last known point rather than assume every notification extends the previous tip.
Bitcoin Core’s ZMQ publication interface does not authenticate subscribers. It should be exposed only within a trusted network boundary.
The Bitcoin peer-to-peer protocol
The P2P protocol carries version negotiation, peer addresses, inventory announcements, transactions, headers, blocks, compact blocks, filters, and other messages between nodes.
It is not an ordinary REST API. Peers are untrusted network participants. Receiving a transaction or block does not make it valid. A P2P client must decide what it validates, how it selects a chain, how it handles malformed messages, and how it limits resource consumption.
A full node uses the P2P protocol as one input to its validation process. An application that implements only a small subset may receive useful data but should not describe that as equivalent to full validation.
Current Bitcoin Core also supports BIP 324 version 2 transport, but transport encryption and peer authentication properties must not be confused with application authorization or consensus validation.
Electrum protocol servers
The Electrum protocol uses JSON-RPC over stream transports such as TCP, TLS, or WebSockets. Clients negotiate a protocol version and can request headers, transactions, script or script-hash histories, balances, UTXOs, fee estimates, and subscriptions.
The currently published protocol documentation is labeled 1.7.x. Protocol 1.7 replaces the older blockchain.scripthash.* method family with blockchain.scriptpubkey.* methods and changes some response and reorganization-notification behavior. Those methods still require an external index that maps scripts to transaction history; Bitcoin Core does not provide that universal index by default.
Deployed support is uneven. Electrum 4.7.2 documents protocol 1.6 support, while clients and servers may advertise different version ranges. Integrations must negotiate and test the exact protocol version instead of assuming that the latest documented specification is already supported everywhere.
Headers and Merkle proofs can support evidence that a transaction was included under a block header. They do not independently validate every Bitcoin consensus rule unless the client performs the additional validation required for that claim.
Esplora-style HTTP APIs
Esplora-style APIs expose HTTP resources for blocks, transactions, addresses, scripts, UTXOs, fee estimates, and mempool information. The API is usually backed by an indexer such as an electrs-derived backend rather than by Bitcoin Core alone.
Fields may combine raw Bitcoin data with indexed, cached, or computed values. Address history and spending relationships require indexes. Fee estimates are estimates. Mempool entries reflect the backend’s local node and policy.
An Esplora endpoint can be self-hosted or hosted by another organization. The protocol shape does not determine the trust model. Applications should record network, chain tip, backend version, cache behavior, and provider failure expectations.
Hosted explorer and infrastructure APIs
Hosted providers may add account authentication, quotas, webhooks, historical analytics, transaction broadcast, address monitoring, fiat conversions, or proprietary risk fields.
Those features can be useful, but they are not part of Bitcoin consensus. A provider’s “confirmed,” “safe,” “final,” “risk,” or “balance” field must be mapped to documented inputs and logic.
Hosted services introduce:
- Availability and rate-limit dependencies
- Provider authentication and account risk
- Privacy leakage from addresses, xpubs, transactions, and IPs
- Version and deprecation risk
- Policy and chain-tip differences
- Logging and data-retention dependencies
- Cached or delayed responses
- Proprietary derived fields
No commercial provider should be treated as a universal default. Selection should follow the application’s validation, privacy, uptime, and regulatory requirements.
Lightning node APIs are separate
Lightning implementations expose separate RPC, REST, gRPC, socket, or plugin interfaces for channels, invoices, payments, routing, peers, and implementation-specific wallet state. Their schemas and security assumptions differ from Bitcoin Core. On-chain funding and closing still interact with Bitcoin, but Lightning APIs require independent version and security review.
Local validation and remote data access
A local validating node can establish which blocks and transactions satisfy Bitcoin rules for its accepted chain. A remote API can provide convenient indexed data. Many applications use both.
For example, a remote service might return address history while a local node verifies referenced transactions and blocks. That cross-check reduces some provider trust but does not automatically verify every derived field. The application must define what is checked, when, and against which chain tip.
A local or remote source can be stale, misconfigured, or on the wrong network. Chain-tip hash, work, sync status, and network identifier all matter.
Raw data and derived fields
API fields can be grouped by how they are produced.
Raw or directly encoded data includes serialized blocks, headers, transactions, scripts, witnesses, and outpoints.
Node state includes active-chain membership, current tip, local mempool contents, peer state, and UTXO-set queries.
Indexed fields include address history, script history, transaction lookup outside available block context, spending relationships, and explorer search.
Estimated fields include fee estimates and projected confirmation targets.
Cached fields may represent an earlier response or asynchronously updated database.
Application-derived fields include invoice status, account balance, risk score, token balance, inscription state, and business labels.
The API should identify those categories rather than present every field with equal authority.
Blocks, headers, transactions, and UTXOs
A block response should include enough identity to determine network, block hash, height, and active-chain relationship. Height alone is insufficient because a reorganization can replace the block at that height.
A transaction response should distinguish raw transaction data from confirmation metadata. Confirmation count depends on current tip. The transaction’s block hash should be preserved so the application can detect replacement of its containing block.
A UTXO response depends on the queried state. Bitcoin Core’s UTXO set reflects currently unspent outputs on its active chain. An indexer may also report mempool spends or historical outputs. Applications should not collapse confirmed UTXO state, mempool availability, and wallet reservations.
Address history is not native consensus state. It is derived by mapping address encodings or scripts to transactions.
Current chain tip and confirmations
APIs should expose chain-tip hash as well as height. Clients can then detect a same-height tip change and walk back to a common ancestor.
Confirmations are usually derived as current tip height minus transaction block height plus one, provided the block remains active. A cached confirmation number can become stale. A transaction can move from confirmed to unconfirmed after a reorganization.
For critical workflows, store the confirming block hash and compare it to the current active chain. Do not store only an integer confirmation count.
Mempool replacement and eviction
Mempool data is local. Transactions can enter, leave, be replaced, expire, be evicted for resource limits, conflict, or confirm.
APIs may report replacement relationships or removal reasons, but those are implementation and observation dependent. One provider may see a replacement that another never received. A transaction absent from a mempool is not necessarily invalid or impossible to confirm.
Webhook and subscription consumers should reconcile missed events. An “unconfirmed balance” should identify the backend that observed it.
Transaction broadcast responses
A broadcast endpoint may reject a transaction before submission, accept it into one node’s mempool, forward it to peers, or merely enqueue it for processing.
A successful acknowledgment is not confirmation. It may not even prove broad relay. Applications should separately monitor local mempool acceptance, provider observations, conflicts, and block inclusion.
Retries should be idempotent at the application level. Re-sending the same raw transaction is usually harmless, but re-running “create and send” may construct a different transaction or duplicate a withdrawal.
Raw transactions and PSBTs
Raw transactions can contain sensitive spending information before broadcast. PSBTs can contain UTXO data, key origins, scripts, derivation paths, proprietary fields, and partial signatures.
API logging should redact or restrict these payloads. Authorization should distinguish transaction construction, signing, finalization, and broadcast. A client allowed to query blocks should not automatically be allowed to sign or spend.
PSBT version and field compatibility must be explicit. APIs should not silently drop unknown fields or convert versions without reporting what changed.
Authentication, authorization, and rate limits
API keys, cookies, mutual TLS, OAuth-style tokens, service identities, and network controls can authenticate clients. Authorization should then limit methods, wallets, amounts, destinations, and administrative operations.
Rate limits protect availability but also affect correctness. A client that stops pagination early or fails after a partial page can build incomplete state. Quotas, burst behavior, and retry windows should be documented.
Administrative node methods should remain behind a separate boundary from public read methods. Wallet spending methods deserve stronger controls than wallet observation methods.
Pagination, cursors, timeouts, and retries
Historical endpoints need stable pagination. Offset pagination can change underneath a client when new records appear or reorganizations reorder data. Cursors should identify ordering and chain context where possible.
Timeouts should distinguish connection failure, server processing time, and unknown completion state. A request that times out may still have been processed.
Retries should use exponential backoff and idempotency semantics appropriate to the operation. Query retries differ from transaction-creation or withdrawal retries. Duplicate webhook delivery should be expected.
Applications should preserve enough identifiers to reconcile after uncertainty instead of assuming a timeout means “nothing happened.”
Errors, versioning, and deprecation
An API should separate transport errors, authentication errors, invalid parameters, policy rejection, consensus invalidity, missing index data, stale backend state, and internal failure.
Bitcoin Core RPC errors are implementation-specific. Hosted providers often normalize or replace them. Applications should log structured error categories without exposing secrets.
Versioning should cover fields, units, enum values, default behavior, and deprecation windows. Adding a field is not always harmless if clients reject unknown data. Removing a field can be dangerous if the application silently substitutes a default.
A provider’s default API version and a repository’s default branch are not reliable substitutes for explicit version pinning.
Amounts, fee rates, and size units
Bitcoin amounts should be transported as integer satoshis where possible. Floating-point numbers can introduce rounding errors.
Fee-rate units must be labeled. Satoshis per virtual byte, satoshis per kilobyte, and bitcoin per kilobyte are not interchangeable.
Transaction size can refer to raw bytes, virtual bytes, or weight units. SegWit weight is defined in weight units; virtual size is derived from weight. An API field named size should not be assumed to mean vsize.
Network identifiers should be explicit. Address parsing must confirm that the address or script belongs to the intended network and encoding.
Privacy leakage and hosted logs
Queries can reveal addresses, script hashes, xpubs, transaction IDs, IP addresses, timing, account relationships, and wallet activity.
Batching queries may reduce or increase linkage depending on the provider. Using Tor changes network metadata but does not prevent a logged xpub from linking the wallet. Self-hosting keeps more requests local but creates its own operational logs.
Privacy policies and retention claims are service-level statements, not Bitcoin protocol guarantees. Applications should minimize queries and avoid sending broader identifiers than required.
Caching and stale data
Caching block and transaction data can improve performance, but mutable metadata needs careful invalidation.
Raw confirmed transaction bytes are stable for a given txid, while active-chain membership, confirmation count, fee estimates, mempool status, and address balances can change. A reorganization can invalidate block-height associations. Index lag can make recently confirmed data appear unconfirmed.
Cache keys should include network and, where relevant, chain-tip or block-hash context. Applications should expose data freshness when it affects decisions.
Cross-checking and proofs
Critical data can be cross-checked across a validating node, multiple providers, or raw chain data. Provider agreement is useful operational evidence but is not itself consensus validation.
A Merkle proof can show that a transaction ID is included in a block whose header commits to the Merkle root. It does not prove that the block is valid, belongs to the best chain, or that the transaction satisfies every consensus rule unless the client validates the necessary headers, proof of work, chain selection, and transaction context.
Headers can support chain-work verification, but they do not contain the full transactions needed for complete validation.
Cross-checks should therefore state exactly what they establish.
Provider disagreement and observability
Applications should monitor:
- Chain-tip height and hash by source
- Sync lag
- Mempool disagreement
- Broadcast rejection categories
- Index freshness
- Webhook gaps
- Cache age
- Error and rate-limit trends
- Version and deprecation notices
Disagreement can result from propagation, policy, reorganization timing, pruning, index lag, or software differences. Preserve source-specific observations and reconcile them.
An API evaluation framework
For each endpoint, ask:
- What system produced the response?
- Does that system validate Bitcoin, index validated data, cache another service, or apply application logic?
- Which network, active-chain tip, and software version does it use?
- Is the value confirmed, mempool-derived, estimated, cached, indexed, or application-derived?
- Which fields require optional or external indexes?
- What authentication and authorization protect the operation?
- What happens during timeout, retry, duplicate delivery, replacement, eviction, or reorganization?
- Which units and integer formats are used?
- What privacy information does the request reveal?
- What evidence can be independently checked?
A well-designed application-facing API should answer those questions in its schema and operational documentation.
The working model
Bitcoin APIs are interfaces to systems around Bitcoin, not a single protocol authority.
Bitcoin Core RPC exposes one implementation’s node and wallet behavior. REST provides limited reads. ZMQ provides lossy notifications. P2P carries untrusted network messages. Electrum and Esplora services depend on indexes. Hosted providers add service and privacy dependencies. Lightning APIs belong to separate implementations. Application APIs add business state.
The safest design keeps node administration private, exposes narrow application methods, uses integer and explicit units, records source and chain-tip context, handles retries and reorganizations, and distinguishes raw, validated, indexed, cached, estimated, mempool, and application-derived data.
An API response can be useful without being independent proof of Bitcoin validity. Precision about that boundary is the foundation of reliable integration.