Getting Started

Prerequisites

GhostBill runs as a set of Docker containers. You need a Linux server (VPS or bare metal) with at least 2 GB RAM, 20 GB disk, and Docker Engine 24+ with Docker Compose v2 installed.

You also need a running Monero node (monerod) with RPC access. GhostBill connects to your node via monero-wallet-rpc to generate subaddresses and monitor payments. A pruned node works fine and requires approximately 50 GB of disk space.

For Tor hidden service access (recommended), install Tor on your host. GhostBill includes a pre-configured Tor setup guide.

Installation

Clone the repository and navigate to the project directory:

git clone https://github.com/nicknull/ghostbill.git
cd ghostbill

The repository contains the complete Docker Compose stack with 5 services: PostgreSQL, Redis, monero-wallet-rpc, the GhostBill API backend, and the merchant dashboard.

Configuration

Copy the example environment file and configure your settings:

cp .env.example .env
nano .env

The critical settings are:

• MONERO_WALLET_RPC_HOST — your monero-wallet-rpc endpoint (default: walletrpc container)
• POSTGRES_PASSWORD — strong password for the database
• SECRET_KEY — random 64-char hex string for JWT signing
• WEBHOOK_HMAC_SECRET — random 64-char hex string for webhook signatures

Generate secure secrets on the server:

openssl rand -hex 32  # SECRET_KEY
openssl rand -hex 32  # WEBHOOK_HMAC_SECRET

First Launch

Start all services with Docker Compose:

docker compose up -d

# Verify all 5 containers are healthy
docker compose ps

# Expected output:
# ghostbill_postgres    ... Up (healthy)
# ghostbill_redis       ... Up (healthy)
# ghostbill_walletrpc   ... Up (healthy)
# ghostbill_backend     ... Up (healthy)
# ghostbill_frontend    ... Up (healthy)

The backend runs on port 8013 and the dashboard on port 3013. Both listen on 127.0.0.1 only — not exposed to the internet directly.

Verify the health endpoint:

curl http://127.0.0.1:8013/health
# {"status": "healthy", "app": "GhostBill", "blocks_behind": 0}

Generate API Key

GhostBill uses API keys for authentication. Keys are prefixed with gb_live_ for production and gb_test_ for testing. Generate your first key through the dashboard or the admin API:

curl -X POST http://127.0.0.1:8013/v1/api-keys \
  -H "Content-Type: application/json" \
  -d '{"label": "My Store", "scopes": ["invoices", "payments", "customers"]}'

# Response:
# {
#   "id": "ak_...",
#   "key": "gb_live_a1b2c3d4e5f6...",
#   "label": "My Store",
#   "scopes": ["invoices", "payments", "customers"]
# }

Save the key value securely — it is shown only once. All subsequent API calls require the Authorization: Bearer gb_live_... header.

Create Your First Invoice

Create an invoice by specifying the amount in piconero (1 XMR = 10¹² piconero) or as a decimal XMR string:

curl -X POST http://127.0.0.1:8013/v1/invoices \
  -H "Authorization: Bearer gb_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount_xmr": "0.5",
    "description": "VPN subscription - 1 month",
    "expiry_minutes": 60,
    "metadata": {"order_id": "ORD-001", "customer_email": "anon"}
  }'

# Response (201 Created):
# {
#   "id": "inv_...",
#   "address": "86jXqk...",
#   "amount_atomic": 500000000000,
#   "status": "pending",
#   "expires_at": "2026-04-28T08:00:00Z",
#   "created_at": "2026-04-28T07:00:00Z"
# }

Each invoice generates a unique Monero subaddress. Funds sent to this address go directly to your wallet — GhostBill never holds private keys or touches your funds.

Verify Payment

GhostBill monitors the mempool and blockchain automatically. When a payment is detected, a payment.detected webhook fires. After the configured number of confirmations,payment.confirmed and invoice.paid events follow.

You can also poll the invoice status:

curl http://127.0.0.1:8013/v1/invoices/inv_... \
  -H "Authorization: Bearer gb_live_a1b2c3d4e5f6..."

# Response:
# {
#   "id": "inv_...",
#   "status": "paid",
#   "amount_atomic": 500000000000,
#   "amount_received_atomic": 500000000000,
#   "payments": [{
#     "tx_hash": "a1b2c3...",
#     "amount_atomic": 500000000000,
#     "status": "confirmed",
#     "confirmations": 10
#   }]
# }

GhostBill handles 7 invoice states: pending, paid, expired,partially_paid, overpaid, late_paid, and cancelled. Each transition is deterministic and fires the corresponding webhook event.

Tor Access

GhostBill is designed to run as a Tor hidden service. After configuring Tor on your host, both the API and dashboard are accessible via .onion addresses:

API:       http://your-ghostbill.onion/v1/
Dashboard: http://your-ghostbill.onion/

# No IP metadata leak. No DNS queries.
# All webhook deliveries routed through Tor.

Clearnet access is optional and configured by the merchant on their own infrastructure. GhostBill itself never exposes services to the public internet.

Next Steps

• API Reference — complete endpoint documentation
• Recurring Billing — set up subscription payments
• GhostBill vs BTCPay Server — detailed comparison
• VPN Provider Guide — accept Monero for VPN services
• Pricing — Open Core tiers and dashboard licenses