/check-btcpay

Audit BTCPay Server configuration. Output findings as structured report.

What This Does

• Check Greenfield API connectivity

• Audit store configuration

• Review webhook endpoints + signature verification

• Check payment notification settings

• Verify Lightning node connection

• Verify wallet hot/cold separation

• Output prioritized findings (P0-P3)

This is a primitive. It only investigates and reports. Use /log-production-issues to create issues or /check-production for infra review.

Process

1. API Connectivity (Greenfield API health)

export BTCPAY_URL="https://btcpay.example.com" export BTCPAY_API_KEY="your-api-key"

Greenfield health

curl -s -H "Authorization: token $BTCPAY_API_KEY" "$BTCPAY_URL/api/v1/health"

List stores (requires valid API key)

curl -s -H "Authorization: token $BTCPAY_API_KEY" "$BTCPAY_URL/api/v1/stores" | jq

2. Store Configuration

Set STORE_ID from the stores list above

export STORE_ID="store_id_here"

Store details

curl -s -H "Authorization: token $BTCPAY_API_KEY" "$BTCPAY_URL/api/v1/stores/$STORE_ID" | jq

Enabled payment methods

curl -s -H "Authorization: token $BTCPAY_API_KEY" "$BTCPAY_URL/api/v1/stores/$STORE_ID/payment-methods" | jq

3. Webhook Endpoints + Signature Verification

List configured webhooks

curl -s -H "Authorization: token $BTCPAY_API_KEY" "$BTCPAY_URL/api/v1/stores/$STORE_ID/webhooks" | jq

Webhook handlers in code

find . -path "/api/webhook" -name ".ts" 2>/dev/null | head -5

Signature verification in handlers?

grep -rE "btcpay|webhook.signature|hmac" --include=".ts" . 2>/dev/null | grep -v node_modules | head -5

4. Payment Notification Settings

In-app notification handlers (invoice paid/confirmed)

grep -rE "invoice.(paid|confirmed|expired)|payment.(received|settled)" --include="*.ts" . 2>/dev/null | grep -v node_modules | head -5

Check for notification URL/config in app env

grep -rE "BTCPAY_.(NOTIFY|NOTIFICATION|WEBHOOK)" --include=".env*" . 2>/dev/null | head -5

5. Lightning Node Connection

Confirm Lightning payment method enabled at store

curl -s -H "Authorization: token $BTCPAY_API_KEY" "$BTCPAY_URL/api/v1/stores/$STORE_ID/payment-methods" | jq

Lightning node health checks in repo

grep -rE "lnd|lightning|lnurl|bolt11" --include="*.ts" . 2>/dev/null | grep -v node_modules | head -5

6. Wallet Hot/Cold Separation

Look for hot wallet usage or private keys in repo

grep -rE "xprv|seed|mnemonic|private key" --include=".ts" --include=".env*" . 2>/dev/null | grep -v node_modules | head -5

Watch-only setup hints (xpub descriptors)

grep -rE "xpub|ypub|zpub|descriptor" --include=".ts" --include=".env*" . 2>/dev/null | grep -v node_modules | head -5

7. Deep Audit

Spawn btcpay-auditor agent for comprehensive review:

• Invoice lifecycle handling (new, paid, confirmed, expired)

• Webhook signature verification and replay protection

• Store policies vs code expectations

• Lightning vs on-chain fallback behavior

• Wallet key custody and backup posture

Output Format

BTCPay Audit

P0: Critical (Payment Failures)

• Greenfield API unreachable - GET /api/v1/health fails
• Webhooks not receiving events (no active endpoints)
• Store has no enabled payment methods

P1: Essential (Must Fix)

• Webhook signature not verified - security risk
• Invoice status handling missing (paid/confirmed/expired)
• Lightning payment method enabled but node not connected
• Notification URL missing or misconfigured

P2: Important (Should Fix)

• No retry/backoff on webhook delivery failures
• Payment method config inconsistent between store and app
• Hot wallet usage detected without separation plan
• No monitoring of invoice settlement latency

P3: Nice to Have

• Add separate store for test vs production
• Add automated webhook replay tooling
• Add dashboard for invoice outcomes

Current Status

• Greenfield API: Unknown
• Stores: Unknown
• Webhooks: Unknown
• Notifications: Unknown
• Lightning: Unknown
• Wallet separation: Unknown

Summary

• P0: 3 | P1: 4 | P2: 4 | P3: 3
• Recommendation: Fix API connectivity + webhook verification first

Priority Mapping

Gap Priority

Greenfield API unreachable P0

No enabled payment methods P0

Webhooks not receiving events P0

Webhook signature not verified P1

Missing invoice status handling P1

Lightning node not connected P1

Notification URL missing P1

Missing retry/backoff P2

Config mismatch store vs app P2

Hot wallet without separation P2

Monitoring gaps P2

Optimization/analytics P3

Related

• /check-lightning

• Lightning setup review

• /check-bitcoin

• On-chain wallet review

• /check-production

• Infra readiness

• /log-production-issues

• Create issues from findings