Implementing Bitcoin Payments

To accept bitcoin payments reliably, generate a unique address for each order. The first and most critical mistake we see in integrating Bitcoin payments is using a single address for all customers. Two users could send the same amount in one transaction, generate multiple UTXOs partially covering the sum, or encounter batching from the exchange. The correct approach is to generate a unique address for each payment. In our practice, when integrating for a marketplace, we solved the address duplication issue, reducing payment processing time by 30% and eliminating confusion with credits.

Bitcoin: A Peer-to-Peer Electronic Cash System — Satoshi Nakamoto

How address derivation works

The BIP-32/BIP-44 standard allows generating an infinite tree of addresses deterministically from a single master seed. For receiving payments, we use an xpub (extended public key) – the public part stored openly on the server to generate addresses. The private key remains separate (cold storage, hardware wallet) and is only needed for withdrawals.

Master Seed → xpub (m/44'/0'/0')
             ↓
  index=0: 1A1zP1... (payment #1)
  index=1: 1B2zP2... (payment #2)
  index=N: ...       (payment #N)

The BIP-44 derivation path for Bitcoin mainnet: m/44'/0'/account'/change/index. For receiving, change=0, index is incremented. For Native SegWit, we use BIP-84 with path m/84'/0'/0'. BIP84 (Native SegWit) is 37% cheaper than BIP44 (Legacy) and 20% cheaper than BIP49 (Wrapped SegWit).

How to ensure a unique address for each payment?

Use the extended public key (xpub) and an index corresponding to the order ID in your database. This guarantees that a customer cannot reuse an old address and you avoid payment overlaps. Never generate addresses randomly – always deterministically.

Address types comparison

Native SegWit (bc1q) saves up to 40% on fees compared to Legacy – almost twice as cost-effective for the customer. Taproot with Schnorr signatures allows transaction aggregation, further reducing block size by 20% relative to Native SegWit.

Implementation: Node.js + bitcoinjs-lib

import * as bitcoin from 'bitcoinjs-lib'
import { BIP32Factory } from 'bip32'
import * as ecc from 'tiny-secp256k1'

bitcoin.initEccLib(ecc)
const bip32 = BIP32Factory(ecc)

const NETWORK = bitcoin.networks.bitcoin // or networks.testnet

// One-time: generate xpub from seed (performed in cold storage)
// const seed = bip39.mnemonicToSeedSync(mnemonic)
// const root = bip32.fromSeed(seed, NETWORK)
// const account = root.derivePath("m/84'/0'/0'") // BIP-84 for Native SegWit
// const xpub = account.neutered().toBase58()
// console.log(xpub) // store in .env as BITCOIN_XPUB

// On server: generate address by index
function getPaymentAddress(xpub: string, index: number): string {
  const node = bip32.fromBase58(xpub, NETWORK)
  const child = node.derive(0).derive(index) // external chain, index N
  const { address } = bitcoin.payments.p2wpkh({
    pubkey: Buffer.from(child.publicKey),
    network: NETWORK,
  })
  if (!address) throw new Error('Failed to derive address')
  return address
}

Follow these steps to setup a bitcoin payment gateway using an HD wallet BIP32:

1. Generate an xpub from a master seed in cold storage using BIP32 or BIP84.
2. Store the xpub in your server environment.
3. For each new order, derive a unique address using the order index.
4. Save the payment details in the database.
5. Monitor the address for incoming transactions via electrs.
6. Update payment status based on confirmations.
7. Handle edge cases like overpayment and underpayment.

Database schema for payments

CREATE TABLE bitcoin_payments (
  id          BIGSERIAL PRIMARY KEY,
  order_id    UUID NOT NULL REFERENCES orders(id),
  address     VARCHAR(62) NOT NULL UNIQUE,
  hd_index    INTEGER NOT NULL UNIQUE,
  amount_sat  BIGINT NOT NULL,           -- amount in satoshis
  status      VARCHAR(20) DEFAULT 'pending', -- pending/underpaid/confirmed/expired
  created_at  TIMESTAMPTZ DEFAULT NOW(),
  expires_at  TIMESTAMPTZ NOT NULL,
  confirmed_at TIMESTAMPTZ,
  tx_hash     VARCHAR(64)
);

CREATE INDEX ON bitcoin_payments(address);
CREATE INDEX ON bitcoin_payments(status) WHERE status = 'pending';

Transaction monitoring

For production, we use our own Bitcoin node with electrs. Public APIs (Blockstream) are only suitable for prototypes. For bitcoin transaction monitoring, we subscribe via WebSocket. Example:

import ElectrumClient from 'electrum-client'

const client = new ElectrumClient(50002, 'your-electrs-host', 'tls')
await client.connect('payment-monitor', '1.4')

async function watchAddress(address: string, onPayment: (tx: any) => void) {
  const scriptHash = addressToScriptHash(address) // sha256 reversedLE
  await client.subscribe.on('blockchain.scripthash.subscribe', async (updates) => {
    const [scripthash, status] = updates
    if (scripthash === scriptHash && status !== null) {
      const history = await client.blockchainScripthash_getHistory(scriptHash)
      onPayment(history)
    }
  })
  await client.blockchainScripthash_subscribe(scriptHash)
}

Number of confirmations

Zero-conf is acceptable only for physical points with small amounts and RBF=false. In e-commerce, we wait for at least one confirmation.

How to handle edge cases correctly?

Bitcoin overpayment handling – we credit the full amount and keep the difference on the user's balance. Refund is only possible if the customer provides a return address.

Underpayment – we freeze the payment and ask to top up to the same address within the order lifetime. We never treat a partial amount as full.

Expiry – the address has "expired" but a transaction still arrives. We keep such addresses active for another 24 hours for crediting, but do not show them for new payments.

Do not trust unconfirmed transactions with BIP125-opt-in-RBF=true. Wait for at least one block.

The built-in logic should differentiate statuses: pending, underpaid, confirmed, expired. For underpaid, automatically extend the wait time by 15 minutes. For expired, cancel the order but retain the ability to credit on late transaction (manually).

Withdrawals

For UTXO withdrawal, we use PSBT with proper coin selection. We recommend sweeping once a day with a script, rather than triggering automatically on every payment – this reduces the number of transactions and fees.

What's included in the work

• Design of HD wallet architecture
• Server-side implementation on Node.js with bitcoinjs-lib (Bitcoin payment gateway Node.js)
• Integration of electrs for transaction monitoring
• Database schema and payment logic (overpayment, underpayment, expiry)
• API documentation and operation manual
• Administrator training on the panel
• 30-day warranty on correct payment gateway operation

Our engineers hold blockchain certifications and have implemented payments for 20+ projects. We offer a free assessment for your project. Get a consultation for your project — write to us. Order a turnkey payment gateway implementation.

Blockchain Infrastructure Deployment: Nodes, RPC, Indexing

Subgraph fell at 3:47 AM. By morning users saw outdated balances, transactions "hung" in the UI, support received 47 tickets in an hour. Cause: the handler in the subgraph failed on a transaction with a non-standard event log — and the entire index stopped. We have encountered such situations dozens of times. Our experience shows: blockchain infrastructure does not forgive gaps in observability. Guaranteeing uptime without multi-layered monitoring and fault-tolerant architecture is impossible. Over 8 years working with Ethereum, Polygon, and Solana, we have developed an approach that allows predictable deployment of infrastructure of any scale — from a single node to a multichain grid with dozens of subgraphs.

RPC Layer Architecture

Every dApp interaction with the blockchain goes through RPC — the JSON-RPC API provided by a node. Three options:

Managed providers — Alchemy, QuickNode, Infura, Ankr. Minimal operational costs, SLA, built-in monitoring. Limits: rate limits (Alchemy Free: 300 RU/sec), vendor lock, potential downtime during provider incidents. For most projects — the right choice at the start.

Self-owned nodes — full control, no rate limits, no third-party dependence. Cost: archive Ethereum node requires 2.5–3TB SSD, a strong server, and DevOps support. Sync from scratch on Ethereum via Geth/Nethermind — 3–7 days. Justified under high load or latency requirements.

Hybrid — self-owned node as primary, managed provider as fallback. Standard for protocols with high TVL. Proper load balancing can reduce costs by 20–30% compared to pure managed setup. Under high monthly request volume, hybrid saves significantly.

How to Set Up an RPC Layer Without a Single Point of Failure?

At least two providers, DNS round-robin with health check every 5 seconds, automatic fallback when latency >500 ms. In practice, this gives 99.99% availability during any provider failure. For protocols with high TVL, we recommend a custom HA-proxy (nginx or Envoy) in front of two managed providers.

Why Is a Hybrid RPC Scheme More Cost-Effective Than Pure Managed?

At high request volumes, managed providers can be very expensive; a hybrid using a self-owned node as primary and a managed fallback cuts costs significantly without losing SLA.

Ethereum Node Clients

Execution clients: Geth (most used), Nethermind (C#, fast sync), Besu (Java, enterprise), Erigon (fastest sync, efficient archive mode ~2TB instead of 3TB).

Consensus clients (post-Merge): Lighthouse (Rust), Prysm (Go), Teku (Java), Nimbus (Nim). Each node after The Merge requires a pair of execution + consensus clients.

For DevOps: eth-docker — Docker Compose configurations for all client combinations. Setting up monitoring via Grafana + Prometheus is mandatory; a standard dashboard is available in each client's repository.

The Graph: Event Indexing

The Graph Protocol — decentralized indexing. A subgraph describes which events from which contracts to index and how to transform them into a GraphQL schema.

Subgraph structure:

• subgraph.yaml — manifest: contract addresses, startBlock, events to handle
• schema.graphql — GraphQL schema of entities
• src/mapping.ts — AssemblyScript event handlers

dataSources:
  - kind: ethereum
    name: UniswapV3Pool
    network: mainnet
    source:
      address: "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640"
      abi: UniswapV3Pool
      startBlock: 12370624
    mapping:
      eventHandlers:
        - event: Swap(indexed address,indexed address,int256,int256,uint160,uint128,int24)
          handler: handleSwap

AssemblyScript handlers — not TypeScript. No nullable types, no closures, no many standard APIs. An error in the handler stops the subgraph indexing on that transaction. Important: add try-catch for operations that can fail (e.g., store.get() for an entity that may not exist).

How to Avoid Subgraph Indexing Stops?

Graph Node logs are monitored in real-time; on hasIndexingErrors = true an alert fires and an automatic node restart (via systemd or Kubernetes). Typical downtime on error — 150–300 seconds to recover. Additionally, for production we set up a watchdog that restarts Graph Node if subgraph lag exceeds 50 blocks.

Choosing Between Hosted Service and Decentralized Network

Graph Hosted Service (free, centralized) is deprecated in favor of Subgraph Studio + Graph Network. For production: deploy on Graph Network with GRT curation signal — the subgraph gets indexers proportional to curation.

Alternatives to The Graph: Ponder (TypeScript, self-hosted, easier to debug), Envio (ultra-fast indexer, supports EVM + non-EVM), Subsquid (TypeScript, own network), Moralis Streams (managed, webhook-based). Our experience shows: for high-load projects with unique logic, Ponder or Envio are more effective — they give full control over the process and do not require GRT tokenomics.

Webhooks and Real-Time Notifications

Alchemy Webhooks and QuickNode Streams allow receiving events in real-time via HTTP webhook or WebSocket. For monitoring addresses, new transactions, mints — this is faster than polling RPC.

Tenderly — platform for monitoring and alerts. You can set up an alert for a specific contract event, balance change, function call with certain parameters. Transaction simulation via Tenderly API is invaluable for debugging.

Monitoring and Observability

Minimum monitoring stack for a protocol:

On-chain: OpenZeppelin Defender Sentinel — watches contract events, triggers webhook or Autotask when conditions are met. Forta Network — community-maintained bots detect anomalies (large withdrawals, flash loans, governance attacks).

Infrastructure: Grafana + Prometheus for nodes, Datadog or Grafana Cloud for managed metrics. Alerts on: node is 10+ blocks behind, RPC latency >500ms, subgraph lag >100 blocks.

Uptime: Better Uptime or PagerDuty on RPC endpoint and subgraph health endpoint (The Graph provides _meta { hasIndexingErrors, block { number } }).

Why Is Monitoring Without Tenderly Insufficient?

Tenderly provides transaction simulation and detailed traces — critical for debugging subgraph and smart contract errors. Forta focuses on network anomalies, not your infrastructure. The combination of Tenderly plus a custom Grafana dashboard covers 90% of incident scenarios.

Multichain Infrastructure

A protocol on 5 chains = 5 separate RPC endpoints, 5 subgraphs, 5 monitoring configs. Manageable but requires deployment automation.

For subgraph multi-network deployment: graph deploy --network mainnet, graph deploy --network arbitrum-one etc. with a unified codebase and network-specific addresses in separate config files.

Chainlink CCIP and LayerZero for cross-chain messaging require monitoring of both chains and transactions on intermediate relayers. A reorg on the source chain after a confirmed mint on the target chain is a classic bridge problem. Solution: wait for finality (on Ethereum ~15 minutes after Merge for economic finality) before confirming on the target chain.

Infrastructure Setup Process

1. Audit current stack — determine chains, request volume, latency and availability requirements.
2. Architecture design — select providers, load balancing, redundancy.
3. Subgraph development — manifest → schema → handlers → testing on local Graph Node → deploy to testnet → mainnet.
4. Monitoring configuration — Tenderly alerts, Grafana dashboard, PagerDuty integration.
5. Documentation and runbook — what to do when: subgraph falls behind, RPC downtime, node desync.
6. Handover to operations — team training, access transfer, first month support.

What's Included

• Deployment of managed or self-hosted Ethereum, Polygon, BNB Chain nodes
• RPC layer setup with primary/fallback and load balancing
• Subgraph development and deployment for your protocol
• Monitoring connection (Tenderly, Grafana, alerts)
• Runbook and operations documentation
• Team training (up to 4 hours online)
• 30-day support after delivery

Timeline

All projects are managed in a GitHub/GitLab repository with CI/CD; configuration code stays with you. Order infrastructure deployment — we'll show how to cut costs by 20–30% without losing reliability. Get a consultation — we'll demonstrate how we deployed infrastructure for a protocol with large TVL on Ethereum and Arbitrum. Contact us.