Skip to content
Back to search

payram-mcp

Connect to hosted payram helper at: https://mcp.payram.com

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/payram--payram-mcp/badge.svg)](/listings/payram--payram-mcp)

HTML

<a href="/listings/payram--payram-mcp"><img src="/api/listings/payram--payram-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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` | Server deployment with web dashboard, manual wallet configuration UI | | `payram-agent-onboarding` | Agent onboarding — CLI-only deployment for AI agents, no web UI | | `payram-auth` | JWT auth flow — signin, token refresh, logout, external-platform details | | `payram-analytics` | Analytics dashboards, reports, and payment insights via MCP tools | | `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` | Embed the Add-Credit widget + webhook handlers for 5 frameworks | | `payram-webhook-integration` | Webhook 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 |

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 365 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # PayRam MCP Server — Self-Hosted Crypto Payments for AI Agents
  2. > **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.**
  3. > 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)
  4. 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.
  5. **Start here:** four tools lead the catalog:
  6. | Tool | What it does |
  7. | --------------------- | -------------------------------------------------------------------------------------------------------- |
  8. | `payram_setup_plan` | A personalised install plan, with every human hand-off marked |
  9. | `payram_doctor` | A public, credential-free check of a PayRam server by URL |
  10. | `payram_troubleshoot` | Describe a problem or paste an error: known causes, how to confirm, the fix, and the next tool |
  11. | `payram_runbook` | Admin tasks: Site URL, domain, SSL, firewall, upgrade, backup, chains, Smart Bridge, Shopify/WooCommerce |
  12. | `payram_ops_playbook` | Day-2 API recipes the agent runs itself with its own credentials |
  13. Around them sit codebase assessment, starter-app scaffolds, multi-language snippets and inline docs.
  14. **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).
  15. **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.
  16. ---
  17. ## What is PayRam? · PayRam 是什么?
  18. **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.
  19. **What makes it different:**
  20. - **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.
  21. - **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.
  22. - **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.
  23. - **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.
  24. - **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.
  25. > **PayRam 是一个你完全自托管、自主拥有的多链加密货币支付网关——运行它无需注册、无需 KYC/KYB。** AI 智能体(或开发者)无需在 PayRam、银行或任何支付处理商处注册账户,即可搭建店铺并开始收款。在自己的 VPS 上部署,本地生成 API 密钥,即刻上线。
  26. >
  27. > **核心差异:**
  28. >
  29. > - **没有人能把你锁在门外** — 没有可被封禁的账户,也没有可被冻结的资金;客户数据从不外泄,也没有任何上报或监控。原因很简单:PayRam 运行在你自己的服务器上,资金直接进入你自己的钱包。
  30. > - **免注册、免许可** — 无需注册、无需 KYC、无需 KYB。没有人审批你,也没有人能关停你。非常适合自主搭建店铺的智能体,以及像**中国**这样难以在西方支付处理商处注册的市场。
  31. > - **银行卡转加密货币结算** — 没有加密货币的买家也能用**信用卡/借记卡**付款,你直接收到加密货币并结算到自托管的钱包。这是内置的支付渠道,在「Payments(支付)」页面开启;银行卡服务商会对买家进行其自身的审核。
  32. > - **多链支持** — 原生支持在 Bitcoin、Ethereum、Base、Polygon、Tron 上接受 BTC、ETH、USDT、USDC、TRX,自动检测充值、链上确认、归集冷钱包并发送带签名的 Webhook。**Smart Bridge** 通道还可接收 **Solana、Bitcoin、Tron(USDT)和 BNB Chain** 上的付款,并以 Base 上的 USDC 结算。
  33. > - **服务器上没有充值私钥** — 智能合约把充值资金归集到你的冷钱包,即便服务器被攻破也无法改变资金去向。服务器上的热钱包负责支付 Gas 并签署出款,请只保留少量余额。
  34. ---
  35. ## How AI agents use PayRam · AI 智能体如何使用 PayRam
  36. 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:
  37. 1. **Connect** — add `https://mcp.payram.com/mcp` to the agent's MCP config (no API key needed just to connect).
  38. 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).
  39. 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`.
  40. 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`.
  41. 5. **Check** — `payram_doctor` with the public URL (no credentials needed).
  42. 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).
  43. 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.
  44. ```json
  45. {
  46. "mcpServers": {
  47. "payram": { "url": "https://mcp.payram.com/mcp" }
  48. }
  49. }
  50. ```
  51. 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).
  52. > 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 服务器从不保存商户凭证。
  53. > 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`).
  54. > 如果你的网络难以访问 GitHub,可以把本仓库镜像到其他 Git 托管平台(`git clone --mirror https://github.com/PayRam/payram-mcp.git`)。
  55. ---
  56. ## Table of Contents
  57. - [What is PayRam?](#what-is-payram--payram-是什么)
  58. - [How AI agents use PayRam](#how-ai-agents-use-payram--ai-智能体如何使用-payram)
  59. - [Agent Skills](#agent-skills)
  60. - [Project Goals](#project-goals)
  61. - [Quick Start](#quick-start)
  62. - [Connect from your MCP client](#connect-from-your-mcp-client)
  63. - [Local mode](#local-mode)
  64. - [Credentials](#credentials-which-key-for-what)
  65. - [Tool Catalog](#tool-catalog)
  66. - [Guided Workflows](#guided-workflows)
  67. - [Development](#development)
  68. - [Troubleshooting](#troubleshooting)
  69. ---
  70. ## Agent Skills
  71. **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).
  72. This repository includes 19 Agent Skills for AI coding assistants. Install them via [skills.sh](https://skills.sh):
  73. ### Install individually
  74. ```bash
  75. npx skills add payram/payram-mcp/payram-setup
  76. npx skills add payram/payram-mcp/payram-agent-onboarding
  77. npx skills add payram/payram-mcp/payram-auth
  78. npx skills add payram/payram-mcp/payram-analytics
  79. npx skills add payram/payram-mcp/payram-crypto-payments
  80. npx skills add payram/payram-mcp/payram-payment-integration
  81. npx skills add payram/payram-mcp/payram-self-hosted-payment-gateway
  82. npx skills add payram/payram-mcp/payram-checkout-integration
  83. npx skills add payram/payram-mcp/payram-widget-integration
  84. npx skills add payram/payram-mcp/payram-webhook-integration
  85. npx skills add payram/payram-mcp/payram-stablecoin-payments
  86. npx skills add payram/payram-mcp/payram-bitcoin-payments
  87. npx skills add payram/payram-mcp/payram-payouts
  88. npx skills add payram/payram-mcp/payram-no-kyc-crypto-payments
  89. npx skills add payram/payram-mcp/payram-openclaw-integration
  90. npx skills add payram/payram-mcp/compare-crypto-payments
  91. npx skills add payram/payram-mcp/payram-agent-journey
  92. npx skills add payram/payram-mcp/payram-topup-wallet-integration
  93. npx skills add payram/payram-mcp/payram-testnet-testing
  94. ```
  95. | Skill | Purpose |
  96. | ------------------------------------ | --------------------------------------------------------------------------------------------- |
  97. | `payram-setup` | Install plan and server setup: requirements, installer, Site URL, wallets, first payment link |
  98. | `payram-agent-onboarding` | Headless install by an agent: agent CLI commands, env vars, human hand-offs |
  99. | `payram-auth` | JWT auth flow — signin, token refresh, logout, external-platform details |
  100. | `payram-analytics` | Payment search, volume, balances and sweep history via direct REST APIs (JWT) |
  101. | `payram-crypto-payments` | Architecture overview, why PayRam, MCP tools |
  102. | `payram-payment-integration` | Quick-start payment integration guide |
  103. | `payram-self-hosted-payment-gateway` | Deploy and own your payment infrastructure |
  104. | `payram-checkout-integration` | Checkout flow with SDK + HTTP for 6 frameworks |
  105. | `payram-widget-integration` | Safe "Add Credit" button (backend endpoint, never a public API key) + signed-webhook handlers |
  106. | `payram-webhook-integration` | Signed-webhook (HMAC) handlers for Express, Next.js, FastAPI, Gin, Laravel, Spring Boot |
  107. | `payram-stablecoin-payments` | USDT/USDC acceptance across EVM chains and Tron |
  108. | `payram-bitcoin-payments` | BTC with HD wallet derivation and mobile signing |
  109. | `payram-payouts` | Send crypto payouts and manage referral programs |
  110. | `payram-no-kyc-crypto-payments` | No-KYC, no-signup, permissionless payment acceptance |
  111. | `payram-openclaw-integration` | Integrate PayRam into OpenClaw / agent runtimes — MCP register, testnet, chat commerce |
  112. | `compare-crypto-payments` | Compare gateways: Stripe, BitPay, Coinbase, NOWPayments, BTCPay, PayRam, x402 |
  113. | `payram-agent-journey` | Start-here map: install (merchant or operator) → wallets → gas/sweep → integrate → test |
  114. | `payram-topup-wallet-integration` | Existing apps: credit crypto to a user balance, debit invoices from it — ledger + flows |
  115. | `payram-testnet-testing` | Pay your own payment link on testnet end-to-end before mainnet |
  116. ---
  117. ## Project Goals
  118. - **Accelerate onboarding** with a personalised setup plan, runbooks, env templates and per-framework playbooks.
  119. - **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.
  120. - **Retrofit existing repos** via the project assessment tool (local mode), which scans package manifests and `.env` files, then recommends the right integration snippets.
  121. - **Provide copy/paste snippets** spanning Payments, Payouts, Referrals, Webhooks, and multi-language backends (Express, Next.js, FastAPI, Laravel, Gin, Spring Boot, etc.).
  122. - **Keep docs local** so Copilot can explain PayRam concepts, flows, and referral dashboards without leaving the editor.
  123. - **Validate connectivity** with read-only probes that never create payments (`payram_doctor`, `test_payram_connection`).
  124. ---
  125. ## Quick Start
  126. 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:
  127. 1. **Install dependencies**
  128. ```bash
  129. yarn install
  130. ```
  131. This repo uses Yarn 1. Node 25 and later no longer ship Corepack, so on Node 26 install Yarn first with `npm install -g yarn`.
  132. 2. **Configure environment** (only needed for the local-mode data tools)
  133. - Copy `.env.example` to `.env`.
  134. - Set `PAYRAM_BASE_URL` to your PayRam URL, the same origin as the dashboard (e.g. `https://pay.example.com`).
  135. - Set `PAYRAM_API_KEY`, plus the JWT variables for the data tools. See [Local mode](#local-mode).
  136. 3. **Run the server**
  137. ```bash
  138. yarn dev
  139. # Streamable HTTP on http://127.0.0.1:3333/mcp (local mode; there is no SSE transport)
  140. ```
  141. 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`.
  142. 5. **Health check**
  143. ```bash
  144. curl http://localhost:3333/healthz
  145. ```
  146. > **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.
  147. ---
  148. ## Connect from your MCP client
  149. **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.
  150. | Client | Where | Settings |
  151. | ---------------------- | ------------------------------------------------------------ | --------------------------------------- |
  152. | VS Code (Copilot Chat) | Settings → Copilot: Model Context Protocol → Add HTTP server | Name `payram`, URL above, headers empty |
  153. | Cursor | Settings → MCP Servers → Add → HTTP | Name `payram`, URL above |
  154. | Claude Desktop / Code | Settings → MCP Servers → Add HTTP server | Name `payram`, URL above |
  155. | Any MCP client | Register an HTTP endpoint | URL above, no headers |
  156. **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".
  157. **Prompts:** `setup-payram`, `setup-payram-agent`, `integrate-payment`, `troubleshoot-payment`, `daily-ops`.
  158. **Resources:** `payram://docs/setup-guide`, `payram://docs/api-reference`, and the templates `payram://ops/playbook/{task}` and `payram://runbooks/{task}`.
  159. ### Copilot automation prompt
  160. Paste this once into a fresh workspace to make "test payram" run the full readiness flow automatically:
  161. ```
  162. You have access to the `payram` MCP server in this workspace.
  163. Whenever I ask you to "test my Payram connection" (or I type "test payram"), follow this order:
  164. 1. Call `prepare_payram_test` (no inputs) and share the checklist verbatim.
  165. 2. Look for a `.env` in the workspace root; create one if missing.
  166. 3. Ensure `.env` defines `PAYRAM_BASE_URL` and `PAYRAM_API_KEY`. If either is
  167. missing, call `generate_env_template` and append it (with TODOs) to `.env`.
  168. Do NOT call `test_payram_connection` until real values are provided.
  169. 4. Once real values exist, call `test_payram_connection` with baseUrl/apiKey
  170. from `.env`, show the structured result, and explain whether the
  171. connection is healthy. If anything fails, run `payram_doctor` and follow
  172. its ranked fixes.
  173. ```
  174. ---
  175. ## Local mode
  176. Run the MCP next to your own PayRam to get the live data tools:
  177. - `list_platforms`, `search_payments`, `lookup_payment`, `get_payment_summary`, `get_daily_volume`, `get_unswept_balances`, `list_currencies`, `list_recipients`
  178. - `create_payment_link`, `check_payment_readiness`, `check_node_sync`, `restart_payram_worker`
  179. - `assess_payram_project`
  180. ```bash
  181. PAYRAM_MCP_MODE=local yarn dev # or: yarn build && PAYRAM_MCP_MODE=local yarn start
  182. ```
  183. - **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.
  184. - **Binding:** local mode binds to **`127.0.0.1`** by default (port `PORT`, default 3333).
  185. - **Non-loopback binds:** set `HOST` (e.g. `HOST=0.0.0.0`), then:
  186. - Set `MCP_ALLOWED_HOSTS` (comma-separated hostnames accepted in the `Host` header).
  187. - Set `MCP_SERVER_TOKEN`; clients then send `Authorization: Bearer <token>`.
  188. - 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.
  189. - **Credentials:** the data tools read `PAYRAM_*` from the environment (or `.env`):
  190. - `PAYRAM_BASE_URL`
  191. - `PAYRAM_API_KEY` (payment links)
  192. - `PAYRAM_ACCESS_TOKEN` / `PAYRAM_REFRESH_TOKEN` (JWT, data tools)
  193. - `PAYRAM_EXTERNAL_PLATFORM_ID` (optional default project)
  194. Example client config for a local server (local mode only):
  195. ```json
  196. {
  197. "mcpServers": {
  198. "payram-local": { "url": "http://localhost:3333/mcp" }
  199. }
  200. }
  201. ```
  202. ---
  203. ## Credentials: which key for what
  204. PayRam has **two credentials** — agents stall when they conflate them:
  205. | Credential | Looks like | Used for | How an agent gets it (no dashboard needed) |
  206. | --------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  207. | **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` |
  208. | **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` |
  209. 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://<your-domain>/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.
  210. ---
  211. ## Tool Catalog
  212. | Category | Tool | Purpose |
  213. | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  214. | **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. |
  215. | **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. |
  216. | **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`. |
  217. | **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`. |
  218. | **Connectivity** | `test_payram_connection` | Read-only reachability/health check plus optional API-key validation. Never creates payments. |
  219. | **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. |
  220. | **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. |
  221. | **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. |
  222. | **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. |
  223. | **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. |
  224. | **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. |
  225. | **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. |
  226. | **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. |
  227. | **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. |
  228. | **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. |
  229. | **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. |
  230. | **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. |
  231. > Tool registrations live in `src/tools/index.ts`; individual implementations sit in `src/tools/**` with language-specific templates under `templates/` folders.
  232. ---
  233. ## Guided Workflows
  234. ### 0. Install PayRam
  235. 1. Ask: "Set up PayRam on pay.example.com" (or use the `setup-payram` / `setup-payram-agent` prompts).
  236. 2. The assistant calls `payram_setup_plan` and walks the phases, stopping at every human step (root account, Site URL, cold wallet, mainnet gas).
  237. 3. It finishes with `payram_doctor`, backups (`payram_runbook` `backup`) and the daily check (`payram_ops_playbook` `daily_check`).
  238. ### 1. Assess and Retrofit an Existing Project
  239. 1. Ask Copilot: "Can you integrate PayRam into this project?"
  240. 2. The assistant runs `assess_payram_project` (local mode), reviewing dependency manifests and `.env`.
  241. 3. Follow the recommended steps (install `payram`, request Express/FastAPI/Spring route snippets, add webhooks, etc.).
  242. 4. Use `test_payram_connection` once credentials are real to ensure the backend can reach your self-hosted server.
  243. ### 2. Scaffold a Fresh Sample
  244. 1. "Create a PayRam Express demo" → `scaffold_payram_app` builds an Express project with payments, payouts, webhooks, and a UI console.
  245. 2. Drop the generated files into an empty repo or compare against your existing directory for reference wiring.
  246. ### 3. Run the "Test PayRam" Readiness Flow
  247. 1. Say "test payram". The assistant automatically:
  248. - Calls `prepare_payram_test` to share the readiness checklist.
  249. - Ensures `.env` exists (creating it if missing) using `generate_env_template`.
  250. - Waits for real credentials before invoking `test_payram_connection`.
  251. 2. Review the structured JSON result to confirm the PayRam API is reachable.
  252. ### 4. Wire Payments, Payouts, Referrals, and Webhooks
  253. - Payments: `generate_payment_sdk_snippet` (JS SDK) or `generate_payment_http_snippet` (Python/Go/PHP/Java).
  254. - Multi-language routes: `snippet_nextjs_payment_route`, `snippet_fastapi_payment_route`, etc.
  255. - Payouts: `generate_payout_sdk_snippet` for create + `generate_payout_status_snippet` for polling.
  256. - Referrals: `generate_referral_route_snippet`, `generate_referral_validation_snippet`.
  257. - Webhooks: `generate_webhook_handler` plus `generate_webhook_event_router` for fan-out + `generate_mock_webhook_event` to test each status.
  258. ---
  259. ## Development
  260. | Command | Description |
  261. | --------------------------- | ----------------------------------------------- |
  262. | `yarn dev` | Run the MCP server with hot reload via `tsx`. |
  263. | `yarn build` | Compile TypeScript to `dist/`. |
  264. | `yarn lint` / `yarn format` | ESLint + Prettier across the repo. |
  265. | `yarn test` | Executes the Vitest suite (`tests/`). |
  266. | `make precommit-test` | Runs format → lint → test → build sequentially. |
  267. 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`.
  268. ---
  269. ## Troubleshooting
  270. > **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`).
  271. - **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.
  272. - **`test_payram_connection` fails with 401:** Confirm the key is an active project API key (sent as the `API-Key` header, not `Authorization`).
  273. - **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).
  274. - **Payment links show `http://localhost`:** the human must save Settings → Site URL from the public domain (`payram_runbook` task `set_site_url`).
  275. - **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 `..`).
  276. - **Server won’t start:** Ensure Node 22.12+ 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)).
  277. 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.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.