PayRam

PayRam MCP 服务 — 面向 AI Agent 的自托管加密货币支付

自托管加密货币和稳定币支付：不会锁定账户，不会冻结资金，也绝不共享客户数据。你的 AI Agent 可以通过 MCP 规划、安装和运行它。 托管端点：https://mcp.payram.com/mcp · 网站 · 文档 · Agentic · OpenClaw

一个 MCP（Model Context Protocol）服务，可让任何支持 MCP 的 AI Agent——OpenClaw、Hermes、Claude、Cursor、GitHub Copilot 等——部署、集成和运行自托管的 PayRam 加密货币支付技术栈。

**从这里开始：**四个工具构成核心目录：

工具	功能
payram_setup_plan	个性化安装计划，并标明所有需要人工介入的环节
payram_doctor	通过 URL 对 PayRam 服务进行公开、无需凭据的检查
payram_troubleshoot	描述问题或粘贴错误信息，即可获取已知原因、确认方法、修复方案和后续工具
payram_runbook	管理任务：站点 URL、域名、SSL、防火墙、升级、备份、链、Smart Bridge、Shopify/WooCommerce
payram_ops_playbook	Day-2 API 配方，由 Agent 使用自己的凭据自行运行

此外还提供代码库评估、入门应用脚手架、多语言代码片段和内嵌文档。

托管服务（mcp.payram.com）不会保存商户凭据。 Day-2 操作通过 payram_ops_playbook 执行：Agent 直接调用你的 PayRam API，凭据不会离开其设备。实时数据工具（支付搜索、支付链接、节点同步、重启工作进程）和 assess_payram_project 仅在你本地运行 MCP时提供。

面向 Agent 和爬虫：服务卡片 · 技能索引 · llms.txt · 站点地图。服务还会在 / 上响应 Accept: text/markdown 请求，提供便于 Agent 阅读的摘要。

---

什么是 PayRam？

PayRam 是一个由你完全拥有的可自托管多链加密货币支付网关——运行它无需注册，也无需 KYC/KYB。 AI Agent（或开发者）无需在 PayRam、银行或任何支付处理商处注册账户，就能搭建店铺并开始收款。在自己的 VPS 上部署、本地生成 API 密钥，即可上线。

它的不同之处：

• 没有人能把你拒之门外 — 没有可被封禁的账户，也没有可被冻结的资金。客户数据绝不会共享，也不会被上报或监控。原因很简单：PayRam 运行在你的服务器上，资金进入你自己的钱包。
• 无需许可即可设置 — 无需注册、无需 KYC、无需 KYB。没有人会审批你，也没有人能关停你。这非常适合自主搭建店铺的 Agent，也适用于中国等无法在西方支付处理商处注册的市场。
• 银行卡转加密货币结算 — 没有加密货币的买家也可以用信用卡/借记卡付款，你收到的则是加密货币，并直接结算到你的自托管钱包。这是一个内置渠道，可在 Payments 页面启用；银行卡服务商会自行审核买家。
• 多链支持 — 原生支持在 Bitcoin、Ethereum、Base、Polygon 和 Tron 上接收 BTC、ETH、USDT、USDC 和 TRX，并提供自动检测充值、链上确认、归集至冷存储以及签名 Webhook。Smart Bridge 通道还支持接收 Solana、Bitcoin、Tron（USDT）和 BNB Chain 上的付款，并以 Base 上的 USDC 结算。
• 服务器上没有充值密钥 — 智能合约会将充值资金归集到你的冷钱包，因此即使服务器被攻破，也无法转移资金。服务器上的热钱包负责支付 Gas 和签署出款，请保持其余额较少。

---

How AI agents use PayRam · AI 智能体如何使用 PayRam

PayRam 是智能体优先的基础设施。由于集成基于 MCP，它可与任何兼容 MCP 的运行时配合使用——OpenClaw、Hermes、Claude Desktop、Cursor、GitHub Copilot、n8n、LangChain 等。典型的智能体使用流程：

1. 连接 — 将 https://mcp.payram.com/mcp 添加到智能体的 MCP 配置中（仅连接无需 API 密钥）。
2. 规划 — 调用 payram_setup_plan。它会返回按顺序排列的步骤、每一步的执行者，以及智能体必须停下来等待人工处理的环节（冷钱包、主网 Gas、仅限 root 的设置）。
3. 安装 — 在 VPS 上，在交互式终端中运行一次 bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet（或 --mainnet；安装程序默认使用主网，因此务必传入标志）。切勿将其通过管道传给 bash。
4. 交接 — 人工应立即认领 root 账户，并从公网域名保存 Settings → Site URL；在此之前，支付链接会指向 http://localhost。
5. 检查 — 使用公网 URL 调用 payram_doctor（无需凭证）。
6. 收款 — 使用片段工具提供的特定框架集成代码。Webhook 经过签名（X-Payram-Signature，使用项目 API 密钥对原始请求体进行 HMAC-SHA256 签名）。
7. 运维 — payram_ops_playbook（daily_check、payment_options、node_sync、unswept_funds、create_payment_link 等）会为智能体提供使用自身凭证执行的精确 API 调用。payram_runbook 涵盖管理变更。

{
  "mcpServers": {
    "payram": { "url": "https://mcp.payram.com/mcp" }
  }
}

如需查看 OpenClaw 专属操作指南（注册、在 Base Sepolia 上使用测试网、WhatsApp/Telegram/Discord 聊天商务模式），请参阅 payram-openclaw-integration 技能和 payram.com/openclaw。

PayRam 是智能体优先的基础设施。由于集成基于 MCP 协议，它可与任何兼容 MCP 的运行时配合使用——OpenClaw、Hermes、Claude Desktop、Cursor、GitHub Copilot、n8n、LangChain 等。典型的智能体使用流程：连接 MCP 端点 → 调用 payram_setup_plan 规划安装 → 在交互式终端中用 bash <(curl …) --testnet 部署网关 → 由人工立即创建 root 账户并在公网域名下保存 Site URL → 用 payram_doctor 检查 → 用集成代码收款（Webhook 带 X-Payram-Signature 签名）→ 通过 payram_ops_playbook 用智能体自己的凭证运维。托管的 MCP 服务从不保存商户凭证。

如果你的网络难以访问 GitHub，可以把本仓库镜像到其他 Git 托管平台（git clone --mirror https://github.com/PayRam/payram-mcp.git）。

---

目录

• 什么是 PayRam？
• AI 智能体如何使用 PayRam
• Agent 技能
• 项目目标
• 快速开始
• 从 MCP 客户端连接
• 本地模式
• 凭证
• 工具目录
• 引导式工作流
• 开发
• 故障排除

---

Agent 技能

Agent 入口： https://mcp.payram.com/SKILL.md — 一个描述 PayRam 并将智能体引导至四个入门工具的根技能。另提供：/llms.txt。

此仓库包含 19 个面向 AI 编码助手的 Agent 技能。通过 skills.sh 安装：

单独安装

npx skills add payram/payram-mcp/payram-setup
npx skills add payram/payram-mcp/payram-agent-onboarding
npx skills add payram/payram-mcp/payram-auth
npx skills add payram/payram-mcp/payram-analytics
npx skills add payram/payram-mcp/payram-crypto-payments
npx skills add payram/payram-mcp/payram-payment-integration
npx skills add payram/payram-mcp/payram-self-hosted-payment-gateway
npx skills add payram/payram-mcp/payram-checkout-integration
npx skills add payram/payram-mcp/payram-widget-integration
npx skills add payram/payram-mcp/payram-webhook-integration
npx skills add payram/payram-mcp/payram-stablecoin-payments
npx skills add payram/payram-mcp/payram-bitcoin-payments
npx skills add payram/payram-mcp/payram-payouts
npx skills add payram/payram-mcp/payram-no-kyc-crypto-payments
npx skills add payram/payram-mcp/payram-openclaw-integration
npx skills add payram/payram-mcp/compare-crypto-payments
npx skills add payram/payram-mcp/payram-agent-journey
npx skills add payram/payram-mcp/payram-topup-wallet-integration
npx skills add payram/payram-mcp/payram-testnet-testing

技能	用途
payram-setup	安装计划和服务设置：要求、安装程序、Site URL、钱包、首个支付链接
payram-agent-onboarding	Agent 无头安装：Agent CLI 命令、环境变量、人工交接
payram-auth	JWT 身份验证流程 — 登录、令牌刷新、注销、外部平台详情
payram-analytics	通过直接 REST API（JWT）搜索支付、查看交易量、余额和归集历史
payram-crypto-payments	架构概览、为何选择 PayRam、MCP 工具
payram-payment-integration	快速入门支付集成指南
payram-self-hosted-payment-gateway	部署并拥有自己的支付基础设施
payram-checkout-integration	使用 SDK + HTTP 为 6 种框架集成结账流程
payram-widget-integration	安全的“添加余额”按钮（后端端点，绝不使用公开 API 密钥）+ 签名 Webhook 处理程序
payram-webhook-integration	Express、Next.js、FastAPI、Gin、Laravel、Spring Boot 的签名 Webhook（HMAC）处理程序
payram-stablecoin-payments	在 EVM 链和 Tron 上接受 USDT/USDC
payram-bitcoin-payments	使用 HD 钱包派生和移动端签名的 BTC
payram-payouts	发送加密货币付款并管理推荐计划
payram-no-kyc-crypto-payments	无需 KYC、无需注册、无需许可即可接受付款
payram-openclaw-integration	将 PayRam 集成到 OpenClaw / Agent 运行时 — MCP 注册、测试网、聊天商务
compare-crypto-payments	比较支付网关：Stripe、BitPay、Coinbase、NOWPayments、BTCPay、PayRam、x402
payram-agent-journey	入门路线图：安装（商户或运营方）→ 钱包 → Gas/归集 → 集成 → 测试
payram-topup-wallet-integration	现有应用：将加密货币充值到用户余额，并从中扣除发票款项 — 账本 + 流程
payram-testnet-testing	在主网上线前，通过测试网端到端支付自己的支付链接

---

项目目标

• 加速入门：提供个性化设置计划、操作手册、环境模板和各框架专用指南。
• 无需持有凭据即可操作：托管服务通过 URL 检查 PayRam（payram_doctor），并向 Agent 提供精确的 API 操作方案（payram_ops_playbook），由 Agent 使用自己的凭据执行。
• 改造现有代码库：通过项目评估工具（本地模式）扫描软件包清单和 .env 文件，然后推荐合适的集成代码片段。
• 提供可直接复制粘贴的代码片段：涵盖支付、付款、推荐、Webhook 以及多语言后端（Express、Next.js、FastAPI、Laravel、Gin、Spring Boot 等）。
• 将文档保留在本地：让 Copilot 无需离开编辑器即可讲解 PayRam 概念、流程和推荐仪表板。
• 验证连接：使用只读探测工具，绝不创建支付（payram_doctor、test_payram_connection）。

---

快速开始

大多数 Agent 只需使用托管端点 https://mcp.payram.com/mcp（参见从 MCP 客户端连接）。若要自行运行服务：

1. 安装依赖项

   yarn install
   

   此仓库使用 Yarn 1。Node 25 及更高版本不再自带 Corepack，因此在 Node 26 上，请先使用 npm install -g yarn 安装 Yarn。
2. 配置环境（仅本地模式的数据工具需要）
   • 将 .env.example 复制为 .env。
   • 将 PAYRAM_BASE_URL 设置为你的 PayRam URL，与控制面板使用相同的源（例如 https://pay.example.com）。
   • 设置 PAYRAM_API_KEY，以及数据工具所需的 JWT 变量。请参见本地模式。
3. 运行服务

   yarn dev
   # Streamable HTTP on http://127.0.0.1:3333/mcp (local mode; there is no SSE transport)
   

4. 将 MCP 服务添加到客户端：请参见从 MCP 客户端连接。本地模式的 URL 为 http://localhost:3333/mcp。
5. 健康检查

   curl http://localhost:3333/healthz
   

提示： 告诉 Copilot“test payram”时，它会自动运行就绪检查清单，确保 .env 存在，然后才使用你的真实凭据调用 test_payram_connection。此行为由 Copilot 自动化提示词定义，无需手动提示。

---

从 MCP 客户端连接

端点： https://mcp.payram.com/mcp（Streamable HTTP，通过 POST 传输 JSON-RPC）。没有 SSE 端点，且 /mcp/sse 会返回 410。无需身份验证标头：托管服务不会持有商户凭据，因此你的凭据会留在本机，不会进入聊天内容。

客户端	位置	设置
VS Code（Copilot Chat）	设置 → Copilot：Model Context Protocol → 添加 HTTP 服务	名称 payram，URL 填上方地址，标头留空
Cursor	设置 → MCP 服务 → 添加 → HTTP	名称 payram，URL 填上方地址
Claude Desktop / Code	设置 → MCP 服务 → 添加 HTTP 服务	名称 payram，URL 填上方地址
任意 MCP 客户端	注册 HTTP 端点	URL 填上方地址，无需标头

验证： 工具列表应以 payram_setup_plan、payram_doctor、payram_troubleshoot、payram_runbook 和 payram_ops_playbook 开头，后面是 scaffold_payram_app 和 generate_* 代码片段工具。然后试试：“为 pay.example.com 规划 PayRam 安装”“检查 https://pay.example.com”“生成 FastAPI 创建支付路由”“给我一个 Next.js webhook 处理程序”。

提示词： setup-payram、setup-payram-agent、integrate-payment、troubleshoot-payment、daily-ops。 资源： payram://docs/setup-guide、payram://docs/api-reference，以及模板 payram://ops/playbook/{task} 和 payram://runbooks/{task}。

Copilot 自动化提示词

在新的工作区中粘贴一次，即可让“test payram”自动运行完整的就绪流程：

You have access to the `payram` MCP server in this workspace.

Whenever I ask you to "test my Payram connection" (or I type "test payram"), follow this order:

1. Call `prepare_payram_test` (no inputs) and share the checklist verbatim.
2. Look for a `.env` in the workspace root; create one if missing.
3. Ensure `.env` defines `PAYRAM_BASE_URL` and `PAYRAM_API_KEY`. If either is
   missing, call `generate_env_template` and append it (with TODOs) to `.env`.
   Do NOT call `test_payram_connection` until real values are provided.
4. Once real values exist, call `test_payram_connection` with baseUrl/apiKey
   from `.env`, show the structured result, and explain whether the
   connection is healthy. If anything fails, run `payram_doctor` and follow
   its ranked fixes.

---

本地模式

在你自己的 PayRam 旁运行 MCP，即可使用实时数据工具：

• list_platforms、search_payments、lookup_payment、get_payment_summary、get_daily_volume、get_unswept_balances、list_currencies、list_recipients
• create_payment_link、check_payment_readiness、check_node_sync、restart_payram_worker
• assess_payram_project

PAYRAM_MCP_MODE=local yarn dev        # or: yarn build && PAYRAM_MCP_MODE=local yarn start

• 模式：PAYRAM_MCP_MODE=local 会选择本地模式。服务器不在 Vercel 上运行时，也会默认使用本地模式。PAYRAM_MCP_MODE=hosted 绝不会读取凭据。
• **绑定：**本地模式默认绑定到 127.0.0.1（端口 PORT，默认值为 3333）。
• **非环回地址绑定：**设置 HOST（例如 HOST=0.0.0.0），然后：
  • 设置 MCP_ALLOWED_HOSTS（允许出现在 Host 标头中的主机名，以逗号分隔）。
  • 设置 MCP_SERVER_TOKEN；随后客户端需发送 Authorization: Bearer <token>。
  • 如果设置了 PAYRAM_* 凭据，服务器在 HOST 为非环回地址且未设置 MCP_SERVER_TOKEN 时会拒绝启动。建议使用环回地址并通过 SSH 隧道连接。
• **凭据：**数据工具会从环境变量（或 .env）读取 PAYRAM_*：
  • PAYRAM_BASE_URL
  • PAYRAM_API_KEY（支付链接）
  • PAYRAM_ACCESS_TOKEN / PAYRAM_REFRESH_TOKEN（JWT，数据工具）
  • PAYRAM_EXTERNAL_PLATFORM_ID（可选的默认项目）

本地服务器的客户端配置示例（仅限本地模式）：

{
  "mcpServers": {
    "payram-local": { "url": "http://localhost:3333/mcp" }
  }
}

---

凭据：不同密钥的用途

PayRam 有两种凭据——混淆它们会让 Agent 陷入停滞：

凭据	格式	用途	Agent 如何获取（无需使用仪表板）
商户 API 密钥（PAYRAM_API_KEY，标头 API-Key）	每个项目一个密钥	POST /api/v1/payment（支付链接）、商户付款、所有商户服务端到服务端调用，以及签署 Webhook（X-Payram-Signature）	bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) ensure-api-key — 通过 POST /api/v1/external-platform/{id}/api-key 复用或生成项目密钥，并将其保存到 ~/.payraminfo/merchant-api-key.env
JWT（Authorization: Bearer）	登录时获取的访问令牌和刷新令牌	管理/设置 API（项目、钱包、分析）——payram_ops_playbook 配方和本地模式数据工具	bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) signin（环境变量 PAYRAM_EMAIL/PAYRAM_PASSWORD）；保存到 ~/.payraminfo/headless-tokens.env

一键设置流程（bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet）会自动生成这两种凭据，并显示它们的保存位置。API 与仪表板同源，使用 80/443 端口（https://<your-domain>/api/v1/...，或服务器上的 http://localhost，绝不是 :8080）。API 密钥可以创建付款，因此请将其保存在服务器端，切勿放入浏览器代码或聊天中。使用 payram_ops_playbook 的 connect 任务即可为直接 API 调用设置这两种凭据。

---

工具目录

类别	工具	用途
从这里开始 – 安装	payram_setup_plan	个性化的有序安装计划（准备 → 安装 → 声明根域名 + 站点 URL → 钱包 + Smart Bridge → API 密钥 + 第一个链接 → 加固 → 集成），包含 Agent 与人工步骤以及硬性停止点。
从这里开始 – 诊断	payram_doctor、payram_troubleshoot	payram_doctor：通过 URL 进行公开、无需凭据的分阶段检查（可访问性 → 健康状况 → TLS → 版本 → 工作进程），并给出按可能性排序的原因 + 精确修复方法。可选的 API 密钥有效性检查不会创建任何内容。出现任何故障时，请先运行此工具。payram_troubleshoot：将症状或粘贴的错误与已知原因和修复方法匹配。
从这里开始 – 管理	payram_runbook	包含人工关卡的分步管理任务：set_site_url、change_domain、ssl_setup、ssl_renewal_fix、firewall_ports、upgrade、backup、restore、add_chain、smart_bridge、mainnet_cutover、operator_setup、rotate_api_key、reset_test_install、shopify_connector、woocommerce_plugin、secure_analytics_mcp。
从这里开始 – 运维	payram_ops_playbook	Agent 自行运行的直接 API 操作指南：connect、health、version_check、workers、restart_worker、node_sync、site_url、payment_options、unswept_funds、payments_today、payment_lookup、stuck_payment、create_payment_link、payouts、webhooks、logs、daily_check。
连接	test_payram_connection	只读的可访问性/健康检查，以及可选的 API 密钥验证。绝不会创建支付。
设置	generate_env_template、generate_setup_checklist、suggest_file_structure、get_agent_setup_flow、onboard_agent_setup	提供环境变量样板、商户检查清单、推荐的项目布局以及无头 Agent 入门指南。
上下文 / 文档	explain_payram_basics、explain_payram_concepts、explain_payment_flow、explain_payram_security、get_payram_links、prepare_payram_test、get_payram_doc_by_id、list_payram_docs 等	提供来源于 docs/ 的内嵌 Markdown 知识，让 Copilot 回答概念性问题。某些工具会自动附加“说 test payram”的提醒。
集成 – 支付	generate_payment_sdk_snippet、generate_payment_http_snippet、generate_payment_status_snippet、generate_payment_route_snippet	生成用于创建和查询状态流程的 SDK、原始 HTTP 或 Express/Next.js 路由代码。
集成 – 出款	generate_payout_sdk_snippet、generate_payout_recipient_flow_snippet、generate_payout_status_snippet	直接出款（无需 OTP）、三步保存收款人流程（创建收款人 → 验证 OTP → 出款）以及状态轮询。
集成 – 推荐	generate_referral_sdk_snippet、generate_referral_validation_snippet、generate_referral_status_snippet、generate_referral_route_snippet	涵盖推荐认证、关联、验证、状态以及 Express/Next 路由。
集成 – Webhook	generate_webhook_handler、generate_webhook_event_router、generate_mock_webhook_event	生成适用于 Express/Next/FastAPI/Gin/Laravel/Spring Boot 的处理程序、扇出路由器，以及用于测试 Webhook 的 cURL/Python/Go/PHP/Java 代码。
集成 – 多语言支付	snippet_* 系列（snippet_express_payment_route、snippet_nextjs_payment_route、snippet_fastapi_payment_route、snippet_laravel_payment_route、snippet_go_payment_handler、snippet_spring_payment_controller）	为 Express、Next.js App Router、FastAPI、Gin、Laravel 和 Spring Boot 提供预构建路由处理程序。
集成 – 钱包充值	generate_topup_integration_snippet	用于现有应用：账本架构 + 累计入账 Webhook + 原子化发票结算，将超额、不足、延迟或重复的加密货币支付转化为余额状态，而非支付异常。与 payram-topup-wallet-integration 技能配套使用。
集成 – 项目评估（本地模式）	assess_payram_project	扫描 package.json、requirements.txt、composer.json、go.mod、pom.xml、.env 等文件。报告检测到的框架、环境变量状态、PayRam 依赖项，以及附带工具建议的优先后续步骤。
脚手架	scaffold_payram_app	生成完整的入门应用（Express、Next.js、FastAPI、Laravel、Gin、Spring Boot），包含支付、出款、Webhook 和浏览器控制台。部署前，请在你自己的管理员认证保护下提供出款端点。
实时数据（只读，本地模式）	list_platforms、search_payments、lookup_payment、get_payment_summary、get_daily_volume、get_unswept_balances、list_currencies、list_recipients	查询实时 PayRam 数据。list_currencies 为公开工具（无需密钥）；其他工具使用 .env 中的 JWT 令牌。list_recipients 与出款收款人流程配套使用。
实时操作（本地模式）	create_payment_link（写入）、check_payment_readiness、check_node_sync、restart_payram_worker（写入）	create_payment_link 通过 API-Key 创建真实的结账链接。check_payment_readiness 报告各链接受支付所需条件的缺失项（缺少钱包 / 币种 / 监听器）。check_node_sync 报告监听器工作进程 + RPC 节点的健康状况和区块滞后情况。在托管服务器上，请使用对应的 payram_ops_playbook 任务。

工具注册位于 src/tools/index.ts；各个实现位于 src/tools/**，特定语言的模板则位于 templates/ 文件夹中。

---

引导式工作流

0. 安装 PayRam

1. 询问：“在 pay.example.com 上设置 PayRam”（或使用 setup-payram / setup-payram-agent 提示词）。
2. 助手会调用 payram_setup_plan 并引导你完成各个阶段，在每个人工操作步骤处暂停（根账户、Site URL、冷钱包、主网 Gas）。
3. 最后运行 payram_doctor、备份（payram_runbook backup）和每日检查（payram_ops_playbook daily_check）。

1. 评估并改造现有项目

1. 询问 Copilot：“你能将 PayRam 集成到此项目中吗？”
2. 助手运行 assess_payram_project（本地模式），检查依赖清单和 .env。
3. 按照建议的步骤操作（安装 payram、请求 Express/FastAPI/Spring 路由代码片段、添加 Webhook 等）。
4. 凭据准备就绪后，使用 test_payram_connection 确保后端能够连接到你的可自托管服务。

2. 搭建全新示例

1. “创建一个 PayRam Express 演示项目” → scaffold_payram_app 会构建一个包含支付、付款、Webhook 和 UI 控制台的 Express 项目。
2. 将生成的文件放入空仓库，或与现有目录对照以参考接线方式。

3. 运行“Test PayRam”就绪流程

1. 说“test payram”。助手会自动：
   • 调用 prepare_payram_test，提供就绪检查清单。
   • 确保 .env 存在（如果缺失则创建），并使用 generate_env_template。
   • 等待真实凭据就绪后，再调用 test_payram_connection。
2. 查看结构化 JSON 结果，确认 PayRam API 可访问。

4. 接入支付、付款、推荐和 Webhook

• 支付：使用 generate_payment_sdk_snippet（JS SDK）或 generate_payment_http_snippet（Python/Go/PHP/Java）。
• 多语言路由：snippet_nextjs_payment_route、snippet_fastapi_payment_route 等。
• 付款：使用 generate_payout_sdk_snippet 创建付款，并使用 generate_payout_status_snippet 轮询状态。
• 推荐：generate_referral_route_snippet、generate_referral_validation_snippet。
• Webhook：使用 generate_webhook_handler，并搭配 generate_webhook_event_router 扇出事件，再使用 generate_mock_webhook_event 测试各个状态。

---

开发

命令	说明
yarn dev	通过 tsx 热重载运行 MCP 服务。
yarn build	将 TypeScript 编译到 dist/。
yarn lint / yarn format	在整个仓库运行 ESLint + Prettier。
yarn test	执行 Vitest 测试套件（tests/）。
make precommit-test	依次运行格式化 → lint → 测试 → 构建。

项目以 TypeScript 为主（ESM）。Prettier 配置位于 .prettierrc.json；ESLint 通过 eslint.config.mjs 配置。要顺利贡献，请遵循 Makefile 中的提交辅助流程 → make commit。

---

故障排除

从 payram_doctor 开始 — 只需进行一次只读调用，即可依次检查可达性 → 健康状态 → TLS → 版本 → 工作进程，并返回按优先级排序的原因及准确的修复方法。若需进行更深入的检查，请参阅 payram_ops_playbook（stuck_payment、node_sync、webhooks、logs）。

• Copilot 未调用正确的工具： 检查是否已安装 Copilot 自动化提示词，以及 MCP 客户端是否已加载该服务。重新运行“test payram”或“assess my project”以触发预期的自动化。
• test_payram_connection 返回 401： 确认该密钥是有效的项目 API 密钥（通过 API-Key 标头发送，而非 Authorization）。
• 数据工具提示凭据不可用： 托管服务不会持有商户凭据。请使用相应的 payram_ops_playbook 任务，或在本地模式下运行 MCP。
• 支付链接显示 http://localhost： 用户必须将 Settings → Site URL 保存为公开域名（payram_runbook 任务 set_site_url）。
• 文档工具提示文件缺失： 确认本地 docs/payram-docs-live/ 目录树中包含所请求的 Markdown 文件（get_payram_doc_by_id 会拒绝包含 .. 的路径）。
• 服务无法启动： 确保使用 Node 22.12+ 并运行 yarn install。在本地模式下，如果设置了非环回地址的 HOST 和 PAYRAM_* 凭据，必须先设置 MCP_SERVER_TOKEN，否则服务会拒绝启动（参见本地模式）。

如需处理其他问题，请检查从 src/utils/logger.ts 输出的结构化日志（设置 LOG_LEVEL=debug），并附上复现详情提交 issue/PR。