/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

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