PayRam Crypto Card Payment Gateway
公式エージェント、openclaw、hermesなどのためのセルフホスト型ペイメントゲートウェイ
PayRam Crypto Card Payment Gateway MCPで何ができますか？
- 個別インストールの計画 —
payram_setup_planを使用して、人間による引き継ぎを含む段階的なPayRam導入計画を依頼します。 - サーバーヘルスの診断 —
payram_doctorを使用して、任意のPayRam URLに対して資格情報なしのチェックを実行し、問題と修正方法を特定します。 - エラーのトラブルシューティング — エラーや症状を貼り付けると、既知の原因、確認事項、次のステップを
payram_troubleshoot経由で取得できます。 - 管理者向けランブックの取得 — SSL、バックアップ、ドメイン変更などの段階的な管理者タスクを
payram_runbookから依頼します。 - デイリー2運用の実行 — エージェントに
payram_ops_playbook経由で、日常チェック、ノード同期、支払いリンク用のAPIレシピを実行させます。 - 統合コードの生成 — ExpressやNext.jsなどのフレームワーク向けに、コピー＆ペースト可能な支払い、 payout、Webhookスニペットを依頼します。
ドキュメント
PayRam MCP サーバー — AI エージェント向けセルフホスト型暗号通貨決済
セルフホスト型の暗号通貨・ステーブルコイン決済：アカウント凍結なし、資金凍結なし、顧客データが共有されることはありません。あなたのAIエージェントはMCP経由で計画、インストール、運用ができます。 ホスト型エンドポイント:
https://mcp.payram.com/mcp· ウェブサイト · ドキュメント · Agentic · OpenClaw
MCP（Model Context Protocol）サーバーであり、MCP対応のAIエージェント — OpenClaw、Hermes、Claude、Cursor、GitHub Copilot など — がセルフホスト型の PayRam 暗号通貨決済スタックをデプロイ、統合、運用できるようにします。
ここから始めます: 4つのツールがカタログの先頭にあります:
| ツール | 機能 |
|---|---|
payram_setup_plan | 人間による引き継ぎ箇所がすべてマークされた、パーソナライズされたインストール計画 |
payram_doctor | URLによるPayRamサーバーの公開・資格情報不要のチェック |
payram_troubleshoot | 問題の説明またはエラーの貼り付け: 既知の原因、確認方法、修正方法、次のツール |
payram_runbook | 管理タスク: サイト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を自分で実行する場合にのみ存在します。
エージェントとクローラー向け: サーバーカード · スキルインデックス · llms.txt · サイトマップ。サーバーは 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として決済します。
- サーバー上に入金キーなし — スマートコントラクトが入金をコールドウォレットにスイープするため、サーバーが侵害されても入金をリダイレクトできません。サーバーのホットウォレットはガスを支払い、支払いに署名するため、残高は少なく保ってください。
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はエージェントファーストのインフラストラクチャです。統合はMCP経由であるため、MCP対応の任意のランタイム — OpenClaw、Hermes、Claude Desktop、Cursor、GitHub Copilot、n8n、LangChain など — と連携します。典型的なエージェントのフロー:
- 接続 —
https://mcp.payram.com/mcpをエージェントのMCP設定に追加します（接続するだけならAPIキーは不要です）。 - 計画 —
payram_setup_planを呼び出します。順序付けられた手順、各手順の実行者、エージェントが人間のために停止する必要がある場所（コールドウォレット、メインネットのガス、root専用設定）が返されます。 - インストール — VPS上で、対話型ターミナルで一度だけ
bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet（または--mainnet; インストーラーのデフォルトはメインネットなので、常にフラグを渡してください）を実行します。bashにパイプしないでください。 - 引き継ぎ — 人間がすぐにrootアカウントを取得し、公開ドメインから設定 → サイト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）。
目次
- PayRamとは？
- AIエージェントがPayRamをどのように使用するか
- エージェントスキル
- プロジェクトの目標
- クイックスタート
- MCPクライアントから接続
- ローカルモード
- 資格情報
- ツールカタログ
- ガイド付きワークフロー
- 開発
- トラブルシューティング
エージェントスキル
エージェントの正面玄関: https://mcp.payram.com/SKILL.md — PayRamを説明し、エージェントを4つの開始ツールにルーティングする単一のルートスキル。他にも提供: /llms.txt。
このリポジトリには、AIコーディングアシスタント向けの19のエージェントスキルが含まれています。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 | インストール計画とサーバーセットアップ: 要件、インストーラー、サイトURL、ウォレット、最初の支払いリンク |
payram-agent-onboarding | エージェントによるヘッドレスインストール: エージェント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 | 開始マップ: インストール（マーチャントまたはオペレーター）→ ウォレット → ガス/スイープ → 統合 → テスト |
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_* スニペットツールが続くはずです。次に、「pay.example.com にPayRamのインストールを計画して」、「https://pay.example.com を確認して」、「FastAPIの支払い作成ルートを生成して」、「Next.jsのウェブフックハンドラーを提供して」と試してください。
プロンプト: 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には 2つの認証情報 があります。エージェントはこれらを混同すると停止します:
| 認証情報 | 形式 | 用途 | エージェントが取得する方法（ダッシュボード不要） |
|---|---|---|---|
マーチャントAPIキー（PAYRAM_API_KEY、ヘッダー API-Key） | プロジェクトごとのキー | POST /api/v1/payment（支払いリンク）、マーチャントの支払い、すべてのマーチャントのサーバー間呼び出し、およびウェブフックの署名（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 | 個人向けの順序付きインストール計画（準備 → インストール → ルートとSite URLの取得 → ウォレットとSmart Bridge → APIキーと最初のリンク → セキュリティ強化 → 統合）で、エージェントと人間の手順、およびハードストップを含む。 |
| 開始 – 診断 | 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 | エージェントが自ら実行する直接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なし）出金、3ステップの保存済み受取人フロー（受取人作成 → 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用のハンドラー、ファンアウトルーター、および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 | 支払い、出金、Webhook、およびブラウザコンソールを備えた完全なスターターアプリ（Express、Next.js、FastAPI、Laravel、Gin、Spring Boot）を生成。デプロイ前に、出金エンドポイントを独自の管理認証の背後に配置してください。 |
| ライブデータ（読み取り専用、ローカルモード） | 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のインストール
- 「pay.example.com に PayRam をセットアップして」と依頼します（または
setup-payram/setup-payram-agentプロンプトを使用）。 - アシスタントは
payram_setup_planを呼び出し、各フェーズを進め、すべての人間のステップ（ルートアカウント、Site URL、コールドウォレット、メインネットガス）で停止します。 - 最後に
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. 「Test 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キーであることを確認します（AuthorizationではなくAPI-Keyヘッダーとして送信されます）。- データツールが認証情報が利用できないと言う： ホスト型サーバーはマーチャントの認証情報を保持しません。一致する
payram_ops_playbookタスクを使用するか、ローカルモードでMCPを実行します。 - 支払いリンクが
http://localhostを表示する： 人間が公開ドメインから設定 → サイトURLを保存する必要があります（payram_runbookタスクset_site_url）。 - ドキュメントツールがファイルが存在しないと言う： ローカルの
docs/payram-docs-live/ツリーに要求されたマークダウンが含まれていることを確認します（get_payram_doc_by_idは..を含むパスを拒否します）。 - サーバーが起動しない： Node 20+を確認し、
yarn installを実行します。非ループバックのHOSTとPAYRAM_*の認証情報が設定されたローカルモードでは、MCP_SERVER_TOKENが設定されるまでサーバーは起動を拒否します（ローカルモードを参照）。
その他の問題については、src/utils/logger.tsから出力される構造化ログを検査し（LOG_LEVEL=debugを設定）、再現の詳細を含む問題/PRを開いてください。