Skip to main content

​
BTCPay Agentbot

This integration is in progress. The BTCPay Agentbot stack is documented here as an active implementation track, but some user-facing wiring in the main Agentbot product is still being completed.
BTCPay Agentbot

​
Overview

BTCPay Agentbot brings Bitcoin-native payments to the Agentbot platform. Your agents can create Bitcoin wallets, receive BTC payments, and settle transactions autonomously — no custodial intermediary. Built on BTCPay Server and NBXplorer, it runs as a headless service on your infrastructure alongside the Agentbot stack.

​
Architecture

Agent Wallets (NBXplorer)
        ↓
    bitcoind (pruned, 10GB)
        ↓
   PostgreSQL (agent metadata)
Headless stack — no UI, just the engine:
ComponentImagePortPurpose
agentbot_bitcoindbtcpayserver/bitcoin:29.143782Bitcoin node (testnet/mainnet)
agentbot_nbxplorernicolasdorier/nbxplorer:2.6.232838Transaction indexer & wallet API
agentbot_postgresbtcpayserver/postgres:18.1-15432Database for NBXplorer

​
Quick Start

​
1. Clone the Docker repo

git clone https://github.com/EskyLab/btcpayagentbot-docker.git
cd btcpayagentbot-docker

​
2. Start the headless stack

docker compose -f docker-compose.headless.yml up -d

​
2.5 Current status

  • Headless BTCPay stack is the current target architecture
  • NBXplorer is the wallet-facing API layer for agents
  • Main product docs and integration points are still being expanded
  • Expect the fastest progress on self-hosted and operator-led setups first

​
3. Verify

# Check all containers are running
docker compose -f docker-compose.headless.yml ps

# Verify NBXplorer API
curl http://localhost:32838

# Check Bitcoin node
curl -s --user btcrpc:btcpayserver4ever \
  -d '{"jsonrpc":"1.0","method":"getblockchaininfo","params":[]}' \
  http://localhost:43782

​
Configuration

The headless stack uses these environment variables in .env: 
NBITCOIN_NETWORK=testnet      # testnet or mainnet
BTCPAYGEN_CRYPTO1=btc         # Bitcoin only
BTCPAYGEN_REVERSEPROXY=none   # No UI proxy

​
Pruning

Bitcoin node is pruned to 10GB by default (prune=10000). Adjust in docker-compose.headless.yml: 
bitcoind:
  environment:
    BITCOIN_EXTRA_ARGS: |
      prune=10000    # MB — adjust as needed

​
Fast Sync

Skip full chain sync by downloading a UTXO snapshot: 
cd btcpayagentbot-docker
sudo ./contrib/FastSync/load-utxo-set.sh
This reduces sync time from days to minutes.

​
Agent Wallet API

NBXplorer provides a REST API for agent wallet operations:

​
Create a wallet

POST http://localhost:32838/v1/cryptos/btc/derivations

​
Get wallet balance

GET http://localhost:32838/v1/cryptos/btc/derivations/{walletId}/balance

​
Track transactions

POST http://localhost:32838/v1/cryptos/btc/derivations/{walletId}/transactions
Full API docs available at http://localhost:32838 (Redoc UI).

​
Use Cases

  • Agent Wallets — Each agent gets its own Bitcoin wallet
  • A2A Payments — Agents pay each other in BTC
  • Merchant Receipts — Accept BTC payments via BTCPay Server
  • Micropayments — Pay-per-request agent services
  • Treasury Management — Multi-sig agent treasury operations

​
Security

  • Non-custodial — You control the keys
  • Pruned nodes — Minimal storage footprint
  • Testnet-first — Develop safely before mainnet
  • Hash verification — UTXO snapshots verified against trusted hashes
  • Isolated network — Headless stack has no public-facing UI

​
Resources