Agent-Skills.md

Agent Skills: /check-btcpay

|

UncategorizedID: phrazzld/claude-config/check-btcpay

Repository

phrazzld/claude-config
phrazzld
31

Install this agent skill to your local

pnpm dlx add-skill https://github.com/phrazzld/claude-config/tree/HEAD/skills/check-btcpay

Skill Files

Browse the full folder contents for check-btcpay.

Download Skill

Loading file tree…

skills/check-btcpay/SKILL.md

Skill Metadata

Name
check-btcpay
Description
|

/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