# PayRam MCP Server — Self-Hosted Crypto Payments for AI Agents > **Self-hosted crypto and stablecoin payments: no account lock, no fund freeze, customer data never shared. Your AI agent can plan, install and operate it over MCP.** > Hosted endpoint: **`https://mcp.payram.com/mcp`** · [Website](https://payram.com) · [Docs](https://docs.payram.com) · [Agentic](https://payram.com/agentic) · [OpenClaw](https://payram.com/openclaw) An **MCP (Model Context Protocol) server** that lets any MCP-aware AI agent — **OpenClaw, Hermes, Claude, Cursor, GitHub Copilot**, and others — deploy, integrate, and operate a self-hosted [PayRam](https://payram.com) crypto-payment stack. **Start here:** four tools lead the catalog: | Tool | What it does | | --------------------- | -------------------------------------------------------------------------------------------------------- | | `payram_setup_plan` | A personalised install plan, with every human hand-off marked | | `payram_doctor` | A public, credential-free check of a PayRam server by URL | | `payram_troubleshoot` | Describe a problem or paste an error: known causes, how to confirm, the fix, and the next tool | | `payram_runbook` | Admin tasks: Site URL, domain, SSL, firewall, upgrade, backup, chains, Smart Bridge, Shopify/WooCommerce | | `payram_ops_playbook` | Day-2 API recipes the agent runs itself with its own credentials | Around them sit codebase assessment, starter-app scaffolds, multi-language snippets and inline docs. **The hosted server (`mcp.payram.com`) never holds merchant credentials.** Day-2 operations run through `payram_ops_playbook`: the agent calls your PayRam API directly, and the credentials never leave its machine. The live data tools (payment search, payment links, node sync, worker restart) and `assess_payram_project` exist only when you [run the MCP yourself in local mode](#local-mode). **For agents & crawlers:** [server card](https://mcp.payram.com/.well-known/mcp/server-card.json) · [skills index](https://mcp.payram.com/.well-known/agent-skills/index.json) · [llms.txt](https://payram.com/llms.txt) · [sitemap](https://mcp.payram.com/sitemap.xml). The server also answers `Accept: text/markdown` on `/` with an agent-readable summary. --- ## What is PayRam? · PayRam 是什么？ **PayRam is a self-hosted, multi-chain crypto payment gateway you own outright — with no signup and no KYC/KYB to run it.** An AI agent (or a developer) can stand up a store and start accepting payments without registering an account with PayRam, a bank, or any payment processor. Deploy on your own VPS, generate API keys locally, go live. **What makes it different:** - **Nobody can lock you out** — there is no account to lock and no funds to freeze. Customer data is never shared, and nothing is reported or monitored. The reason is simple: PayRam runs on your server and funds land in your own wallet. - **Permissionless setup** — no signup, no KYC, no KYB. Nobody approves you; nobody can switch you off. Ideal for agents spinning up stores autonomously, and for markets like **China** where registering with a Western processor isn't an option. - **Card-to-crypto checkout** — shoppers without crypto can pay with a **credit/debit card** and you receive crypto, settled straight into your self-custodied wallet. It is a built-in channel you switch on from the Payments page; the card provider runs its own checks on the shopper. - **Multi-chain** — accept BTC, ETH, USDT, USDC, and TRX natively across **Bitcoin, Ethereum, Base, Polygon, and Tron**, with automatic deposit detection, on-chain confirmation, sweeps to cold storage, and signed webhooks. **Smart Bridge** rails also take payments on **Solana, Bitcoin, Tron (USDT) and BNB Chain** and settle them as USDC on Base. - **No deposit keys on the server** — smart contracts sweep deposits to your cold wallet, so a compromised server cannot redirect them. The server's hot wallet pays gas and signs payouts, so keep its balance small. > **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 并签署出款，请只保留少量余额。 --- ## How AI agents use PayRam · AI 智能体如何使用 PayRam PayRam is **agent-first infrastructure**. Because integration is over MCP, it works with any MCP-aware runtime — **OpenClaw, Hermes**, Claude Desktop, Cursor, GitHub Copilot, n8n, LangChain, and more. A typical agent flow: 1. **Connect** — add `https://mcp.payram.com/mcp` to the agent's MCP config (no API key needed just to connect). 2. **Plan** — call `payram_setup_plan`. It returns the ordered steps, who runs each one, and where the agent must stop for the human (cold wallet, mainnet gas, root-only settings). 3. **Install** — on the VPS, in an interactive terminal once, run `bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet` (or `--mainnet`; the installer default is mainnet, so always pass the flag). Never pipe it into `bash`. 4. **Hand off** — the human claims the root account right away and saves **Settings → Site URL** from the public domain; until then, payment links point at `http://localhost`. 5. **Check** — `payram_doctor` with the public URL (no credentials needed). 6. **Accept payments** — drop in framework-specific integration code from the snippet tools. Webhooks are signed (`X-Payram-Signature`, HMAC-SHA256 of the raw body with the project API key). 7. **Operate** — `payram_ops_playbook` (`daily_check`, `payment_options`, `node_sync`, `unswept_funds`, `create_payment_link`, …) gives the agent the exact API calls to run with its own credentials. `payram_runbook` covers admin changes. ```json { "mcpServers": { "payram": { "url": "https://mcp.payram.com/mcp" } } } ``` For the OpenClaw-specific walkthrough (registration, testnet on Base Sepolia, chat-commerce patterns for WhatsApp/Telegram/Discord) see the [`payram-openclaw-integration`](skills/payram-openclaw-integration/SKILL.md) skill and [payram.com/openclaw](https://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 服务器从不保存商户凭证。 > If GitHub is hard to reach from your network, you can mirror this repository to another Git host (`git clone --mirror https://github.com/PayRam/payram-mcp.git`). > 如果你的网络难以访问 GitHub，可以把本仓库镜像到其他 Git 托管平台（`git clone --mirror https://github.com/PayRam/payram-mcp.git`）。 --- ## Table of Contents - [What is PayRam?](#what-is-payram--payram-是什么) - [How AI agents use PayRam](#how-ai-agents-use-payram--ai-智能体如何使用-payram) - [Agent Skills](#agent-skills) - [Project Goals](#project-goals) - [Quick Start](#quick-start) - [Connect from your MCP client](#connect-from-your-mcp-client) - [Local mode](#local-mode) - [Credentials](#credentials-which-key-for-what) - [Tool Catalog](#tool-catalog) - [Guided Workflows](#guided-workflows) - [Development](#development) - [Troubleshooting](#troubleshooting) --- ## Agent Skills **Agent front door:** [`https://mcp.payram.com/SKILL.md`](https://mcp.payram.com/SKILL.md) — a single root skill that describes PayRam and routes agents to the four start-here tools. Also served: [`/llms.txt`](https://mcp.payram.com/llms.txt). This repository includes 19 Agent Skills for AI coding assistants. Install them via [skills.sh](https://skills.sh): ### Install individually ```bash 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 ``` | Skill | Purpose | | ------------------------------------ | --------------------------------------------------------------------------------------------- | | `payram-setup` | Install plan and server setup: requirements, installer, Site URL, wallets, first payment link | | `payram-agent-onboarding` | Headless install by an agent: agent CLI commands, env vars, human hand-offs | | `payram-auth` | JWT auth flow — signin, token refresh, logout, external-platform details | | `payram-analytics` | Payment search, volume, balances and sweep history via direct REST APIs (JWT) | | `payram-crypto-payments` | Architecture overview, why PayRam, MCP tools | | `payram-payment-integration` | Quick-start payment integration guide | | `payram-self-hosted-payment-gateway` | Deploy and own your payment infrastructure | | `payram-checkout-integration` | Checkout flow with SDK + HTTP for 6 frameworks | | `payram-widget-integration` | Safe "Add Credit" button (backend endpoint, never a public API key) + signed-webhook handlers | | `payram-webhook-integration` | Signed-webhook (HMAC) handlers for Express, Next.js, FastAPI, Gin, Laravel, Spring Boot | | `payram-stablecoin-payments` | USDT/USDC acceptance across EVM chains and Tron | | `payram-bitcoin-payments` | BTC with HD wallet derivation and mobile signing | | `payram-payouts` | Send crypto payouts and manage referral programs | | `payram-no-kyc-crypto-payments` | No-KYC, no-signup, permissionless payment acceptance | | `payram-openclaw-integration` | Integrate PayRam into OpenClaw / agent runtimes — MCP register, testnet, chat commerce | | `compare-crypto-payments` | Compare gateways: Stripe, BitPay, Coinbase, NOWPayments, BTCPay, PayRam, x402 | | `payram-agent-journey` | Start-here map: install (merchant or operator) → wallets → gas/sweep → integrate → test | | `payram-topup-wallet-integration` | Existing apps: credit crypto to a user balance, debit invoices from it — ledger + flows | | `payram-testnet-testing` | Pay your own payment link on testnet end-to-end before mainnet | --- ## Project Goals - **Accelerate onboarding** with a personalised setup plan, runbooks, env templates and per-framework playbooks. - **Operate without holding credentials**: the hosted server checks a PayRam by URL (`payram_doctor`) and hands agents exact API recipes (`payram_ops_playbook`) to run with their own credentials. - **Retrofit existing repos** via the project assessment tool (local mode), which scans package manifests and `.env` files, then recommends the right integration snippets. - **Provide copy/paste snippets** spanning Payments, Payouts, Referrals, Webhooks, and multi-language backends (Express, Next.js, FastAPI, Laravel, Gin, Spring Boot, etc.). - **Keep docs local** so Copilot can explain PayRam concepts, flows, and referral dashboards without leaving the editor. - **Validate connectivity** with read-only probes that never create payments (`payram_doctor`, `test_payram_connection`). --- ## Quick Start Most agents only need the hosted endpoint, `https://mcp.payram.com/mcp` (see [Connect from your MCP client](#connect-from-your-mcp-client)). To run the server yourself: 1. **Install dependencies** ```bash yarn install ``` 2. **Configure environment** (only needed for the local-mode data tools) - Copy `.env.example` to `.env`. - Set `PAYRAM_BASE_URL` to your PayRam URL, the same origin as the dashboard (e.g. `https://pay.example.com`). - Set `PAYRAM_API_KEY`, plus the JWT variables for the data tools. See [Local mode](#local-mode). 3. **Run the server** ```bash yarn dev # Streamable HTTP on http://127.0.0.1:3333/mcp (local mode; there is no SSE transport) ``` 4. **Add the MCP server to your client**: see [Connect from your MCP client](#connect-from-your-mcp-client). The local-mode URL is `http://localhost:3333/mcp`. 5. **Health check** ```bash curl http://localhost:3333/healthz ``` > **Tip:** When you tell Copilot "test payram" it will automatically run the readiness checklist, ensure `.env` exists, and only then call `test_payram_connection` with your real credentials. The behavior is defined by the [Copilot automation prompt](#copilot-automation-prompt)—no manual prompting required. --- ## Connect from your MCP client **Endpoint:** `https://mcp.payram.com/mcp` (Streamable HTTP, JSON-RPC over POST). There is no SSE endpoint, and `/mcp/sse` returns 410. No auth headers: the hosted server never holds merchant credentials, so yours stay on your machine and never go into chat. | Client | Where | Settings | | ---------------------- | ------------------------------------------------------------ | --------------------------------------- | | VS Code (Copilot Chat) | Settings → Copilot: Model Context Protocol → Add HTTP server | Name `payram`, URL above, headers empty | | Cursor | Settings → MCP Servers → Add → HTTP | Name `payram`, URL above | | Claude Desktop / Code | Settings → MCP Servers → Add HTTP server | Name `payram`, URL above | | Any MCP client | Register an HTTP endpoint | URL above, no headers | **Verify:** the tool list should start with `payram_setup_plan`, `payram_doctor`, `payram_troubleshoot`, `payram_runbook` and `payram_ops_playbook`, followed by `scaffold_payram_app` and the `generate_*` snippet tools. Then try: "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". **Prompts:** `setup-payram`, `setup-payram-agent`, `integrate-payment`, `troubleshoot-payment`, `daily-ops`. **Resources:** `payram://docs/setup-guide`, `payram://docs/api-reference`, and the templates `payram://ops/playbook/{task}` and `payram://runbooks/{task}`. ### Copilot automation prompt Paste this once into a fresh workspace to make "test payram" run the full readiness flow automatically: ``` 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. ``` --- ## Local mode Run the MCP next to your own PayRam to get the live data tools: - `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` ```bash PAYRAM_MCP_MODE=local yarn dev # or: yarn build && PAYRAM_MCP_MODE=local yarn start ``` - **Mode:** `PAYRAM_MCP_MODE=local` selects local mode. It is also the default whenever the server is not running on Vercel. `PAYRAM_MCP_MODE=hosted` never reads credentials. - **Binding:** local mode binds to **`127.0.0.1`** by default (port `PORT`, default 3333). - **Non-loopback binds:** set `HOST` (e.g. `HOST=0.0.0.0`), then: - Set `MCP_ALLOWED_HOSTS` (comma-separated hostnames accepted in the `Host` header). - Set `MCP_SERVER_TOKEN`; clients then send `Authorization: Bearer `. - If `PAYRAM_*` credentials are set, the server refuses to start on a non-loopback `HOST` without `MCP_SERVER_TOKEN`. Prefer loopback plus an SSH tunnel. - **Credentials:** the data tools read `PAYRAM_*` from the environment (or `.env`): - `PAYRAM_BASE_URL` - `PAYRAM_API_KEY` (payment links) - `PAYRAM_ACCESS_TOKEN` / `PAYRAM_REFRESH_TOKEN` (JWT, data tools) - `PAYRAM_EXTERNAL_PLATFORM_ID` (optional default project) Example client config for a local server (local mode only): ```json { "mcpServers": { "payram-local": { "url": "http://localhost:3333/mcp" } } } ``` --- ## Credentials: which key for what PayRam has **two credentials** — agents stall when they conflate them: | Credential | Looks like | Used for | How an agent gets it (no dashboard needed) | | --------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Merchant API key** (`PAYRAM_API_KEY`, header `API-Key`) | per-**project** key | `POST /api/v1/payment` (payment links), merchant payouts, all merchant server-to-server calls, and it signs webhooks (`X-Payram-Signature`) | `bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) ensure-api-key` — reuses or mints the project key via `POST /api/v1/external-platform/{id}/api-key` and saves it to `~/.payraminfo/merchant-api-key.env` | | **JWT** (`Authorization: Bearer`) | access+refresh token from signin | admin/setup APIs (projects, wallets, analytics) — `payram_ops_playbook` recipes and the local-mode data tools | `bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) signin` (env `PAYRAM_EMAIL`/`PAYRAM_PASSWORD`); saved to `~/.payraminfo/headless-tokens.env` | The one-step setup flow (`bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet`) produces **both** automatically and prints where they live. The API is same-origin with the dashboard, on **port 80/443** (`https:///api/v1/...`, or `http://localhost` on the server, never `:8080`). The API key can create payouts, so keep it server-side and never put it in browser code or chat. Use `payram_ops_playbook` task `connect` to set both up for direct API calls. --- ## Tool Catalog | Category | Tool | Purpose | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Start here – Install** | `payram_setup_plan` | Personalised, ordered install plan (prepare → install → claim root + Site URL → wallets + Smart Bridge → API key + first link → harden → integrate) with agent vs human steps and hard stops. | | **Start here – Diagnostics** | `payram_doctor`, `payram_troubleshoot` | `payram_doctor`: public, credential-free staged check by URL (reachability → health → TLS → version → workers) with ranked likely causes + exact fixes. Optional API-key validity check that creates nothing. Run this FIRST when anything fails. `payram_troubleshoot`: match a symptom or pasted error to known causes and fixes. | | **Start here – Admin** | `payram_runbook` | Step-by-step admin tasks with human gates: `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`. | | **Start here – Operations** | `payram_ops_playbook` | Direct-API recipes the agent runs itself: `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`. | | **Connectivity** | `test_payram_connection` | Read-only reachability/health check plus optional API-key validation. Never creates payments. | | **Setup** | `generate_env_template`, `generate_setup_checklist`, `suggest_file_structure`, `get_agent_setup_flow`, `onboard_agent_setup` | Ship env boilerplate, merchant checklists, recommended project layouts, and the headless agent onboarding guide. | | **Context / Docs** | `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`, etc. | Provide inline Markdown knowledge sourced from `docs/` so Copilot can answer conceptual questions. Some tools append “say `test payram`” reminders automatically. | | **Integration – Payments** | `generate_payment_sdk_snippet`, `generate_payment_http_snippet`, `generate_payment_status_snippet`, `generate_payment_route_snippet` | Emit SDK, raw HTTP, or Express/Next.js route code for create + status flows. | | **Integration – Payouts** | `generate_payout_sdk_snippet`, `generate_payout_recipient_flow_snippet`, `generate_payout_status_snippet` | Direct (no-OTP) payout, the 3-step saved-recipient flow (create recipient → validate OTP → pay out), and status polling. | | **Integration – Referrals** | `generate_referral_sdk_snippet`, `generate_referral_validation_snippet`, `generate_referral_status_snippet`, `generate_referral_route_snippet` | Cover referral auth, linking, validation, status, and express/next routes. | | **Integration – Webhooks** | `generate_webhook_handler`, `generate_webhook_event_router`, `generate_mock_webhook_event` | Produce handlers for Express/Next/FastAPI/Gin/Laravel/Spring Boot, fan-out routers, and cURL/Python/Go/PHP/Java webhook testers. | | **Integration – Multi-language Payments** | `snippet_*` family (`snippet_express_payment_route`, `snippet_nextjs_payment_route`, `snippet_fastapi_payment_route`, `snippet_laravel_payment_route`, `snippet_go_payment_handler`, `snippet_spring_payment_controller`) | Prebuilt route handlers for Express, Next.js App Router, FastAPI, Gin, Laravel, and Spring Boot. | | **Integration – Top-Up Wallet** | `generate_topup_integration_snippet` | For EXISTING apps: ledger schema + cumulative-credit webhook + atomic invoice settle, so over/under/late/duplicate crypto payments become balance states instead of payment exceptions. Pairs with the `payram-topup-wallet-integration` skill. | | **Integration – Project Assessment** (local mode) | `assess_payram_project` | Scans `package.json`, `requirements.txt`, `composer.json`, `go.mod`, `pom.xml`, `.env`, etc. Reports detected frameworks, env status, PayRam dependencies, and prioritized next steps with tool suggestions. | | **Scaffolding** | `scaffold_payram_app` | Generates full starter apps (Express, Next.js, FastAPI, Laravel, Gin, Spring Boot) with payments, payouts, webhooks, and a browser console. Put the payout endpoints behind your own admin auth before deploying. | | **Live Data (read-only, local mode)** | `list_platforms`, `search_payments`, `lookup_payment`, `get_payment_summary`, `get_daily_volume`, `get_unswept_balances`, `list_currencies`, `list_recipients` | Query live PayRam data. `list_currencies` is public (no key); the rest use the JWT tokens in `.env`. `list_recipients` pairs with the payout recipient flow. | | **Live Operations (local mode)** | `create_payment_link` (write), `check_payment_readiness`, `check_node_sync`, `restart_payram_worker` (write) | `create_payment_link` creates a real checkout link via `API-Key`. `check_payment_readiness` reports per-chain gaps (missing wallet / currency / listener) to accept payments. `check_node_sync` reports listener-worker + RPC node health and block staleness. On the hosted server, use the matching `payram_ops_playbook` tasks. | > Tool registrations live in `src/tools/index.ts`; individual implementations sit in `src/tools/**` with language-specific templates under `templates/` folders. --- ## Guided Workflows ### 0. Install PayRam 1. Ask: "Set up PayRam on pay.example.com" (or use the `setup-payram` / `setup-payram-agent` prompts). 2. The assistant calls `payram_setup_plan` and walks the phases, stopping at every human step (root account, Site URL, cold wallet, mainnet gas). 3. It finishes with `payram_doctor`, backups (`payram_runbook` `backup`) and the daily check (`payram_ops_playbook` `daily_check`). ### 1. Assess and Retrofit an Existing Project 1. Ask Copilot: "Can you integrate PayRam into this project?" 2. The assistant runs `assess_payram_project` (local mode), reviewing dependency manifests and `.env`. 3. Follow the recommended steps (install `payram`, request Express/FastAPI/Spring route snippets, add webhooks, etc.). 4. Use `test_payram_connection` once credentials are real to ensure the backend can reach your self-hosted server. ### 2. Scaffold a Fresh Sample 1. "Create a PayRam Express demo" → `scaffold_payram_app` builds an Express project with payments, payouts, webhooks, and a UI console. 2. Drop the generated files into an empty repo or compare against your existing directory for reference wiring. ### 3. Run the "Test PayRam" Readiness Flow 1. Say "test payram". The assistant automatically: - Calls `prepare_payram_test` to share the readiness checklist. - Ensures `.env` exists (creating it if missing) using `generate_env_template`. - Waits for real credentials before invoking `test_payram_connection`. 2. Review the structured JSON result to confirm the PayRam API is reachable. ### 4. Wire Payments, Payouts, Referrals, and Webhooks - Payments: `generate_payment_sdk_snippet` (JS SDK) or `generate_payment_http_snippet` (Python/Go/PHP/Java). - Multi-language routes: `snippet_nextjs_payment_route`, `snippet_fastapi_payment_route`, etc. - Payouts: `generate_payout_sdk_snippet` for create + `generate_payout_status_snippet` for polling. - Referrals: `generate_referral_route_snippet`, `generate_referral_validation_snippet`. - Webhooks: `generate_webhook_handler` plus `generate_webhook_event_router` for fan-out + `generate_mock_webhook_event` to test each status. --- ## Development | Command | Description | | --------------------------- | ----------------------------------------------- | | `yarn dev` | Run the MCP server with hot reload via `tsx`. | | `yarn build` | Compile TypeScript to `dist/`. | | `yarn lint` / `yarn format` | ESLint + Prettier across the repo. | | `yarn test` | Executes the Vitest suite (`tests/`). | | `make precommit-test` | Runs format → lint → test → build sequentially. | Project is TypeScript-first (ESM). Prettier config lives in `.prettierrc.json`; ESLint is configured via `eslint.config.mjs`. Smooth contributions follow the commit helper in `Makefile` → `make commit`. --- ## Troubleshooting > **Start with `payram_doctor`** — one read-only call that walks reachability → health → TLS → version → workers and returns ranked causes with exact fixes. For deeper checks, follow `payram_ops_playbook` (`stuck_payment`, `node_sync`, `webhooks`, `logs`). - **Copilot doesn’t call the right tool:** Check the [Copilot automation prompt](#copilot-automation-prompt) is installed and your MCP client loaded the server. Re-run "test payram" or "assess my project" to trigger the expected automation. - **`test_payram_connection` fails with 401:** Confirm the key is an active project API key (sent as the `API-Key` header, not `Authorization`). - **A data tool says credentials are unavailable:** the hosted server never holds merchant credentials. Use the matching `payram_ops_playbook` task, or run the MCP in [local mode](#local-mode). - **Payment links show `http://localhost`:** the human must save Settings → Site URL from the public domain (`payram_runbook` task `set_site_url`). - **Docs tool says a file is missing:** Verify your local `docs/payram-docs-live/` tree contains the requested markdown (`get_payram_doc_by_id` rejects paths with `..`). - **Server won’t start:** Ensure Node 20+ and run `yarn install`. In local mode with a non-loopback `HOST` and `PAYRAM_*` credentials set, the server refuses to start until `MCP_SERVER_TOKEN` is set (see [Local mode](#local-mode)). For anything else, inspect the structured logs emitted from `src/utils/logger.ts` (set `LOG_LEVEL=debug`) and open an issue/PR with reproduction details.