/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)
bash
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
bash
# 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
bash
# 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
bash
# 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
bash
# 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
bash
# 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
markdown
## 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