/check-btcpay

/​check-btcpay

Audit BTCPay Server configuration. Output findings as structured report.

What This Does

1. Check Greenfield API connectivity
2. Audit store configuration
3. Review webhook endpoints + signature verification
4. Check payment notification settings
5. Verify Lightning node connection
6. Verify wallet hot/​cold separation
7. 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

Related

• /​check-lightning - Lightning setup review
• /​check-bitcoin - On-chain wallet review
• /​check-production - Infra readiness
• /​log-production-issues - Create issues from findings