Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agentbot.raveculture.xyz/llms.txt

Use this file to discover all available pages before exploring further.

​
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 (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=mainnet      # mainnet (default) or testnet
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

Agentbot wraps NBXplorer with authenticated endpoints for registering watch-only wallets, generating addresses, querying balances, and viewing transactions. See the Bitcoin wallets API reference for the full endpoint specification. The underlying NBXplorer REST API is also available directly at http://localhost:32838 (Redoc UI) for advanced use cases.

​
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
  • Mainnet by default — Production environment runs on Bitcoin mainnet; switch to testnet for development
  • Hash verification — UTXO snapshots verified against trusted hashes
  • Isolated network — Headless stack has no public-facing UI

​
Beyond Bitcoin mainnet: Liquid network

The headless BTCPay stack covers Bitcoin mainnet. If you also want to operate on the Liquid network (Blockstream’s Bitcoin sidechain), you have two options:
  • Liquid Wallet Kit (LWK) — a lightweight toolkit that connects to Blockstream’s Electrum server without running a full Liquid node. Supports multi-sig wallets, Blockstream Jade hardware signing, and asset issuance. See the LWK GitHub repository for setup details.
  • Full Liquid node — run your own validating Elements Core node. Follow Blockstream’s official Liquid node setup guide for chain sync, data directory configuration, and optional Bitcoin-node-backed peg-in validation.
Liquid support is a planned integration track. The current agent wallet API endpoints serve Bitcoin mainnet only. Choose LWK for a fast, low-infrastructure start or a full Liquid node for independent validation.

​
Resources