Agent skill

check-btcpay

Audit BTCPay Server configuration. Checks store settings, webhook health, payment notifications, and API connectivity. Use when: running BTCPay as payment processor, diagnosing webhook issues, or verifying setup. Keywords: btcpay, btcpayserver, greenfield, payment processor.

Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/check-btcpay

SKILL.md

/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)

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

Expand your agent's capabilities with these related and highly-rated skills.

Didn't find tool you were looking for?

Be as detailed as possible for better results