Chaingateway Bitcoin API

Search for a Bitcoin API and the first result is Bitcoin Core's RPC reference. It is the canonical interface to the network, and it assumes you operate a full node: install bitcoind, sync roughly several hundred gigabytes of chain data, keep the machine online, and repeat the upgrade cycle every release. For some projects that is the right path. If you want to accept BTC payments in your application, it is a detour.

Chaingateway's Bitcoin API is the REST alternative. You create wallets and deposit addresses over plain HTTPS, send BTC with a single POST, and get a webhook when coins arrive. It is a BTC API in the plainest sense: HTTPS in, JSON out. Authentication is a Bearer token from a free 7-day trial — no node, no KYC to start.

Bitcoin over REST instead of JSON-RPC

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.

What you'd need with bitcoin-core RPC, side by side

The comparison gets concrete once you list the actual work. Suppose the job is "give each customer a deposit address and credit their account when BTC arrives."

Task	With Bitcoin Core (JSON-RPC)	With the REST API
Prerequisite	a synced full node: bitcoind plus several hundred GB of chain data	an API key
New deposit address	getnewaddress per customer, plus a wallet backup regime you script yourself	POST /api/v2/bitcoin/wallets/{wallet}/addresses
Detect incoming BTC	configure walletnotify, or poll listsinceblock / gettransaction on a timer	signed webhook POST to your server
Send BTC	sendtoaddress, plus a hot wallet in the node, fee settings and wallet-file backups you own	POST /api/v2/bitcoin/transactions
Track confirmations	re-poll gettransaction until the count satisfies your policy	poll GET /api/v2/bitcoin/transactions/{txid}/decoded, which carries the confirmation count
Audit trail	parse listtransactions output and dedupe in your own code	GET /api/v2/bitcoin/webhooks/notifications
Ongoing cost	disk, bandwidth, upgrades, monitoring	the provider's problem

Outbound payments deserve the closer look. sendtoaddress looks like one call, but it presumes a hot wallet inside your node, fee settings you own and a tested backup of the wallet file. Even getbalance is narrower than it appears: it reports the node wallet's balance, not an arbitrary address's, so exchange-style accounting still lands in your code. None of this is a criticism of Bitcoin Core — it is the reference software for operating the network and good at that job. It was never meant to be the payments backend of a web application, which is why so much glue code accumulates around it.

Sending BTC over REST

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.

Everything you need to accept BTC

Webhooks (IPN)

Instant payment notifications for incoming transactions, sent as soon as a matching transaction settles on-chain. Set a personal secret in your profile and each notification carries an X-Signature header your server can verify. Deliveries that failed are listed at GET /api/v2/bitcoin/webhooks/notifications/failed and can be re-sent with one call.

Predictable REST endpoints

Create addresses and track payments with a clean, consistent API. Requests and responses look like the rest of the Chaingateway platform, so a developer who has integrated one chain reads the Bitcoin responses without a manual.

Secure address handling

Non-custodial by design, with address validation built in. Malformed or mistyped addresses fail before anything touches the chain.

Decoded queries

Transaction data arrives as structured JSON instead of raw hex, including the amounts and confirmation state your backend acts on.

Block times and confirmations: what to expect

Bitcoin adds a block roughly every ten minutes. The difficulty adjustment holds that average 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.

Each new block mined on top of the one containing your transaction adds a confirmation, and every confirmation makes reversal harder. A widely used scheme ties the threshold to the amount at stake: one confirmation for small payments up to roughly $1,000, three for mid-sized amounts up to about $10,000, six for anything large, and ten or more when a single transfer runs past a million dollars. 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.

Why not credit at zero confirmations and be fast? 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.

UTXOs: why Bitcoin deposits differ from EVM chains

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.

The deposit flow, step by step

Most Bitcoin integrations at Chaingateway center on deposits: an address per customer, a webhook per payment.

1. Assign each customer a deposit address from your wallet (POST /api/v2/bitcoin/wallets/{wallet}/addresses).
2. The customer sends BTC.
3. Once the transaction settles on-chain, Chaingateway POSTs a signed notification to your server, carrying amount, address, txid and block number.
4. Your backend verifies the signature and credits the account once the confirmation count — read from GET /api/v2/bitcoin/transactions/{txid}/decoded — meets your threshold.

Two implementation notes. Delivery is not exactly-once — a failed notification you re-send through the API arrives again in full — so make your handler idempotent and key credits to the transaction ID rather than counting callbacks. And confirmations exist for a reason: the newest block can still be orphaned in a reorg, which is why the credit decision belongs to the confirmation count, not to the webhook alone.

It helps to model each deposit as a small state machine rather than a boolean. An order starts at awaiting_payment, moves to detected when the webhook fires, advances through confirming while your poller watches the confirmation count, and lands on settled once the threshold is met — with underpaid and expired as explicit side exits. Customers who send 0.00095 BTC against a 0.001 BTC invoice exist, usually because their wallet deducted the network fee from the entered amount; decide in advance whether your tolerance absorbs the shortfall or the order waits for a top-up. And give invoices an expiry. Exchange rates move, so an address that matched the invoice amount on Monday should not settle at a stale price the following week.

For auditing and reconciliation, every notification your account has received can be listed through the API:

curl https://app.chaingateway.io/api/v2/bitcoin/webhooks/notifications \
  -H "Authorization: Bearer YOUR_API_KEY"

// Reconcile deposits after a deploy or an outage
const response = await fetch(
  "https://app.chaingateway.io/api/v2/bitcoin/webhooks/notifications",
  { headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
const notifications = await response.json();
// Compare against your database and credit anything you missed

import requests

notifications = requests.get(
    "https://app.chaingateway.io/api/v2/bitcoin/webhooks/notifications",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
).json()
# Diff against your ledger; credit whatever a bug or outage swallowed

<?php
$ch = curl_init('https://app.chaingateway.io/api/v2/bitcoin/webhooks/notifications');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer YOUR_API_KEY']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$notifications = json_decode(curl_exec($ch), true);
curl_close($ch);

Webhook setup and signature verification are covered in the webhook guide, and the quickstart takes you from key to first request.

Testnet first

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.

When something fails

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.

Need stablecoins next to BTC?

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.

Why developers build on Bitcoin

• 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.

Built for real payment use cases

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.

Integration in four steps

1. Get your API key. Sign-up is free and the trial starts without KYC.
2. Make your first request. Confirm the key with GET /api/account, then create a wallet and your deposit addresses.
3. Set up webhooks. Point notifications at your endpoint and verify the HMAC signature.
4. Go live. Drop the X-Network: testnet header and the identical code runs on mainnet.

Going from zero to a production-ready integration in under an hour is realistic, because there is nothing to install and nothing to sync.

Frequently asked questions

How are private keys handled?

Wallets are password-protected and stored encrypted, and the architecture is non-custodial: without your credentials, funds cannot be moved.

Do I need to run a Bitcoin full node?

No. Chaingateway operates the infrastructure; your application talks HTTPS. If you are weighing a self-hosted node against the API, our node comparison covers the maintenance side honestly.

Do you support testnet?

Yes. Add X-Network: testnet to any request and it runs against the test network, with the same endpoints and response formats but worthless coins.

When should I credit a deposit?

That depends on your risk tolerance. The webhook tells you the payment settled; the current confirmation count comes from GET /api/v2/bitcoin/transactions/{txid}/decoded. So you set the threshold per amount: a small order might ship after the first confirmation, a large withdrawal after several. The block-times section above lists the thresholds most platforms use.

How long does a Bitcoin payment take?

Blocks arrive roughly every ten minutes on average, with wide variance in both directions. A transaction with a sufficient fee reaches its first confirmation after ten minutes on average; the classic six-confirmation standard takes about an hour. Fee level matters too: a transaction that underpays during a busy period waits longer for its first block, sometimes hours.

What is a reorg, and should I care?

A reorganization replaces the newest block or blocks with a competing chain, and any transaction that existed only in the replaced blocks returns to pending. Single-block reorgs are rare and deeper ones rarer still, but they are the reason confirmation thresholds exist. Credit only after your threshold and reorgs remain a statistic, not an incident.

Why one address per customer instead of a shared address?

Attribution. On a shared address you have to match payments to customers by amount or timing, which breaks the day two invoices total the same sum. A dedicated address makes every incoming output self-identifying, and since addresses cost nothing to create, there is no reason to economize on them.

How is this different from a hosted payment processor?

A processor typically takes custody of the funds, settles later and requires KYC before payouts. Chaingateway is an API on top of the chain itself: deposits land on addresses tied to your own wallet, and what happens next is your code's decision. You get the raw building blocks, not an opinionated checkout.

Can I reuse the integration for other chains?

Yes. The same API covers Ethereum, TRON, Solana, BNB Smart Chain, Polygon and Arbitrum. Routes differ only in the chain segment of the path.

What about rate limits and pricing?

Plans and their limits are listed on the pricing page. Every plan starts with the free 7-day trial.

The fastest way to evaluate is a testnet run. Create an account and point a webhook at a request bin. Send yourself test BTC; if the flow fits, mainnet is one header away.