Content
# PayRam MCP Server — Self-Hosted Crypto Payments for AI Agents
> **A no-signup, no-KYC crypto payment gateway with card-to-crypto checkout — your AI agent can deploy 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. It exposes tools to assess a codebase, scaffold starter apps, generate multi-language integration snippets, read inline docs, create payment links, and check node sync + payment readiness against your own deployment.
**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 in ~10 minutes, generate API keys locally, go live.
**What makes it different:**
- **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. A built-in channel you switch on from the Payments page — no extra processor to sign up with.
- **Multi-chain** — accept BTC, ETH, USDT, USDC, and TRX across **Bitcoin, Ethereum, Base, Polygon, and Tron**, with automatic deposit detection, on-chain confirmation, sweeps to cold storage, and webhooks.
- **Self-custody by design** — **deposit wallet keys are never stored on the server.** Fund movement is enforced on-chain by smart contracts with hardcoded cold-wallet destinations, so a full server compromise yields zero spendable funds. An agent can run the whole stack without ever holding a private key.
> **PayRam 是一个你完全自托管、自主拥有的多链加密货币支付网关——运行它无需注册、无需 KYC/KYB。** AI 智能体（或开发者）无需在 PayRam、银行或任何支付处理商处注册账户，即可搭建店铺并开始收款。在自己的 VPS 上约 10 分钟即可部署，本地生成 API 密钥，即刻上线。
>
> **核心差异：**
> - **免注册、免许可** — 无需注册、无需 KYC、无需 KYB。没有人审批你，也没有人能关停你。非常适合自主搭建店铺的智能体，以及像**中国**这样难以在西方支付处理商处注册的市场。
> - **银行卡转加密货币结算** — 没有加密货币的买家也能用**信用卡/借记卡**付款，你直接收到加密货币并结算到自托管的钱包。这是内置的支付渠道，在「Payments（支付）」页面一键开启——无需额外对接任何第三方支付处理商。
> - **多链支持** — 在 Bitcoin、Ethereum、Base、Polygon、Tron 上接受 BTC、ETH、USDT、USDC、TRX，自动检测充值、链上确认、归集冷钱包并发送 Webhook。
> - **原生自托管** — **充值钱包私钥永不存储在服务器上**，资金转移由链上智能合约强制执行、目的地冷钱包地址硬编码，即便服务器被完全攻破也无法盗取资金。智能体无需持有任何私钥即可运行整个系统。
---
## 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. **Deploy** — the agent runs the one-line agent-mode installer to stand up a gateway on a VPS, no web UI required.
3. **Accept payments** — generate a checkout link (`create_payment_link`) or drop in framework-specific integration code from the snippet tools.
4. **Operate** — `check_payment_readiness` reports per-chain gaps before go-live; `check_node_sync` watches listener + RPC health; webhooks fulfil orders on `FILLED`.
```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 端点 → 用一行命令**部署**网关 → 生成支付链接或集成代码来**收款** → 通过就绪检查与节点同步检查**运维**，并在收到 `FILLED` Webhook 时完成订单履约。
---
## 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)
- [Tool Catalog](#tool-catalog)
- [Guided Workflows](#guided-workflows)
- [Docs & Specs](#docs--specs)
- [Development](#development)
- [Troubleshooting](#troubleshooting)
---
## Agent Skills
This repository includes 16 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
```
| 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 |
---
## Project Goals
- **Accelerate onboarding** by serving env templates, readiness checklists, and per-framework playbooks.
- **Retrofit existing repos** via the project assessment tool, 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** through a built-in `/api/v1/payment` probe that enforces the `API-Key` header PayRam expects.
---
## Quick Start
1. **Install dependencies**
```bash
yarn install
```
2. **Configure environment**
- Copy `.env.example` to `.env` and fill `PAYRAM_BASE_URL` + `PAYRAM_API_KEY`, or run the MCP tool `generate_env_template` from Copilot to append the template automatically.
3. **Run the server**
```bash
yarn dev
# exposes HTTP + SSE transports on http://localhost:3333/mcp and /mcp/sse
```
4. **Add the MCP server to Copilot / your MCP client**
- Hosted MCP server: `https://mcp.payram.com`.
- Local dev server: `http://localhost:3333/mcp` (or `/mcp/sse` if it supports streaming).
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 documented in `COPILOT-USE.md`—no manual prompting required.
---
## Tool Catalog
| Category | Tool | Purpose |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Connectivity** | `test_payram_connection` | POSTs to `/api/v1/payment` using `API-Key`. Returns status, headers, and helpful errors when `.env` is incomplete. |
| **Setup** | `generate_env_template`, `generate_setup_checklist`, `suggest_file_structure` | Ship env boilerplate, merchant runbooks, and recommended project layouts for PayRam modules. |
| **Context / Docs** | `explain_payram_basics`, `explain_payram_concepts`, `explain_payment_flow`, `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_*_payment_route` family | Prebuilt route handlers for Express, Next.js App Router, FastAPI, Gin, Laravel, and Spring Boot. |
| **Integration – Project Assessment** | `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. |
| **Live Data (read-only)** | `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** | `create_payment_link` (write), `check_payment_readiness`, `check_node_sync` | `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. |
> Tool registrations live in `src/tools/index.ts`; individual implementations sit in `src/tools/**` with language-specific templates under `templates/` folders.
---
## Guided Workflows
### 1. Assess and Retrofit an Existing Project
1. Ask Copilot: "Can you integrate PayRam into this project?"
2. The assistant runs `assess_payram_project`, 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.
---
## Skills vs. MCP Tools
This repository provides two integration paths for AI agents:
| Feature | MCP Server (Tools) | Agent Skills (skills.sh) |
| ------------------------ | ------------------------------------ | ---------------------------------------- |
| **Client Requirements** | MCP-aware (GitHub Copilot, etc.) | Any AI agent (Claude, GPT, etc.) |
| **Dynamic Capabilities** | ✅ Generate code, assess projects | ❌ Static instructions only |
| **Connectivity Testing** | ✅ Live API validation | ❌ Instructions for manual testing |
| **Code Generation** | ✅ Framework-specific templates | ✅ Copy-paste code examples |
| **Documentation Access** | ✅ Query PayRam docs dynamically | ✅ Inline references to docs |
| **Best For** | Interactive development with Copilot | AI chat interfaces, non-MCP environments |
**Recommended workflow with skills:**
1. Start with `payram-setup` to configure your server, API keys, and wallets
2. Use `payram-payment-integration` or `payram-crypto-payments` for integration overview
3. Follow `payram-checkout-integration` for payment flow implementation
4. Add `payram-webhook-integration` for real-time event handling
5. Use `payram-payouts` for outbound payments and affiliate tracking
---
## Docs & Specs
- Local references live under `docs/`:
- `docs/js-sdk.md` – expanded guide for the TypeScript SDK.
- `docs/payram-external.yaml`, `docs/payram-webhook.yaml` – OpenAPI specs.
- `docs/referrals.md` – referral FAQs and workflows.
- MCP doc tools (`get_payram_doc_by_id`, `list_payram_docs`) read files from `docs/payram-docs-live/**` via `src/utils/markdownLoader.ts`.
- For future updates, run `make fetch-docs` to sync the latest documentation from docs.payram.com into `docs/payram-docs-live/`.
---
## 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/health.test.ts`). |
| `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
- **Copilot doesn’t call the right tool:** Check `COPILOT-USE.md` and ensure 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 `.env` uses the `API-Key` header, not `Authorization`. The tool echoes the missing fields when placeholders are detected.
- **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:** Check `.env` for `PAYRAM_BASE_URL`/`PAYRAM_API_KEY`, ensure Node 18+, and run `yarn install` to grab the MCP SDK.
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.
