Bitcoin API: Accept BTC Payments Without Running a Node

Bitcoin Core's JSON-RPC wants a synced node before the first useful response. A REST API wants an API key. The difference shows up in your calendar: initial block download takes days on typical hardware, and after that the node consumes disk and bandwidth, and still needs monitoring, for as long as your product lives. Our article on blockchain API vs. blockchain node compares both approaches in detail. Run your own node when you need policy-level control over your view of the network; use the API when payments are the goal.

The day-to-day calls map cleanly onto the REST model. Where a node integration wraps getnewaddress and listtransactions and polls for changes, the API assigns addresses and lets the webhook do the watching. Polling loops disappear, and with them the cron jobs that break silently on a weekend.

There is a second difference. Raw RPC methods return raw data. Chaingateway returns structured JSON with readable fields, so a response can go straight into your database instead of through a parsing layer.

The REST side of the send path is three endpoints. POST /api/v2/bitcoin/wallets creates a wallet, encrypted with a password that Chaingateway does not store — lose it and nobody can restore the wallet, which is the point. POST /api/v2/bitcoin/wallets/{wallet}/addresses derives as many addresses under it as you need; one wallet carries them all. And POST /api/v2/bitcoin/transactions sends:

curl -X POST https://app.chaingateway.io/api/v2/bitcoin/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
    "amount": 0.0015,
    "walletname": "treasury",
    "password": "wallet-password",
    "speed": "medium"
  }'

The response carries the txid of the broadcast transaction. speed takes fast, medium or slow and sets the fee level — the trade-off between cost and time to first confirmation. An optional subtractfee: true deducts the network fee from the amount instead of adding it on top, which is what you want when a customer withdraws their full balance.

Bitcoin adds a block roughly every ten minutes, though individual gaps vary widely. Each new block mined on top of the one containing your transaction adds a confirmation, and every confirmation makes reversal harder.

Six confirmations — about an hour — has been the de-facto standard for "settled" since the early exchange days, and it still holds as of mid-2026.

Ten minutes is an average, not a schedule

The difficulty adjustment holds it over time, but individual gaps scatter widely around it — two blocks inside a minute happen, and so do forty-minute droughts. Payment UX has to respect this: "about ten minutes" is an average, not a promise, so your checkout page should say "usually within the hour" rather than run a countdown timer it cannot keep.

Why not credit at zero confirmations?

Because until a transaction is in a block, it sits in the mempool, where it can be replaced or double-spent, and even the newest block can drop out of the chain in a reorganization. The API splits that work in two. The webhook fires once the transaction settles on-chain — the payload carries amount, address, txid and block number — so your UI can react right away. From there, GET /api/v2/bitcoin/transactions/{txid}/decoded returns the current confirmation count, so your ledger credits only money that has reached your threshold. Show progress early, settle late.

Bitcoin has no account balances. What the chain stores are unspent transaction outputs — UTXOs — each one a discrete lump of value locked to an address. A wallet's "balance" is a number your software derives by summing every UTXO its addresses control; the protocol never stores that sum anywhere. Spending consumes whole UTXOs and creates new ones, including a change output back to yourself, the way paying a 7-euro bill with a 10-euro note returns coins.

Ethereum runs the opposite model. An account has one balance, the chain stores it directly, and a deposit is an increment. On EVM chains it is normal to hand a customer one address and let a hundred deposits pile up on it over the years.

For deposit handling, the UTXO model has a practical upside: it pushes you toward one address per customer or per invoice, which is the cleaner design anyway. Every incoming payment is a new output to an address you watch, so attribution is unambiguous — no memo parsing, no matching by amount. It also means "the balance of an address" is a question an indexer answers rather than the chain, which is precisely the bookkeeping you outsource by using an API with webhooks instead of running the machinery yourself. The notification tells you: this amount, this address, this transaction, this block. Your ledger does the rest.

Add the header X-Network: testnet and every call on this page runs against Bitcoin's test network: same routes, same response shapes, coins with no value. Faucets hand out test BTC for free, so the entire deposit flow — address, payment, webhook, confirmations — can be rehearsed end to end without spending a satoshi.

Keep the header behind configuration rather than scattered through the code, and give your staging environment a separate callback URL so test deposits cannot leak into the production ledger. When the rehearsal works, remove the header. Nothing else about the integration changes, which is the point: the first mainnet deposit should be boring.

A payments backend earns its keep on the bad days, so plan the failure paths explicitly.

On the HTTP layer the rules are standard REST. A 401 means the Bearer token is wrong or missing; fix the key rather than retrying. Other 4xx responses point at the request itself — log the body, which names the problem, and treat it as a bug. Responses in the 5xx range and timeouts are transient; retry those with backoff.

The Bitcoin-specific failure modes live above HTTP. A deposit that never confirms usually paid too little fee and is stuck in the mempool; it may confirm hours later or drop out entirely, which is why detected and settled must stay separate states in your system. A notification for an amount below the invoice is a business decision, not an error — handle it in code, not in a support queue. And if your webhook endpoint was down, the failed deliveries wait for you: GET /api/v2/bitcoin/webhooks/notifications/failed lists them, POST /api/v2/bitcoin/webhooks/notifications/{id}/retry re-sends each one, and the full list at GET /api/v2/bitcoin/webhooks/notifications lets you diff against the ledger and credit the gaps. Run that comparison nightly even when nothing looks wrong. Reconciliation that only runs after incidents finds its bugs in production.

Bitcoin itself has no USDT or USDC — stablecoins live on other chains. What the shared platform gives you is a head start: your Bitcoin integration already speaks the same API as our Ethereum and TRON endpoints. Accept BTC today, add USDT on TRON next sprint with the same key and the same webhook handler. The blockchain API overview lists all seven supported chains.

The practical order for most teams: launch BTC deposits first, because that is what customers ask for by name, then let payment data tell you which stablecoin rail to add second. On Chaingateway, that second rail reuses your signature verification, your reconciliation job and your deposit state machine unchanged.

• It has the longest track record of any blockchain, running since 2009, and the widest recognition among end users.
• The network settles around the clock. There are no banking hours and no regional cutoffs.
• Confirmations follow a predictable rhythm, with a new block roughly every ten minutes, which keeps payment workflows easy to reason about.
• Adoption is the largest of all crypto networks, so "do you take Bitcoin?" is still the first question customers ask.

None of these properties came from a roadmap update; they are the same guarantees the network shipped with. That stability is the argument for BTC in products with long horizons: an integration built this year will not be obsoleted by a protocol pivot next year, which is more than most payment stacks can claim.

The obvious case is checkout: a customer picks Bitcoin and your app assigns an address; the webhook confirms the payment. The same building blocks carry heavier loads too. Exchanges and gaming platforms run one deposit address per user and credit balances on confirmation. Payout and remittance flows push cross-border transfers without correspondent banks in the middle. Subscription businesses generate a fresh invoice address each cycle and let the webhook close it out.

What these cases share is the shape of the work. Bitcoin handles settlement; your application handles state. The API sits between the two and turns chain events into HTTP calls your framework already knows how to route — which is why the checkout case and the exchange case run on the same handful of endpoints.