PayRam Crypto Card Payment Gateway

PayRam MCP Server — Selbst gehostete Krypto-Zahlungen für KI-Agenten

Selbst gehostete Krypto- und Stablecoin-Zahlungen: kein Account-Lock, kein Einfrieren von Geldern, Kundendaten werden niemals geteilt. Ihr KI-Agent kann über MCP planen, installieren und betreiben. Gehosteter Endpunkt: https://mcp.payram.com/mcp · Website · Dokumentation · Agentic · OpenClaw

Ein MCP (Model Context Protocol) Server, der es jedem MCP-fähigen KI-Agenten — OpenClaw, Hermes, Claude, Cursor, GitHub Copilot und anderen — ermöglicht, einen selbst gehosteten PayRam Krypto-Zahlungs-Stack bereitzustellen, zu integrieren und zu betreiben.

Hier starten: Vier Tools führen den Katalog an:

Tool	Funktion
payram_setup_plan	Ein personalisierter Installationsplan, mit allen menschlichen Übergaben markiert
payram_doctor	Ein öffentlicher, ohne Anmeldedaten durchführbarer Check eines PayRam-Servers per URL
payram_troubleshoot	Problem beschreiben oder Fehler einfügen: bekannte Ursachen, Bestätigungsmethode, Lösung und das nächste Tool
payram_runbook	Admin-Aufgaben: Site-URL, Domain, SSL, Firewall, Upgrade, Backup, Chains, Smart Bridge, Shopify/WooCommerce
payram_ops_playbook	Day-2-API-Rezepte, die der Agent selbst mit seinen eigenen Anmeldedaten ausführt

Darum herum gibt es Codebase-Bewertung, Starter-App-Gerüste, mehrsprachige Snippets und Inline-Dokumentation.

Der gehostete Server (mcp.payram.com) speichert niemals Händler-Anmeldedaten. Day-2-Operationen laufen über payram_ops_playbook: Der Agent ruft Ihre PayRam-API direkt auf, und die Anmeldedaten verlassen niemals seine Maschine. Die Live-Daten-Tools (Zahlungssuche, Zahlungslinks, Node-Sync, Worker-Neustart) und assess_payram_project existieren nur, wenn Sie das MCP selbst im lokalen Modus ausführen.

Für Agenten & Crawler: Server-Karte · Skills-Index · llms.txt · Sitemap. Der Server beantwortet auch Accept: text/markdown auf / mit einer für Agenten lesbaren Zusammenfassung.

---

Was ist PayRam? · PayRam 是什么？

PayRam ist ein selbst gehostetes, Multi-Chain-Krypto-Zahlungsgateway, das Ihnen vollständig gehört — ohne Anmeldung und ohne KYC/KYB, um es zu betreiben. Ein KI-Agent (oder ein Entwickler) kann einen Shop aufbauen und Zahlungen annehmen, ohne ein Konto bei PayRam, einer Bank oder einem Zahlungsabwickler zu registrieren. Stellen Sie es auf Ihrem eigenen VPS bereit, generieren Sie API-Schlüssel lokal, gehen Sie live.

Was es anders macht:

• Niemand kann Sie aussperren — es gibt kein Konto, das gesperrt werden kann, und keine Gelder, die eingefroren werden können. Kundendaten werden niemals geteilt, und nichts wird gemeldet oder überwacht. Der Grund ist einfach: PayRam läuft auf Ihrem Server und Gelder landen in Ihrer eigenen Wallet.
• Genehmigungsfreie Einrichtung — keine Anmeldung, kein KYC, kein KYB. Niemand genehmigt Sie; niemand kann Sie abschalten. Ideal für Agenten, die autonom Shops aufbauen, und für Märkte wie China, wo die Registrierung bei einem westlichen Abwickler keine Option ist.
• Karte-zu-Krypto-Checkout — Käufer ohne Krypto können mit einer Kredit-/Debitkarte zahlen und Sie erhalten Krypto, direkt auf Ihre selbst verwahrte Wallet abgerechnet. Es ist ein integrierter Kanal, den Sie auf der Zahlungsseite aktivieren; der Kartenanbieter führt seine eigenen Prüfungen des Käufers durch.
• Multi-Chain — Akzeptieren Sie BTC, ETH, USDT, USDC und TRX nativ über Bitcoin, Ethereum, Base, Polygon und Tron, mit automatischer Einzahlungserkennung, On-Chain-Bestätigung, Transfers in den Cold Storage und signierten Webhooks. Smart Bridge-Schienen akzeptieren auch Zahlungen auf Solana, Bitcoin, Tron (USDT) und BNB Chain und rechnen sie als USDC auf Base ab.
• Keine Einzahlungsschlüssel auf dem Server — Smart Contracts transferieren Einzahlungen in Ihre Cold Wallet, sodass ein kompromittierter Server sie nicht umleiten kann. Die Hot Wallet des Servers bezahlt Gas und signiert Auszahlungen. Halten Sie daher ihren Saldo klein.

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 并签署出款，请只保留少量余额。

---

Wie KI-Agenten PayRam nutzen · AI 智能体如何使用 PayRam

PayRam ist Agenten-zuerst-Infrastruktur (agent-first). Da die Integration über MCP erfolgt, funktioniert es mit jeder MCP-fähigen Laufzeitumgebung — OpenClaw, Hermes, Claude Desktop, Cursor, GitHub Copilot, n8n, LangChain und mehr. Ein typischer Agenten-Ablauf:

1. Verbinden — fügen Sie https://mcp.payram.com/mcp zur MCP-Konfiguration des Agenten hinzu (kein API-Schlüssel nur zum Verbinden erforderlich).
2. Planen — rufen Sie payram_setup_plan auf. Es gibt die geordneten Schritte zurück, wer jeden ausführt und wo der Agent für den Menschen anhalten muss (Cold Wallet, Mainnet-Gas, Nur-Root-Einstellungen).
3. Installieren — auf dem VPS, in einem interaktiven Terminal, einmalig bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet ausführen (oder --mainnet; der Installer-Standard ist Mainnet, also immer das Flag übergeben). Niemals in bash pipen.
4. Übergabe — der Mensch beansprucht sofort das Root-Konto und speichert Einstellungen → Site-URL von der öffentlichen Domain; bis dahin zeigen Zahlungslinks auf http://localhost.
5. Prüfen — payram_doctor mit der öffentlichen URL (keine Anmeldedaten erforderlich).
6. Zahlungen annehmen — fügen Sie framework-spezifischen Integrationscode aus den Snippet-Tools ein. Webhooks sind signiert (X-Payram-Signature, HMAC-SHA256 des rohen Bodys mit dem Projekt-API-Schlüssel).
7. Betreiben — payram_ops_playbook (daily_check, payment_options, node_sync, unswept_funds, create_payment_link, …) gibt dem Agenten die genauen API-Aufrufe, die er mit seinen eigenen Anmeldedaten ausführen kann. payram_runbook deckt Admin-Änderungen ab.

{
  "mcpServers": {
    "payram": { "url": "https://mcp.payram.com/mcp" }
  }
}

Für die OpenClaw-spezifische Anleitung (Registrierung, Testnet auf Base Sepolia, Chat-Commerce-Muster für WhatsApp/Telegram/Discord) siehe die payram-openclaw-integration Skill und 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 服务器从不保存商户凭证。

Wenn GitHub aus Ihrem Netzwerk schwer erreichbar ist, können Sie dieses Repository auf einen anderen Git-Host spiegeln (git clone --mirror https://github.com/PayRam/payram-mcp.git). 如果你的网络难以访问 GitHub，可以把本仓库镜像到其他 Git 托管平台（git clone --mirror https://github.com/PayRam/payram-mcp.git）。

---

Inhaltsverzeichnis

• Was ist PayRam?
• Wie KI-Agenten PayRam nutzen
• Agent Skills
• Projektziele
• Schnellstart
• Von Ihrem MCP-Client verbinden
• Lokaler Modus
• Anmeldedaten
• Tool-Katalog
• Geführte Workflows
• Entwicklung
• Fehlerbehebung

---

Agent Skills

Agenten-Eingangstür: https://mcp.payram.com/SKILL.md — eine einzelne Root-Skill, die PayRam beschreibt und Agenten zu den vier Start-Hier-Tools führt. Ebenfalls bereitgestellt: /llms.txt.

Dieses Repository enthält 19 Agent Skills für KI-Codierungsassistenten. Installieren Sie sie über skills.sh:

Einzeln installieren

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	Zweck
payram-setup	Installationsplan und Server-Setup: Anforderungen, Installer, Site-URL, Wallets, erster Zahlungslink
payram-agent-onboarding	Headless-Installation durch einen Agenten: Agent-CLI-Befehle, Umgebungsvariablen, menschliche Übergaben
payram-auth	JWT-Authentifizierungsablauf — Anmeldung, Token-Aktualisierung, Abmeldung, Details zu externen Plattformen
payram-analytics	Zahlungssuche, Volumen, Salden und Sweep-Verlauf über direkte REST-APIs (JWT)
payram-crypto-payments	Architekturübersicht, warum PayRam, MCP-Tools
payram-payment-integration	Schnellstart-Zahlungsintegrationsleitfaden
payram-self-hosted-payment-gateway	Stellen Sie Ihre Zahlungsinfrastruktur bereit und besitzen Sie sie
payram-checkout-integration	Checkout-Ablauf mit SDK + HTTP für 6 Frameworks
payram-widget-integration	Sicherer „Guthaben hinzufügen"-Button (Backend-Endpunkt, niemals ein öffentlicher API-Schlüssel) + signierte Webhook-Handler
payram-webhook-integration	Signierte Webhook- (HMAC) Handler für Express, Next.js, FastAPI, Gin, Laravel, Spring Boot
payram-stablecoin-payments	USDT/USDC-Akzeptanz über EVM-Chains und Tron
payram-bitcoin-payments	BTC mit HD-Wallet-Ableitung und mobilem Signieren
payram-payouts	Krypto-Auszahlungen senden und Empfehlungsprogramme verwalten
payram-no-kyc-crypto-payments	Kein-KYC-, kein-Signup-, genehmigungsfreie Zahlungsakzeptanz
payram-openclaw-integration	PayRam in OpenClaw / Agenten-Laufzeitumgebungen integrieren — MCP-Register, Testnet, Chat-Commerce
compare-crypto-payments	Gateways vergleichen: Stripe, BitPay, Coinbase, NOWPayments, BTCPay, PayRam, x402
payram-agent-journey	Start-Hier-Karte: Installation (Händler oder Betreiber) → Wallets → Gas/Sweep → Integrieren → Testen
payram-topup-wallet-integration	Bestehende Apps: Krypto einem Benutzersaldo gutschreiben, Rechnungen davon abbuchen — Hauptbuch + Abläufe
payram-testnet-testing	Zahlen Sie Ihren eigenen Zahlungslink auf dem Testnet End-to-End, bevor Sie ins Mainnet gehen

---

Projektziele

• Onboarding beschleunigen mit einem personalisierten Setup-Plan, Runbooks, Env-Vorlagen und Framework-spezifischen Playbooks.
• Ohne das Halten von Anmeldedaten betreiben: Der gehostete Server prüft ein PayRam per URL (payram_doctor) und gibt Agenten exakte API-Rezepte (payram_ops_playbook), die sie mit ihren eigenen Anmeldedaten ausführen.
• Bestehende Repos nachrüsten über das Projektbewertungs-Tool (lokaler Modus), das Paketmanifeste und .env-Dateien scannt und dann die richtigen Integrations-Snippets empfiehlt.
• Copy/Paste-Snippets bereitstellen, die Zahlungen, Auszahlungen, Empfehlungen, Webhooks und mehrsprachige Backends abdecken (Express, Next.js, FastAPI, Laravel, Gin, Spring Boot usw.).
• Dokumentation lokal halten, damit Copilot PayRam-Konzepte, Abläufe und Empfehlungs-Dashboards erklären kann, ohne den Editor zu verlassen.
• Konnektivität validieren mit schreibgeschützten Sonden, die niemals Zahlungen erstellen (payram_doctor, test_payram_connection).

---

Schnellstart

Die meisten Agenten benötigen nur den gehosteten Endpunkt, https://mcp.payram.com/mcp (siehe Von Ihrem MCP-Client verbinden). Um den Server selbst auszuführen:

1. Abhängigkeiten installieren

   yarn install
   

2. Umgebung konfigurieren (nur für die Daten-Tools im lokalen Modus erforderlich)
   • Kopieren Sie .env.example nach .env.
   • Setzen Sie PAYRAM_BASE_URL auf Ihre PayRam-URL, dieselbe Origin wie das Dashboard (z. B. https://pay.example.com).
   • Setzen Sie PAYRAM_API_KEY sowie die JWT-Variablen für die Daten-Tools. Siehe Lokaler Modus.
3. Server ausführen

   yarn dev
   # Streamable HTTP on http://127.0.0.1:3333/mcp (local mode; there is no SSE transport)
   

4. MCP-Server zu Ihrem Client hinzufügen: siehe Verbindung von Ihrem MCP-Client. Die URL für den lokalen Modus lautet http://localhost:3333/mcp.
5. Health-Check

   curl http://localhost:3333/healthz
   

Tipp: Wenn Sie Copilot „test payram“ sagen, führt es automatisch die Bereitschafts-Checkliste aus, stellt sicher, dass .env existiert, und ruft erst dann test_payram_connection mit Ihren echten Anmeldedaten auf. Das Verhalten wird durch den Copilot-Automatisierungs-Prompt definiert – kein manuelles Prompting erforderlich.

---

Verbindung von Ihrem MCP-Client

Endpunkt: https://mcp.payram.com/mcp (Streamable HTTP, JSON-RPC über POST). Es gibt keinen SSE-Endpunkt, und /mcp/sse gibt 410 zurück. Keine Auth-Header: Der gehostete Server speichert niemals Händler-Anmeldedaten, sodass Ihre auf Ihrem Rechner bleiben und niemals in den Chat gelangen.

Client	Wo	Einstellungen
VS Code (Copilot Chat)	Einstellungen → Copilot: Model Context Protocol → HTTP-Server hinzufügen	Name payram, URL oben, Header leer
Cursor	Einstellungen → MCP-Server → Hinzufügen → HTTP	Name payram, URL oben
Claude Desktop / Code	Einstellungen → MCP-Server → HTTP-Server hinzufügen	Name payram, URL oben
Jeder MCP-Client	HTTP-Endpunkt registrieren	URL oben, keine Header

Überprüfung: Die Werkzeugliste sollte mit payram_setup_plan, payram_doctor, payram_troubleshoot, payram_runbook und payram_ops_playbook beginnen, gefolgt von scaffold_payram_app und den generate_*-Snippet-Werkzeugen. Versuchen Sie dann: „PayRam-Installation auf pay.example.com planen“, „https://pay.example.com prüfen“, „FastAPI-Create-Payment-Route generieren“, „Next.js-Webhook-Handler erstellen“.

Prompts: setup-payram, setup-payram-agent, integrate-payment, troubleshoot-payment, daily-ops. Ressourcen: payram://docs/setup-guide, payram://docs/api-reference und die Vorlagen payram://ops/playbook/{task} und payram://runbooks/{task}.

Copilot-Automatisierungs-Prompt

Fügen Sie dies einmal in einen neuen Arbeitsbereich ein, damit „test payram“ den vollständigen Bereitschaftsablauf automatisch ausführt:

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.

---

Lokaler Modus

Führen Sie den MCP neben Ihrem eigenen PayRam aus, um die Live-Daten-Tools zu erhalten:

• 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

PAYRAM_MCP_MODE=local yarn dev        # or: yarn build && PAYRAM_MCP_MODE=local yarn start

• Modus: PAYRAM_MCP_MODE=local wählt den lokalen Modus aus. Er ist auch die Standardeinstellung, wenn der Server nicht auf Vercel läuft. PAYRAM_MCP_MODE=hosted liest niemals Anmeldedaten.
• Bindung: Der lokale Modus bindet standardmäßig an 127.0.0.1 (Port PORT, Standard 3333).
• Nicht-Loopback-Bindungen: Setzen Sie HOST (z. B. HOST=0.0.0.0), dann:
  • Setzen Sie MCP_ALLOWED_HOSTS (durch Kommas getrennte Hostnamen, die im Host-Header akzeptiert werden).
  • Setzen Sie MCP_SERVER_TOKEN; Clients senden dann Authorization: Bearer <token>.
  • Wenn PAYRAM_*-Anmeldedaten gesetzt sind, weigert sich der Server, auf einem Nicht-Loopback-HOST ohne MCP_SERVER_TOKEN zu starten. Bevorzugen Sie Loopback plus einen SSH-Tunnel.
• Anmeldedaten: Die Daten-Tools lesen PAYRAM_* aus der Umgebung (oder .env):
  • PAYRAM_BASE_URL
  • PAYRAM_API_KEY (Zahlungslinks)
  • PAYRAM_ACCESS_TOKEN / PAYRAM_REFRESH_TOKEN (JWT, Daten-Tools)
  • PAYRAM_EXTERNAL_PLATFORM_ID (optionales Standardprojekt)

Beispiel-Client-Konfiguration für einen lokalen Server (nur lokaler Modus):

{
  "mcpServers": {
    "payram-local": { "url": "http://localhost:3333/mcp" }
  }
}

---

Anmeldedaten: Welcher Schlüssel wofür

PayRam hat zwei Anmeldedaten – Agenten bleiben stehen, wenn sie diese verwechseln:

Anmeldedaten	Sieht aus wie	Verwendet für	Wie ein Agent sie erhält (kein Dashboard erforderlich)
Händler-API-Schlüssel (PAYRAM_API_KEY, Header API-Key)	Schlüssel pro Projekt	POST /api/v1/payment (Zahlungslinks), Händler-Auszahlungen, alle Händler-Server-zu-Server-Aufrufe, und er signiert Webhooks (X-Payram-Signature)	bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) ensure-api-key – verwendet oder erstellt den Projektschlüssel über POST /api/v1/external-platform/{id}/api-key und speichert ihn in ~/.payraminfo/merchant-api-key.env
JWT (Authorization: Bearer)	Zugriffs-+Aktualisierungstoken von der Anmeldung	Admin-/Setup-APIs (Projekte, Wallets, Analysen) – payram_ops_playbook-Rezepte und die Daten-Tools im lokalen Modus	bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) signin (Umgebung PAYRAM_EMAIL/PAYRAM_PASSWORD); gespeichert in ~/.payraminfo/headless-tokens.env

Der einstufige Setup-Ablauf (bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet) erzeugt beide automatisch und gibt aus, wo sie sich befinden. Die API ist gleich-origin mit dem Dashboard, auf Port 80/443 (https://<your-domain>/api/v1/..., oder http://localhost auf dem Server, niemals :8080). Der API-Schlüssel kann Auszahlungen erstellen, bewahren Sie ihn daher serverseitig auf und setzen Sie ihn niemals in Browser-Code oder Chat ein. Verwenden Sie die payram_ops_playbook-Aufgabe connect, um beide für direkte API-Aufrufe einzurichten.

---

Werkzeugkatalog

Kategorie	Tool	Zweck
Start hier – Installation	payram_setup_plan	Personalisierter, geordneter Installationsplan (vorbereiten → installieren → Root + Site-URL beanspruchen → Wallets + Smart Bridge → API-Schlüssel + erster Link → härten → integrieren) mit Agenten- vs. menschlichen Schritten und harten Stopps.
Start hier – Diagnose	payram_doctor, payram_troubleshoot	payram_doctor: öffentlicher, anmeldefreier, gestufter Check per URL (Erreichbarkeit → Gesundheit → TLS → Version → Worker) mit priorisierten wahrscheinlichen Ursachen + exakten Fixes. Optionale API-Schlüssel-Validierung, die nichts erstellt. Führen Sie dies ZUERST aus, wenn etwas fehlschlägt. payram_troubleshoot: Symptom oder eingefügten Fehler bekannten Ursachen und Fixes zuordnen.
Start hier – Admin	payram_runbook	Schritt-für-Schritt-Admin-Aufgaben mit menschlichen 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 hier – Betrieb	payram_ops_playbook	Direkt-API-Rezepte, die der Agent selbst ausführt: 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.
Konnektivität	test_payram_connection	Schreibgeschützter Erreichbarkeits-/Gesundheitscheck plus optionale API-Schlüssel-Validierung. Erstellt niemals Zahlungen.
Einrichtung	generate_env_template, generate_setup_checklist, suggest_file_structure, get_agent_setup_flow, onboard_agent_setup	Liefert Env-Boilerplate, Händler-Checklisten, empfohlene Projektstrukturen und den Headless-Agent-Onboarding-Leitfaden.
Kontext / Doku	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, usw.	Stellen Inline-Markdown-Wissen aus docs/ bereit, damit Copilot konzeptionelle Fragen beantworten kann. Einige Tools hängen automatisch „sage test payram“-Erinnerungen an.
Integration – Zahlungen	generate_payment_sdk_snippet, generate_payment_http_snippet, generate_payment_status_snippet, generate_payment_route_snippet	Erzeugen SDK-, Roh-HTTP- oder Express/Next.js-Routencode für Erstellen- und Statusabläufe.
Integration – Auszahlungen	generate_payout_sdk_snippet, generate_payout_recipient_flow_snippet, generate_payout_status_snippet	Direkte (ohne OTP) Auszahlung, der 3-Schritte-Ablauf für gespeicherte Empfänger (Empfänger erstellen → OTP validieren → auszahlen) und Statusabfrage.
Integration – Empfehlungen	generate_referral_sdk_snippet, generate_referral_validation_snippet, generate_referral_status_snippet, generate_referral_route_snippet	Abdecken von Empfehlungs-Auth, Verknüpfung, Validierung, Status und Express/Next-Routen.
Integration – Webhooks	generate_webhook_handler, generate_webhook_event_router, generate_mock_webhook_event	Erzeugen von Handlern für Express/Next/FastAPI/Gin/Laravel/Spring Boot, Fan-out-Router und cURL/Python/Go/PHP/Java-Webhook-Testern.
Integration – Mehrsprachige Zahlungen	snippet_*-Familie (snippet_express_payment_route, snippet_nextjs_payment_route, snippet_fastapi_payment_route, snippet_laravel_payment_route, snippet_go_payment_handler, snippet_spring_payment_controller)	Vorgefertigte Routen-Handler für Express, Next.js App Router, FastAPI, Gin, Laravel und Spring Boot.
Integration – Wallet aufladen	generate_topup_integration_snippet	Für BESTEHENDE Apps: Ledger-Schema + kumulativer Gutschrift-Webhook + atomarer Rechnungsabschluss, sodass Über-/Unter-/Spät-/Doppel-Krypto-Zahlungen zu Kontoständen statt Zahlungsausnahmen werden. Passt zur payram-topup-wallet-integration-Fähigkeit.
Integration – Projektbewertung (lokaler Modus)	assess_payram_project	Scannt package.json, requirements.txt, composer.json, go.mod, pom.xml, .env, usw. Meldet erkannte Frameworks, Env-Status, PayRam-Abhängigkeiten und priorisierte nächste Schritte mit Tool-Vorschlägen.
Scaffolding	scaffold_payram_app	Erzeugt vollständige Starter-Apps (Express, Next.js, FastAPI, Laravel, Gin, Spring Boot) mit Zahlungen, Auszahlungen, Webhooks und einer Browser-Konsole. Setzen Sie die Auszahlungs-Endpunkte vor der Bereitstellung hinter Ihre eigene Admin-Auth.
Live-Daten (schreibgeschützt, lokaler Modus)	list_platforms, search_payments, lookup_payment, get_payment_summary, get_daily_volume, get_unswept_balances, list_currencies, list_recipients	Live-PayRam-Daten abfragen. list_currencies ist öffentlich (kein Schlüssel); der Rest verwendet die JWT-Tokens in .env. list_recipients passt zum Auszahlungs-Empfängerablauf.
Live-Betrieb (lokaler Modus)	create_payment_link (Schreiben), check_payment_readiness, check_node_sync, restart_payram_worker (Schreiben)	create_payment_link erstellt einen echten Checkout-Link über API-Key. check_payment_readiness meldet Lücken pro Chain (fehlende Wallet / Währung / Listener), um Zahlungen anzunehmen. check_node_sync meldet Listener-Worker- und RPC-Node-Gesundheit sowie Block-Veraltung. Auf dem gehosteten Server verwenden Sie die passenden payram_ops_playbook-Aufgaben.

Tool-Registrierungen befinden sich in src/tools/index.ts; einzelne Implementierungen liegen in src/tools/** mit sprachspezifischen Vorlagen unter templates/-Ordnern.

---

Geführte Workflows

0. PayRam installieren

1. Fragen Sie: „PayRam auf pay.example.com einrichten“ (oder verwenden Sie die setup-payram / setup-payram-agent-Prompts).
2. Der Assistent ruft payram_setup_plan auf und geht die Phasen durch, wobei er bei jedem menschlichen Schritt stoppt (Root-Konto, Site-URL, Cold Wallet, Mainnet-Gas).
3. Er endet mit payram_doctor, Backups (payram_runbook backup) und dem täglichen Check (payram_ops_playbook daily_check).

1. Bestehendes Projekt bewerten und nachrüsten

1. Fragen Sie Copilot: „Kannst du PayRam in dieses Projekt integrieren?“
2. Der Assistent führt assess_payram_project aus (lokaler Modus), prüft Abhängigkeitsmanifeste und .env.
3. Befolgen Sie die empfohlenen Schritte (installieren Sie payram, fordern Sie Express/FastAPI/Spring-Routenschnipsel an, fügen Sie Webhooks hinzu usw.).
4. Verwenden Sie test_payram_connection, sobald die Anmeldedaten echt sind, um sicherzustellen, dass das Backend Ihren selbst gehosteten Server erreichen kann.

2. Ein frisches Beispielprojekt erstellen

1. „Erstelle ein PayRam Express-Demo“ → scaffold_payram_app erstellt ein Express-Projekt mit Zahlungen, Auszahlungen, Webhooks und einer UI-Konsole.
2. Fügen Sie die generierten Dateien in ein leeres Repository ein oder vergleichen Sie sie mit Ihrem vorhandenen Verzeichnis für die Referenzverdrahtung.

3. Den „Test PayRam“-Bereitschaftsfluss ausführen

1. Sagen Sie „test payram“. Der Assistent führt automatisch Folgendes aus:
   • Ruft prepare_payram_test auf, um die Bereitschaftscheckliste zu teilen.
   • Stellt sicher, dass .env existiert (erstellt es, falls es fehlt) mit generate_env_template.
   • Wartet auf echte Anmeldedaten, bevor test_payram_connection aufgerufen wird.
2. Überprüfen Sie das strukturierte JSON-Ergebnis, um zu bestätigen, dass die PayRam-API erreichbar ist.

4. Zahlungen, Auszahlungen, Empfehlungen und Webhooks verdrahten

• Zahlungen: generate_payment_sdk_snippet (JS-SDK) oder generate_payment_http_snippet (Python/Go/PHP/Java).
• Mehrsprachige Routen: snippet_nextjs_payment_route, snippet_fastapi_payment_route usw.
• Auszahlungen: generate_payout_sdk_snippet zum Erstellen + generate_payout_status_snippet zum Abfragen.
• Empfehlungen: generate_referral_route_snippet, generate_referral_validation_snippet.
• Webhooks: generate_webhook_handler plus generate_webhook_event_router für Fan-out + generate_mock_webhook_event zum Testen jedes Status.

---

Entwicklung

Befehl	Beschreibung
yarn dev	Führen Sie den MCP-Server mit Hot Reload über tsx aus.
yarn build	Kompilieren Sie TypeScript zu dist/.
yarn lint / yarn format	ESLint + Prettier im gesamten Repository.
yarn test	Führt die Vitest-Suite aus (tests/).
make precommit-test	Führt format → lint → test → build sequenziell aus.

Das Projekt ist TypeScript-first (ESM). Die Prettier-Konfiguration befindet sich in .prettierrc.json; ESLint ist über eslint.config.mjs konfiguriert. Reibungslose Beiträge folgen dem Commit-Helfer in Makefile → make commit.

---

Fehlerbehebung

Beginnen Sie mit payram_doctor — ein einziger schreibgeschützter Aufruf, der Erreichbarkeit → Gesundheit → TLS → Version → Worker durchläuft und priorisierte Ursachen mit genauen Korrekturen zurückgibt. Für tiefere Prüfungen folgen Sie payram_ops_playbook (stuck_payment, node_sync, webhooks, logs).

• Copilot ruft nicht das richtige Tool auf: Überprüfen Sie, ob der Copilot-Automatisierungs-Prompt installiert ist und Ihr MCP-Client den Server geladen hat. Führen Sie erneut „test payram“ oder „bewerte mein Projekt“ aus, um die erwartete Automatisierung auszulösen.
• test_payram_connection schlägt mit 401 fehl: Bestätigen Sie, dass der Schlüssel ein aktiver Projekt-API-Schlüssel ist (gesendet als API-Key-Header, nicht Authorization).
• Ein Datentool sagt, Anmeldedaten sind nicht verfügbar: Der gehostete Server hält niemals Händleranmeldedaten. Verwenden Sie die passende payram_ops_playbook-Aufgabe oder führen Sie den MCP im lokalen Modus aus.
• Zahlungslinks zeigen http://localhost: Der Mensch muss Einstellungen → Site-URL von der öffentlichen Domäne speichern (payram_runbook-Aufgabe set_site_url).
• Das Dokumentationstool sagt, eine Datei fehlt: Überprüfen Sie, ob Ihr lokaler docs/payram-docs-live/-Baum das angeforderte Markdown enthält (get_payram_doc_by_id lehnt Pfade mit .. ab).
• Server startet nicht: Stellen Sie sicher, dass Node 20+ vorhanden ist, und führen Sie yarn install aus. Im lokalen Modus mit einer Nicht-Loopback-HOST und gesetzten PAYRAM_*-Anmeldedaten weigert sich der Server zu starten, bis MCP_SERVER_TOKEN gesetzt ist (siehe Lokaler Modus).

Für alles andere überprüfen Sie die strukturierten Protokolle, die von src/utils/logger.ts ausgegeben werden (setzen Sie LOG_LEVEL=debug) und eröffnen Sie ein Issue/PR mit Reproduktionsdetails.