PayRam Crypto Card Payment Gateway
官方為代理、openclaw、hermes等提供的自託管支付網關
你可以用 PayRam Crypto Card Payment Gateway MCP 做什麼？
- 規劃個人化安裝 — 透過
payram_setup_plan請求逐步的 PayRam 部署計畫，並包含人工交接。 - 診斷伺服器健康狀態 — 使用
payram_doctor對任何 PayRam URL 執行免憑證檢查，以找出問題與修正方式。 - 疑難排解錯誤 — 貼上錯誤或症狀，即可透過
payram_troubleshoot取得已知原因、確認方式與後續步驟。 - 取得管理員操作手冊 — 透過
payram_runbook請求逐步的管理員任務，例如 SSL、備份或網域變更。 - 執行 Day-2 維運 — 讓代理程式使用
payram_ops_playbook執行日常檢查、節點同步或付款連結的 API 配方。 - 產生整合程式碼 — 請求可直接複製貼上的付款、付款或 Webhook 程式碼片段，適用於 Express 或 Next.js 等框架。
文件
PayRam MCP Server — 自托管加密支付，專為 AI 智能體設計
自託管的加密貨幣與穩定幣支付：無帳戶鎖定、無資金凍結、客戶資料絕不外洩。您的 AI 智能體可透過 MCP 自行規劃、安裝並操作它。 託管端點：
https://mcp.payram.com/mcp· 網站 · 文件 · Agentic · OpenClaw
一個 MCP（Model Context Protocol）伺服器，讓任何支援 MCP 的 AI 智能體 — OpenClaw、Hermes、Claude、Cursor、GitHub Copilot 等 — 都能部署、整合並操作自託管的 PayRam 加密支付堆疊。
從這裡開始： 四個工具引領整個目錄：
| 工具 | 功能 |
|---|---|
payram_setup_plan | 個人化的安裝計畫，標記每個需要人工介入的步驟 |
payram_doctor | 透過 URL 對 PayRam 伺服器進行公開、無需憑證的檢查 |
payram_troubleshoot | 描述問題或貼上錯誤訊息：已知原因、如何確認、修復方式，以及下一步該用的工具 |
payram_runbook | 管理任務：Site URL、網域、SSL、防火牆、升級、備份、鏈、Smart Bridge、Shopify/WooCommerce |
payram_ops_playbook | Day-2 API 配方，智能體使用自己的憑證自行執行 |
圍繞這些工具的是程式碼庫評估、入門應用程式脚手架、多語言程式碼片段和內聯文件。
託管伺服器（mcp.payram.com）絕不保存商家憑證。 Day-2 操作透過 payram_ops_playbook 執行：智能體直接呼叫您的 PayRam API，憑證絕不離開其機器。即時資料工具（支付搜尋、支付連結、節點同步、工作者重啟）和 assess_payram_project 僅在您以本機模式自行執行 MCP 時才存在。
給智能體與爬蟲： server card · skills index · llms.txt · sitemap。伺服器也會在 / 上回應 Accept: text/markdown，提供智能體可讀的摘要。
什麼是 PayRam？ · PayRam 是什么？
PayRam 是一個您完全自託管、多鏈的加密支付閘道，您擁有完全所有權 — 運行它無需註冊、無需 KYC/KYB。 AI 智能體（或開發者）無需在 PayRam、銀行或任何支付處理商處註冊帳戶，即可搭建商店並開始收款。部署在您自己的 VPS 上，在本機產生 API 金鑰，即刻上線。
與眾不同之處：
- 沒有人能將您鎖在門外 — 沒有可被封鎖的帳戶，也沒有可被凍結的資金。客戶資料絕不共用，也沒有任何回報或監控。原因很簡單：PayRam 運行在您自己的伺服器上，資金直接進入您自己的錢包。
- 免許可設定 — 無需註冊、無需 KYC、無需 KYB。沒有人審批您，也沒有人能關停您。非常適合自主搭建商店的智能體，以及像中國這樣無法在西方支付處理商處註冊的市場。
- 卡片轉加密結帳 — 沒有加密貨幣的購物者也能用信用卡/金融卡付款，您直接收到加密貨幣，並結算到您自託管的錢包。這是內建的支付管道，在 Payments 頁面開啟；卡片服務商會對購物者進行其自身的審核。
- 多鏈支援 — 原生支援在 Bitcoin、Ethereum、Base、Polygon 和 Tron 上接受 BTC、ETH、USDT、USDC 和 TRX，具備自動存款偵測、鏈上確認、歸集至冷錢包，以及簽章 Webhook。Smart Bridge 通道還可接收 Solana、Bitcoin、Tron（USDT）和 BNB Chain 上的付款，並以 Base 上的 USDC 結算。
- 伺服器上沒有存款金鑰 — 智慧合約將存款歸集到您的冷錢包，因此即使伺服器被入侵也無法重新導向資金。伺服器的熱錢包負責支付 Gas 並簽署付款，請保持其餘額較低。
PayRam 是一个你完全自托管、自主拥有的多链加密货币支付网关——运行它无需注册、无需 KYC/KYB。 AI 智能体（或开发者）无需在 PayRam、银行或任何支付处理商处注册账户，即可搭建店铺并开始收款。在自己的 VPS 上部署，本地生成 API 密钥，即刻上线。
核心差异：
- 没有人能把你锁在门外 — 没有可被封禁的账户，也没有可被冻结的资金；客户数据从不外泄，也没有任何上报或监控。原因很简单：PayRam 运行在你自己的服务器上，资金直接进入你自己的钱包。
- 免注册、免许可 — 无需注册、无需 KYC、无需 KYB。没有人审批你，也没有人能关停你。非常适合自主搭建店铺的智能体，以及像中国这样难以在西方支付处理商处注册的市场。
- 银行卡转加密货币结算 — 没有加密货币的买家也能用信用卡/借记卡付款，你直接收到加密货币并结算到自托管的钱包。这是内置的支付渠道，在「Payments（支付）」页面开启；银行卡服务商会对买家进行其自身的审核。
- 多链支持 — 原生支持在 Bitcoin、Ethereum、Base、Polygon、Tron 上接受 BTC、ETH、USDT、USDC、TRX，自动检测充值、链上确认、归集冷钱包并发送带签名的 Webhook。Smart Bridge 通道还可接收 Solana、Bitcoin、Tron（USDT）和 BNB Chain 上的付款，并以 Base 上的 USDC 结算。
- 服务器上没有充值私钥 — 智能合约把充值资金归集到你的冷钱包，即便服务器被攻破也无法改变资金去向。服务器上的热钱包负责支付 Gas 并签署出款，请只保留少量余额。
AI 智能體如何使用 PayRam · AI 智能体如何使用 PayRam
PayRam 是智能體優先（agent-first）的基礎設施。由於整合基於 MCP 協議，它可與任何相容 MCP 的執行環境配合使用 — OpenClaw、Hermes、Claude Desktop、Cursor、GitHub Copilot、n8n、LangChain 等。典型的智能體流程：
- 連接 — 將
https://mcp.payram.com/mcp加入智能體的 MCP 設定（僅連接不需要 API 金鑰）。 - 規劃 — 呼叫
payram_setup_plan。它會回傳有序的步驟、每個步驟由誰執行，以及智能體必須停下來等待人工介入的地方（冷錢包、主網 Gas、僅限 root 的設定）。 - 安裝 — 在 VPS 上，於互動式終端機中執行一次
bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet（或--mainnet；安裝程式預設為主網，因此務必傳入旗標）。切勿將其管道傳入bash。 - 交接 — 人工立即認領 root 帳戶，並從公開網域保存 Settings → Site URL；在此之前，支付連結指向
http://localhost。 - 檢查 — 使用公開 URL 呼叫
payram_doctor（無需憑證）。 - 收款 — 從程式碼片段工具放入框架特定的整合程式碼。Webhook 帶有簽章（
X-Payram-Signature，使用專案 API 金鑰對原始內文進行 HMAC-SHA256）。 - 操作 —
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 是智能体优先（agent-first）的基础设施。由于集成基于 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）。 如果你的网络难以访问 GitHub，可以把本仓库镜像到其他 Git 托管平台（git clone --mirror https://github.com/PayRam/payram-mcp.git）。
目錄
Agent Skills
智能體入口： https://mcp.payram.com/SKILL.md — 一個描述 PayRam 並將智能體引導至四個入門工具的根技能。同時提供：/llms.txt。
此儲存庫包含 19 個供 AI 編碼助手使用的 Agent Skills。透過 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 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 / 智能體執行環境 — 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），並將精確的 API 配方（payram_ops_playbook）交給智能體，讓其使用自己的憑證執行。 - 改造現有儲存庫，透過專案評估工具（本機模式），掃描套件清單和
.env檔案，然後推薦正確的整合程式碼片段。 - 提供複製貼上程式碼片段，涵蓋 Payments、Payouts、Referrals、Webhooks 和多語言後端（Express、Next.js、FastAPI、Laravel、Gin、Spring Boot 等）。
- 保持文件在本機，讓 Copilot 無需離開編輯器即可解釋 PayRam 概念、流程和推薦儀表板。
- 驗證連線，使用絕不建立付款的唯讀探測（
payram_doctor、test_payram_connection）。
快速開始
大多數智能體只需要託管端點 https://mcp.payram.com/mcp（請參閱從您的 MCP 用戶端連接）。若要自行執行伺服器：
- 安裝相依套件
yarn install - 設定環境（僅本機模式資料工具需要）
- 複製
.env.example到.env。 - 將
PAYRAM_BASE_URL設定為您的 PayRam URL，與儀表板相同來源（例如https://pay.example.com）。 - 設定
PAYRAM_API_KEY，以及資料工具所需的 JWT 變數。請參閱 本機模式。
- 複製
- 啟動伺服器
yarn dev # Streamable HTTP on http://127.0.0.1:3333/mcp (local mode; there is no SSE transport) - 將 MCP 伺服器新增至您的用戶端：請參閱 從您的 MCP 用戶端連線。本機模式 URL 為
http://localhost:3333/mcp。 - 健康檢查
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_* 程式碼片段工具。然後嘗試：「plan a PayRam install on pay.example.com」、「check https://pay.example.com」、「generate a FastAPI create-payment route」、「give me a Next.js webhook handler」。
提示： 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_recipientscreate_payment_link、check_payment_readiness、check_node_sync、restart_payram_workerassess_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_*憑證，伺服器在沒有MCP_SERVER_TOKEN的情況下拒絕在非迴路HOST上啟動。建議使用迴路加上 SSH 隧道。
- 設定
- 憑證： 資料工具從環境（或
.env）讀取PAYRAM_*：PAYRAM_BASE_URLPAYRAM_API_KEY（付款連結）PAYRAM_ACCESS_TOKEN/PAYRAM_REFRESH_TOKEN（JWT，資料工具）PAYRAM_EXTERNAL_PLATFORM_ID（可選的預設專案）
本機伺服器的範例用戶端設定（僅本機模式）：
{
"mcpServers": {
"payram-local": { "url": "http://localhost:3333/mcp" }
}
}
憑證：哪個金鑰用於什麼
PayRam 有兩組憑證——當代理混淆它們時就會停滯：
| 憑證 | 外觀 | 用途 | 代理如何取得（無需儀表板） |
|---|---|---|---|
商家 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 | 個人化的有序安裝計畫（準備 → 安裝 → 認領 root + Site URL → 錢包 + Smart Bridge → API 金鑰 + 第一個連結 → 強化 → 整合），包含代理程式與人工步驟及強制停止點。 |
| 從這裡開始 – 診斷 | payram_doctor, payram_troubleshoot | payram_doctor：公開、無需憑證的分階段檢查，依 URL 進行（可達性 → 健康狀態 → TLS → 版本 → workers），附排名可能原因與精確修正。可選的 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 | 代理程式自行執行的直接 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 | 提供環境變數樣板、商家檢查清單、建議的專案結構，以及無頭代理程式入門指南。 |
| 情境 / 文件 | 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 路由。 |
| 整合 – Webhooks | generate_webhook_handler, generate_webhook_event_router, generate_mock_webhook_event | 產生 Express/Next/FastAPI/Gin/Laravel/Spring Boot 的處理器、扇出路由器，以及 cURL/Python/Go/PHP/Java webhook 測試器。 |
| 整合 – 多語言付款 | 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），包含付款、付款支出、webhooks 和瀏覽器控制台。部署前請將付款支出端點放在您自己的管理員驗證之後。 |
| 即時資料（唯讀，本機模式） | 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 回報監聽器-worker 與 RPC 節點健康狀態及區塊過時情況。在託管伺服器上，請使用對應的 payram_ops_playbook 任務。 |
工具註冊位於
src/tools/index.ts；個別實作位於src/tools/**，語言特定範本位於templates/資料夾下。
引導式工作流程
0. 安裝 PayRam
- 詢問：「在 pay.example.com 上設定 PayRam」（或使用
setup-payram/setup-payram-agent提示）。 - 助理呼叫
payram_setup_plan並逐步執行各階段，在每個人工步驟（root 帳戶、Site URL、冷錢包、主網 gas）處停止。 - 最後以
payram_doctor、備份（payram_runbookbackup）和每日檢查（payram_ops_playbookdaily_check）結束。
1. 評估並改造現有專案
- 詢問 Copilot：「你能將 PayRam 整合到這個專案中嗎？」
- 助手會執行
assess_payram_project（本機模式），檢查相依性清單與.env。 - 依照建議步驟操作（安裝
payram、索取 Express/FastAPI/Spring 路由片段、新增 webhook 等）。 - 當憑證為真實資料時，使用
test_payram_connection以確保後端能連線到你的自架伺服器。
2. 建立全新的範例專案
- 「建立一個 PayRam Express 示範專案」→
scaffold_payram_app會建立一個包含付款、付款、webhook 與 UI 控制台的 Express 專案。 - 將產生的檔案放入空的儲存庫，或與你現有的目錄比對，作為參考接線。
3. 執行「測試 PayRam」就緒流程
- 說「test payram」。助手會自動：
- 呼叫
prepare_payram_test分享就緒檢查清單。 - 使用
generate_env_template確保.env存在（若缺少則建立）。 - 在呼叫
test_payram_connection前，等待真實憑證。
- 呼叫
- 檢視結構化的 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 | 依序執行 format → lint → test → build。 |
專案以 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 20+ 並執行
yarn install。在本機模式中，若使用非迴環的HOST與PAYRAM_*憑證，伺服器會拒絕啟動，直到設定MCP_SERVER_TOKEN（請參閱本機模式）。
若遇到其他問題，請檢查從 src/utils/logger.ts 輸出的結構化日誌（設定 LOG_LEVEL=debug），並附上重現細節開啟 issue/PR。