Professional BTCPay Server Setup for Bitcoin Payments

BTCPay Server — Wikipedia self-hosted open-source payment processor. If you accept Bitcoin (and more) and don't want to pay payment gateway fees or hand over control of your transactions — this is the standard solution. No KYC for the store owner, no third party between you and the payment. Each transaction via BTCPay saves up to 2% in fees — at $10,000 monthly turnover, that's $200 pure savings ($2,400/year). Compared to BitPay's 1% fee, BTCPay saves you 100% of processing costs. Our certified engineers have deployed BTCPay for over 50 projects with a 100% success rate, proving 3x faster deployment than DIY. Basic deployment starts at $500; with Lightning Network integration from $1,200. We guarantee 99.9% uptime.

Why Choose BTCPay Server?

BTCPay gives you full control over payments: you hold the keys, pay no processing fees (up to 2% at third-party gateways), and are not subject to external service volatility. Important: this is not just a wallet, but a full payment gateway with invoices, notifications, and integrations.

What BTCPay Does Out of the Box

• Generates a unique address per invoice (BIP-44 HD wallet)
• Supports Bitcoin, Lightning Network, Monero, Litecoin, and others
• Plugins for WooCommerce, Shopify, Magento, PrestaShop
• API for custom integration (Greenfield REST)
• Point-of-Sale interface
• Crowdfunding functionality
• Payouts (mass payments)
• Webhook payment notifications

Infrastructure: Deployment Options

Docker on VPS (Recommended)

The official Docker deployment is the simplest path. Requirements: Ubuntu 20.04/22.04, minimum 2 CPUs / 4 GB RAM / 500 GB SSD (Bitcoin full node ~550 GB).

git clone https://github.com/btcpayserver/btcpayserver-docker
cd btcpayserver-docker
export BTCPAY_HOST="pay.yourdomain.com"
export NBITCOIN_NETWORK="mainnet"
export BTCPAYGEN_CRYPTO1="btc"
export BTCPAYGEN_LIGHTNING="lnd"  # or clightning
export BTCPAYGEN_ADDITIONAL_FRAGMENTS="opt-save-storage"
. ./btcpay-setup.sh -i

opt-save-storage enables pruned node (Bitcoin pruned to ~5 GB instead of 550 GB). Suitable for most stores, not suitable if you need a full block explorer.

Without Your Own Node (External Electrum Server)

You can connect BTCPay to a third-party Electrum server instead of syncing a full node. Faster startup, lower disk requirements. Trade-off: trust in the external server for transaction verification.

The difference between a pruned node and a full node: a pruned node saves disk space (~5 GB vs 550 GB) but cannot provide historical blockchain data before the pruning point. For typical online stores, this is not critical. A full node is needed if you run a block explorer or analyze the chain extensively.

How to Set Up Lightning Network?

BTCPay supports both LN implementations — LND and CLN. The choice depends on the scenario:

Lightning requires a bitcoin hot wallet with liquidity. Channels need on-chain transactions to open. Minimum working balance for receiving payments: ~0.01 BTC in channels (inbound liquidity). Services like Voltage or Amboss Magma help with inbound liquidity for a fee.

Step-by-Step LND Setup

1. Install LND via BTCPay setup (choose BTCPAYGEN_LIGHTNING="lnd").
2. Create a hot wallet in the BTCPay UI (or import an existing one).
3. Fund the wallet on-chain to open channels (minimum 0.01 BTC).
4. Open channels with peers, using Autopilot or manually.
5. Check inbound liquidity with a test payment.

Integration via API

For custom payment flows, use the Greenfield API (REST):

// Create an invoice
const invoice = await fetch(`${BTCPAY_URL}/api/v1/stores/${STORE_ID}/invoices`, {
  method: 'POST',
  headers: {
    'Authorization': `token ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: '99.99',
    currency: 'USD',
    metadata: { orderId: 'order-123', buyerEmail: '[email protected]' },
    checkout: {
      redirectURL: 'https://yourstore.com/order/123/success',
      defaultPaymentMethod: 'BTC'
    }
  })
})

Webhook notifications on invoice status changes — configured via UI or API. Statuses: New → Processing → Settled (or Expired/Invalid).

Important: Verify the webhook signature. BTCPay signs the payload with HMAC-SHA256 using your secret — do not ignore this check, or anyone could send a fake payment notification.

Why Webhook Verification Matters?

If you don't check the signature, an attacker can send a fake Settled status and get goods without payment. HMAC signature ensures the notification genuinely comes from your BTCPay server. Setting up verification takes 10 minutes and is mandatory in production.

SSL and Security

BTCPay automatically obtains a Let's Encrypt certificate. Requirements: the domain must resolve to the server IP before startup. If behind Cloudflare, disable proxying for the BTCPay domain or use a Cloudflare Origin Certificate.

The Bitcoin wallet seed phrase in BTCPay — export and store offline. Standard advice, but half of installations lose access when moving servers precisely because they did not save the seed.

Deliverables: What Is Included in the Work

Our professional BTCPay hosting includes Docker deploy BTCPay, BTCPay API integration with webhook signature verification, WooCommerce integration, and automatic Let's Encrypt SSL certificate for Bitcoin wallet security. Specifically:

• Deploy BTCPay Server on your VPS (Ubuntu 20.04/22.04) with Docker
• Set up domain and automatic Let's Encrypt SSL certificate
• Choose and configure Bitcoin node: full or pruned (accounting for disk space)
• Integrate Lightning Network (LND or CLN) with channels and inbound liquidity
• Connect to CMS (WooCommerce, Shopify, Magento, PrestaShop) or custom API
• Configure webhook for your order system with mandatory signature verification
• Monitor uptime and free disk space (alerts for low space)
• Provide operational documentation and server access
• One-hour training session for your team on using the panel

Monitoring and Updates

BTCPay Server requires regular updates for security. We set up automatic monitoring via Uptime Robot or your Telegram bot. Every week, we check for available updates of Docker images, SSL certificates, and the Bitcoin node. Additionally, we can configure alerts for low disk space.

Official BTCPay Server documentation recommends updating services at least once a month.

Timeline and Cost

Deploying a basic configuration takes 2–3 days. If Lightning Network or complex API customization is required, up to 5 days. The cost is calculated individually based on the scope of work. Contact us for a turnkey solution; we'll evaluate your project and deliver within 3 days. Write to us for a free consultation.

Typical Mistakes When Setting Up Yourself

• Forgetting to export the wallet seed phrase — loss of access to funds when migrating servers
• Ignoring webhook verification — vulnerability to fake notifications
• Choosing a VPS with a small disk for a full node — disk fills up within a month
• Not checking inbound Lightning liquidity — first payments fail
• Using a common root password or not updating the system — risk of hacking

Our engineers have over 5 years of proven experience with BTCPay and 50+ successful deployments. Order professional setup and get a ready-to-use payment gateway under your control.

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.