Back to Details

check-btcpay

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

/check-btcpay

/check-btcpay

Audit BTCPay Server configuration. Output findings as structured report.
审计BTCPay Server配置，将检查结果输出为结构化报告。

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.
  1. 检查Greenfield API连通性
  2. 审计商店配置
  3. 检查webhook端点及签名验证
  4. 检查支付通知设置
  5. 验证Lightning节点连接状态
  6. 验证钱包冷热分离配置
  7. 输出按优先级划分的检查结果（P0-P3）
这是一个基础检查工具，仅用于调查和报告问题。如需创建问题工单请使用
/log-production-issues
，如需基础设施审查请使用
/check-production
。

Process

检查流程

1. API Connectivity (Greenfield API health)

1. API连通性（Greenfield API健康状态）

bash
export BTCPAY_URL="https://btcpay.example.com"
export BTCPAY_API_KEY="your-api-key"
bash
export BTCPAY_URL="https://btcpay.example.com"
export BTCPAY_API_KEY="your-api-key"

Greenfield health

Greenfield健康检查

curl -s -H "Authorization: token $BTCPAY_API_KEY" "$BTCPAY_URL/api/v1/health"
curl -s -H "Authorization: token $BTCPAY_API_KEY" "$BTCPAY_URL/api/v1/health"

List stores (requires valid API key)

列出商店（需要有效的API密钥）

curl -s -H "Authorization: token $BTCPAY_API_KEY" "$BTCPAY_URL/api/v1/stores" | jq
undefined
curl -s -H "Authorization: token $BTCPAY_API_KEY" "$BTCPAY_URL/api/v1/stores" | jq
undefined

2. Store Configuration

2. 商店配置检查

bash
undefined
bash
undefined

Set STORE_ID from the stores list above

从上述商店列表中设置STORE_ID

export STORE_ID="store_id_here"
export STORE_ID="store_id_here"

Store details

商店详情

curl -s -H "Authorization: token $BTCPAY_API_KEY" "$BTCPAY_URL/api/v1/stores/$STORE_ID" | jq
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
undefined
curl -s -H "Authorization: token $BTCPAY_API_KEY" "$BTCPAY_URL/api/v1/stores/$STORE_ID/payment-methods" | jq
undefined

3. Webhook Endpoints + Signature Verification

3. Webhook端点及签名验证检查

bash
undefined
bash
undefined

List configured webhooks

列出已配置的webhook

curl -s -H "Authorization: token $BTCPAY_API_KEY" "$BTCPAY_URL/api/v1/stores/$STORE_ID/webhooks" | jq
curl -s -H "Authorization: token $BTCPAY_API_KEY" "$BTCPAY_URL/api/v1/stores/$STORE_ID/webhooks" | jq

Webhook handlers in code

代码中的webhook处理器

find . -path "/api/webhook" -name ".ts" 2>/dev/null | head -5
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
undefined
grep -rE "btcpay|webhook.signature|hmac" --include=".ts" . 2>/dev/null | grep -v node_modules | head -5
undefined

4. Payment Notification Settings

4. 支付通知设置检查

bash
undefined
bash
undefined

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

检查应用环境变量中的通知URL/配置

grep -rE "BTCPAY_.(NOTIFY|NOTIFICATION|WEBHOOK)" --include=".env*" . 2>/dev/null | head -5
undefined
grep -rE "BTCPAY_.(NOTIFY|NOTIFICATION|WEBHOOK)" --include=".env*" . 2>/dev/null | head -5
undefined

5. Lightning Node Connection

5. Lightning节点连接检查

bash
undefined
bash
undefined

Confirm Lightning payment method enabled at store

确认商店是否启用Lightning支付方式

curl -s -H "Authorization: token $BTCPAY_API_KEY" "$BTCPAY_URL/api/v1/stores/$STORE_ID/payment-methods" | jq
curl -s -H "Authorization: token $BTCPAY_API_KEY" "$BTCPAY_URL/api/v1/stores/$STORE_ID/payment-methods" | jq

Lightning node health checks in repo

仓库中的Lightning节点健康检查代码

grep -rE "lnd|lightning|lnurl|bolt11" --include="*.ts" . 2>/dev/null | grep -v node_modules | head -5
undefined
grep -rE "lnd|lightning|lnurl|bolt11" --include="*.ts" . 2>/dev/null | grep -v node_modules | head -5
undefined

6. Wallet Hot/Cold Separation

6. 钱包冷热分离检查

bash
undefined
bash
undefined

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

观察仅设置的提示（xpub描述符）

grep -rE "xpub|ypub|zpub|descriptor" --include=".ts" --include=".env*" . 2>/dev/null | grep -v node_modules | head -5
undefined
grep -rE "xpub|ypub|zpub|descriptor" --include=".ts" --include=".env*" . 2>/dev/null | grep -v node_modules | head -5
undefined

7. Deep Audit

7. 深度审计

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
启动
btcpay-auditor
agent进行全面审查：
  • 发票生命周期处理（新建、已支付、已确认、已过期）
  • Webhook签名验证与重放保护
  • 商店策略与代码预期的一致性
  • Lightning与链下 fallback 行为
  • 钱包密钥托管与备份策略

Output Format

输出格式

markdown
undefined
markdown
undefined

BTCPay Audit

BTCPay审计报告

P0: Critical (Payment Failures)

P0：严重级别（支付失败风险）

  • Greenfield API unreachable - 
    GET /api/v1/health
    fails
  • Webhooks not receiving events (no active endpoints)
  • Store has no enabled payment methods
  • Greenfield API无法访问 - 
    GET /api/v1/health
    请求失败
  • Webhook未接收事件（无活跃端点）
  • 商店未启用任何支付方式

P1: Essential (Must Fix)

P1：关键级别（必须修复）

  • 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
  • Webhook签名未验证 - 存在安全风险
  • 缺失发票状态处理逻辑（已支付/已确认/已过期）
  • Lightning支付方式已启用但节点未连接
  • 通知URL缺失或配置错误

P2: Important (Should Fix)

P2：重要级别（建议修复）

  • 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
  • Webhook交付失败时无重试/退避机制
  • 商店与应用的支付方式配置不一致
  • 检测到热钱包使用但无分离方案
  • 未监控发票结算延迟

P3: Nice to Have

P3：优化级别（可选改进）

  • Add separate store for test vs production
  • Add automated webhook replay tooling
  • Add dashboard for invoice outcomes
  • 为测试环境与生产环境分别创建独立商店
  • 添加自动化Webhook重放工具
  • 添加发票结果监控仪表盘

Current Status

当前状态

  • Greenfield API: Unknown
  • Stores: Unknown
  • Webhooks: Unknown
  • Notifications: Unknown
  • Lightning: Unknown
  • Wallet separation: Unknown
  • Greenfield API：未知
  • 商店：未知
  • Webhook：未知
  • 通知：未知
  • Lightning：未知
  • 钱包分离：未知

Summary

总结

  • P0: 3 | P1: 4 | P2: 4 | P3: 3
  • Recommendation: Fix API connectivity + webhook verification first
undefined
  • P0：3项 | P1：4项 | P2：4项 | P3：3项
  • 建议：优先修复API连通性与Webhook验证问题
undefined

Priority Mapping

优先级映射表

GapPriority
Greenfield API unreachableP0
No enabled payment methodsP0
Webhooks not receiving eventsP0
Webhook signature not verifiedP1
Missing invoice status handlingP1
Lightning node not connectedP1
Notification URL missingP1
Missing retry/backoffP2
Config mismatch store vs appP2
Hot wallet without separationP2
Monitoring gapsP2
Optimization/analyticsP3
问题优先级
Greenfield API无法访问P0
未启用任何支付方式P0
Webhook未接收事件P0
Webhook签名未验证P1
缺失发票状态处理逻辑P1
Lightning节点未连接P1
通知URL缺失P1
无重试/退避机制P2
商店与应用配置不匹配P2
热钱包未分离P2
监控缺失P2
优化/分析需求P3

Related

相关工具

  • /check-lightning
    - Lightning setup review
  • /check-bitcoin
    - On-chain wallet review
  • /check-production
    - Infra readiness
  • /log-production-issues
    - Create issues from findings
  • /check-lightning
    - Lightning配置审查
  • /check-bitcoin
    - 链上钱包审查
  • /check-production
    - 基础设施就绪性检查
  • /log-production-issues
    - 根据检查结果创建问题工单