PayRam Crypto Card Payment Gateway

officiel

Passerelle de paiement auto-hébergée pour agents, openclaw, hermes et plus

GitHub

158

Que pouvez-vous faire avec PayRam Crypto Card Payment Gateway MCP ?

Planifier une installation personnalisée — Demandez un plan de déploiement PayRam étape par étape avec des transferts humains via payram_setup_plan.
Diagnostiquer la santé du serveur — Exécutez une vérification sans identifiants de toute URL PayRam pour identifier les problèmes et les solutions avec payram_doctor.
Résoudre les erreurs — Collez une erreur ou un symptôme pour obtenir les causes connues, les confirmations et les étapes suivantes via payram_troubleshoot.
Obtenir des runbooks d’administration — Demandez des tâches administratives étape par étape comme SSL, sauvegardes ou changements de domaine depuis payram_runbook.
Exécuter les opérations de jour 2 — Faites exécuter à l’agent des recettes API pour les vérifications quotidiennes, la synchronisation des nœuds ou les liens de paiement via payram_ops_playbook.
Générer du code d’intégration — Demandez des extraits de paiement, de versement ou de webhook prêts à copier-coller pour des frameworks comme Express ou Next.js.

Documentation

Serveur MCP PayRam — Paiements Crypto Auto-hébergés pour Agents IA

Paiements crypto et stablecoins auto-hébergés : aucun blocage de compte, aucun gel de fonds, les données clients ne sont jamais partagées. Votre agent IA peut planifier, installer et exploiter le serveur via MCP. Point de terminaison hébergé : https://mcp.payram.com/mcp · Site web · Documentation · Agentic · OpenClaw

Un serveur MCP (Model Context Protocol) qui permet à tout agent IA compatible MCP — OpenClaw, Hermes, Claude, Cursor, GitHub Copilot, et autres — de déployer, intégrer et exploiter une pile de paiement crypto PayRam auto-hébergée.

Commencez ici : quatre outils ouvrent le catalogue :

Outil	Ce qu'il fait
`payram_setup_plan`	Un plan d'installation personnalisé, avec chaque étape nécessitant une intervention humaine clairement marquée
`payram_doctor`	Une vérification publique, sans identifiants, d'un serveur PayRam par URL
`payram_troubleshoot`	Décrivez un problème ou collez une erreur : causes connues, comment confirmer, la correction, et l'outil suivant
`payram_runbook`	Tâches d'administration : URL du site, domaine, SSL, pare-feu, mise à niveau, sauvegarde, chaînes, Smart Bridge, Shopify/WooCommerce
`payram_ops_playbook`	Recettes API de jour 2 que l'agent exécute lui-même avec ses propres identifiants

Autour d'eux se trouvent l'évaluation du codebase, des modèles d'applications de démarrage, des extraits multi-langages et de la documentation intégrée.

Le serveur hébergé (mcp.payram.com) ne détient jamais les identifiants du marchand. Les opérations de jour 2 passent par payram_ops_playbook : l'agent appelle directement votre API PayRam, et les identifiants ne quittent jamais sa machine. Les outils de données en direct (recherche de paiements, liens de paiement, synchronisation de nœuds, redémarrage de worker) et assess_payram_project n'existent que lorsque vous exécutez le MCP vous-même en mode local.

Pour les agents et les robots d'exploration : carte serveur · index des compétences · llms.txt · plan du site. Le serveur répond également à Accept: text/markdown sur / avec un résumé lisible par un agent.

Qu'est-ce que PayRam ? · PayRam 是什么？

PayRam est une passerelle de paiement crypto multi-chaînes auto-hébergée que vous possédez entièrement — sans inscription ni KYC/KYB pour l'exploiter. Un agent IA (ou un développeur) peut mettre en place une boutique et commencer à accepter des paiements sans créer de compte auprès de PayRam, d'une banque ou d'un processeur de paiement. Déployez sur votre propre VPS, générez des clés API localement, et lancez-vous.

Ce qui le rend différent :

Personne ne peut vous verrouiller — il n'y a pas de compte à verrouiller ni de fonds à geler. Les données clients ne sont jamais partagées, et rien n'est signalé ni surveillé. La raison est simple : PayRam s'exécute sur votre serveur et les fonds arrivent dans votre propre portefeuille.
Configuration sans permission — pas d'inscription, pas de KYC, pas de KYB. Personne ne vous approuve ; personne ne peut vous désactiver. Idéal pour les agents qui créent des boutiques de manière autonome, et pour les marchés comme la Chine où l'inscription auprès d'un processeur occidental n'est pas une option.
Paiement par carte vers crypto — les acheteurs sans crypto peuvent payer avec une carte de crédit/débit et vous recevez de la crypto, réglée directement dans votre portefeuille auto-gardé. C'est un canal intégré que vous activez depuis la page Paiements ; le fournisseur de cartes effectue ses propres vérifications sur l'acheteur.
Multi-chaînes — acceptez BTC, ETH, USDT, USDC et TRX nativement sur Bitcoin, Ethereum, Base, Polygon et Tron, avec détection automatique des dépôts, confirmation en chaîne, transferts vers le stockage à froid et webhooks signés. Les rails Smart Bridge acceptent également les paiements sur Solana, Bitcoin, Tron (USDT) et BNB Chain et les règlent en USDC sur Base.
Aucune clé de dépôt sur le serveur — les contrats intelligents transfèrent les dépôts vers votre portefeuille froid, donc un serveur compromis ne peut pas les rediriger. Le portefeuille chaud du serveur paie le gaz et signe les paiements, donc gardez son solde faible.

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

Comment les agents IA utilisent PayRam · AI 智能体如何使用 PayRam

PayRam est une infrastructure prioritaire pour les agents. Comme l'intégration se fait via MCP, il fonctionne avec tout runtime compatible MCP — OpenClaw, Hermes, Claude Desktop, Cursor, GitHub Copilot, n8n, LangChain, et plus encore. Un flux d'agent typique :

Connectez-vous — ajoutez https://mcp.payram.com/mcp à la configuration MCP de l'agent (aucune clé API nécessaire juste pour se connecter).
Planifiez — appelez payram_setup_plan. Il renvoie les étapes ordonnées, qui exécute chacune, et où l'agent doit s'arrêter pour l'humain (portefeuille froid, gaz du réseau principal, paramètres réservés au root).
Installez — sur le VPS, dans un terminal interactif, une fois, exécutez bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet (ou --mainnet ; l'installateur par défaut est le réseau principal, donc passez toujours le drapeau). Ne le pipez jamais dans bash.
Passez le relais — l'humain revendique immédiatement le compte root et enregistre Paramètres → URL du site depuis le domaine public ; jusque-là, les liens de paiement pointent vers http://localhost.
Vérifiez — payram_doctor avec l'URL publique (aucun identifiant requis).
Acceptez les paiements — insérez le code d'intégration spécifique au framework depuis les outils d'extraits. Les webhooks sont signés (X-Payram-Signature, HMAC-SHA256 du corps brut avec la clé API du projet).
Exploitez — payram_ops_playbook (daily_check, payment_options, node_sync, unswept_funds, create_payment_link, …) donne à l'agent les appels API exacts à exécuter avec ses propres identifiants. payram_runbook couvre les modifications administratives.

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

Pour la procédure pas à pas spécifique à OpenClaw (inscription, testnet sur Base Sepolia, modèles de commerce par chat pour WhatsApp/Telegram/Discord), voir la compétence payram-openclaw-integration et 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 服务器从不保存商户凭证。

Si GitHub est difficile d'accès depuis votre réseau, vous pouvez mirroiter ce dépôt vers un autre hébergeur Git (git clone --mirror https://github.com/PayRam/payram-mcp.git). 如果你的网络难以访问 GitHub，可以把本仓库镜像到其他 Git 托管平台（git clone --mirror https://github.com/PayRam/payram-mcp.git）。

Compétences de l'agent

Porte d'entrée de l'agent : https://mcp.payram.com/SKILL.md — une compétence racine unique qui décrit PayRam et oriente les agents vers les quatre outils de démarrage. Également disponible : /llms.txt.

Ce dépôt comprend 19 compétences d'agent pour les assistants de codage IA. Installez-les via skills.sh :

Installation individuelle

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

Compétence	Objectif
`payram-setup`	Plan d'installation et configuration du serveur : exigences, installateur, URL du site, portefeuilles, premier lien de paiement
`payram-agent-onboarding`	Installation sans tête par un agent : commandes CLI de l'agent, variables d'environnement, relais humains
`payram-auth`	Flux d'authentification JWT — connexion, actualisation du jeton, déconnexion, détails de la plateforme externe
`payram-analytics`	Recherche de paiements, volume, soldes et historique de transfert via les API REST directes (JWT)
`payram-crypto-payments`	Aperçu de l'architecture, pourquoi PayRam, outils MCP
`payram-payment-integration`	Guide d'intégration de paiement de démarrage rapide
`payram-self-hosted-payment-gateway`	Déployez et possédez votre infrastructure de paiement
`payram-checkout-integration`	Flux de paiement avec SDK + HTTP pour 6 frameworks
`payram-widget-integration`	Bouton « Ajouter du crédit » sécurisé (point de terminaison backend, jamais une clé API publique) + gestionnaires de webhooks signés
`payram-webhook-integration`	Gestionnaires de webhooks signés (HMAC) pour Express, Next.js, FastAPI, Gin, Laravel, Spring Boot
`payram-stablecoin-payments`	Acceptation USDT/USDC sur les chaînes EVM et Tron
`payram-bitcoin-payments`	BTC avec dérivation de portefeuille HD et signature mobile
`payram-payouts`	Envoyez des paiements crypto et gérez les programmes de parrainage
`payram-no-kyc-crypto-payments`	Acceptation de paiement sans KYC, sans inscription, sans permission
`payram-openclaw-integration`	Intégrez PayRam dans OpenClaw / les runtimes d'agents — enregistrement MCP, testnet, commerce par chat
`compare-crypto-payments`	Comparez les passerelles : Stripe, BitPay, Coinbase, NOWPayments, BTCPay, PayRam, x402
`payram-agent-journey`	Carte de démarrage : installation (marchand ou opérateur) → portefeuilles → gaz/transfert → intégration → test
`payram-topup-wallet-integration`	Applications existantes : créditez de la crypto sur un solde utilisateur, débitez des factures — registre + flux
`payram-testnet-testing`	Payez votre propre lien de paiement sur testnet de bout en bout avant le réseau principal

Objectifs du projet

Accélérer l'intégration avec un plan de configuration personnalisé, des runbooks, des modèles d'environnement et des playbooks par framework.
Opérer sans détenir d'identifiants : le serveur hébergé vérifie un PayRam par URL (payram_doctor) et donne aux agents des recettes API exactes (payram_ops_playbook) à exécuter avec leurs propres identifiants.
Moderniser les dépôts existants via l'outil d'évaluation de projet (mode local), qui analyse les manifestes de paquets et les fichiers .env, puis recommande les extraits d'intégration appropriés.
Fournir des extraits copier-coller couvrant les paiements, les versements, les parrainages, les webhooks et les backends multi-langages (Express, Next.js, FastAPI, Laravel, Gin, Spring Boot, etc.).
Garder la documentation locale pour que Copilot puisse expliquer les concepts PayRam, les flux et les tableaux de bord de parrainage sans quitter l'éditeur.
Valider la connectivité avec des sondes en lecture seule qui ne créent jamais de paiements (payram_doctor, test_payram_connection).

Démarrage rapide

La plupart des agents n'ont besoin que du point de terminaison hébergé, https://mcp.payram.com/mcp (voir Connexion depuis votre client MCP). Pour exécuter le serveur vous-même :

Installer les dépendances
```
yarn install
```
Configurer l'environnement (uniquement nécessaire pour les outils de données en mode local)
- Copier .env.example vers .env.
- Définir PAYRAM_BASE_URL sur votre URL PayRam, la même origine que le tableau de bord (par exemple https://pay.example.com).
- Définir PAYRAM_API_KEY, ainsi que les variables JWT pour les outils de données. Voir Mode local.

Exécuter le serveur

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

Ajouter le serveur MCP à votre client : voir Se connecter depuis votre client MCP. L'URL en mode local est http://localhost:3333/mcp.
Vérification de l'état de santé
```
curl http://localhost:3333/healthz
```

Astuce : Lorsque vous dites à Copilot « test payram », il exécute automatiquement la liste de contrôle de préparation, s'assure que .env existe, puis appelle test_payram_connection avec vos véritables identifiants. Ce comportement est défini par l'invite d'automatisation Copilot — aucune invite manuelle n'est requise.

Se connecter depuis votre client MCP

Point de terminaison : https://mcp.payram.com/mcp (HTTP Streamable, JSON-RPC sur POST). Il n'y a pas de point de terminaison SSE, et /mcp/sse renvoie 410. Aucun en-tête d'authentification : le serveur hébergé ne détient jamais les identifiants marchands, donc les vôtres restent sur votre machine et ne sont jamais envoyés dans le chat.

Client	Où	Paramètres
VS Code (Copilot Chat)	Paramètres → Copilot: Model Context Protocol → Ajouter un serveur HTTP	Nom `payram`, URL ci-dessus, en-têtes vides
Cursor	Paramètres → Serveurs MCP → Ajouter → HTTP	Nom `payram`, URL ci-dessus
Claude Desktop / Code	Paramètres → Serveurs MCP → Ajouter un serveur HTTP	Nom `payram`, URL ci-dessus
Tout client MCP	Enregistrer un point de terminaison HTTP	URL ci-dessus, aucun en-tête

Vérification : la liste des outils doit commencer par payram_setup_plan, payram_doctor, payram_troubleshoot, payram_runbook et payram_ops_playbook, suivis de scaffold_payram_app et des outils d'extraits generate_*. Essayez ensuite : « planifier une installation PayRam sur pay.example.com », « vérifier https://pay.example.com », « générer une route FastAPI create-payment », « donnez-moi un gestionnaire de webhook Next.js ».

Invites : setup-payram, setup-payram-agent, integrate-payment, troubleshoot-payment, daily-ops. Ressources : payram://docs/setup-guide, payram://docs/api-reference, et les modèles payram://ops/playbook/{task} et payram://runbooks/{task}.

Invite d'automatisation Copilot

Collez ceci une fois dans un espace de travail vierge pour que « test payram » exécute automatiquement le flux complet de préparation :

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.

Mode local

Exécutez le MCP à côté de votre propre PayRam pour obtenir les outils de données en direct :

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

Mode : PAYRAM_MCP_MODE=local sélectionne le mode local. C'est également la valeur par défaut chaque fois que le serveur ne fonctionne pas sur Vercel. PAYRAM_MCP_MODE=hosted ne lit jamais les identifiants.
Liaison : le mode local se lie à 127.0.0.1 par défaut (port PORT, défaut 3333).
Liaisons non-loopback : définissez HOST (par exemple HOST=0.0.0.0), puis :
- Définissez MCP_ALLOWED_HOSTS (noms d'hôtes séparés par des virgules acceptés dans l'en-tête Host).
- Définissez MCP_SERVER_TOKEN ; les clients envoient alors Authorization: Bearer <token>.
- Si les identifiants PAYRAM_* sont définis, le serveur refuse de démarrer sur un HOST non-loopback sans MCP_SERVER_TOKEN. Préférez le loopback avec un tunnel SSH.
Identifiants : les outils de données lisent PAYRAM_* depuis l'environnement (ou .env) :
- PAYRAM_BASE_URL
- PAYRAM_API_KEY (liens de paiement)
- PAYRAM_ACCESS_TOKEN / PAYRAM_REFRESH_TOKEN (JWT, outils de données)
- PAYRAM_EXTERNAL_PLATFORM_ID (projet par défaut facultatif)

Exemple de configuration client pour un serveur local (mode local uniquement) :

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

Identifiants : quelle clé pour quoi

PayRam possède deux identifiants — les agents calent lorsqu'ils les confondent :

Identifiant	Ressemble à	Utilisé pour	Comment un agent l'obtient (sans tableau de bord)
Clé API marchand (`PAYRAM_API_KEY`, en-tête `API-Key`)	clé par projet	`POST /api/v1/payment` (liens de paiement), paiements marchands, tous les appels serveur-à-serveur marchands, et elle signe les webhooks (`X-Payram-Signature`)	`bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) ensure-api-key` — réutilise ou crée la clé de projet via `POST /api/v1/external-platform/{id}/api-key` et l'enregistre dans `~/.payraminfo/merchant-api-key.env`
JWT (`Authorization: Bearer`)	jeton d'accès+actualisation depuis la connexion	API admin/configuration (projets, portefeuilles, analyses) — recettes `payram_ops_playbook` et outils de données en mode local	`bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) signin` (env `PAYRAM_EMAIL`/`PAYRAM_PASSWORD`) ; enregistré dans `~/.payraminfo/headless-tokens.env`

Le flux de configuration en une étape (bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet) produit les deux automatiquement et affiche où ils se trouvent. L'API est de même origine que le tableau de bord, sur le port 80/443 (https://<your-domain>/api/v1/..., ou http://localhost sur le serveur, jamais :8080). La clé API peut créer des paiements, alors gardez-la côté serveur et ne la mettez jamais dans le code navigateur ou le chat. Utilisez la tâche payram_ops_playbook connect pour configurer les deux pour des appels API directs.

Catalogue d'outils

Catégorie	Outil	Objectif
Commencer ici – Installation	`payram_setup_plan`	Plan d'installation personnalisé et ordonné (préparation → installation → revendication du compte root + URL du site → portefeuilles + Smart Bridge → clé API + premier lien → durcissement → intégration) avec étapes pour agent vs humain et points d'arrêt obligatoires.
Commencer ici – Diagnostics	`payram_doctor`, `payram_troubleshoot`	`payram_doctor` : vérification publique par étapes, sans identifiants, basée sur l'URL (accessibilité → santé → TLS → version → workers) avec causes probables classées + corrections exactes. Vérification facultative de validité de clé API qui ne crée rien. Exécutez ceci EN PREMIER en cas d'échec. `payram_troubleshoot` : faites correspondre un symptôme ou une erreur collée à des causes et corrections connues.
Commencer ici – Administration	`payram_runbook`	Tâches administratives pas à pas avec étapes humaines : `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`.
Commencer ici – Opérations	`payram_ops_playbook`	Recettes API directes que l'agent exécute lui-même : `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`.
Connectivité	`test_payram_connection`	Vérification en lecture seule de l'accessibilité/santé plus validation facultative de clé API. Ne crée jamais de paiements.
Configuration	`generate_env_template`, `generate_setup_checklist`, `suggest_file_structure`, `get_agent_setup_flow`, `onboard_agent_setup`	Fournit le boilerplate d'environnement, les listes de contrôle marchand, les structures de projet recommandées et le guide d'intégration pour agent sans interface.
Contexte / Documentation	`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.	Fournit des connaissances Markdown en ligne issues de `docs/` afin que Copilot puisse répondre aux questions conceptuelles. Certains outils ajoutent automatiquement des rappels « dites `test payram` ».
Intégration – Paiements	`generate_payment_sdk_snippet`, `generate_payment_http_snippet`, `generate_payment_status_snippet`, `generate_payment_route_snippet`	Génère du code SDK, HTTP brut ou des routes Express/Next.js pour les flux de création et de statut.
Intégration – Paiements sortants	`generate_payout_sdk_snippet`, `generate_payout_recipient_flow_snippet`, `generate_payout_status_snippet`	Paiement sortant direct (sans OTP), flux en 3 étapes pour bénéficiaire enregistré (créer le bénéficiaire → valider l'OTP → payer) et interrogation du statut.
Intégration – Parrainage	`generate_referral_sdk_snippet`, `generate_referral_validation_snippet`, `generate_referral_status_snippet`, `generate_referral_route_snippet`	Couvre l'authentification du parrainage, la liaison, la validation, le statut et les routes express/next.
Intégration – Webhooks	`generate_webhook_handler`, `generate_webhook_event_router`, `generate_mock_webhook_event`	Produit des gestionnaires pour Express/Next/FastAPI/Gin/Laravel/Spring Boot, des routeurs de fan-out et des testeurs de webhooks en cURL/Python/Go/PHP/Java.
Intégration – Paiements multi-langages	`snippet_*` famille (`snippet_express_payment_route`, `snippet_nextjs_payment_route`, `snippet_fastapi_payment_route`, `snippet_laravel_payment_route`, `snippet_go_payment_handler`, `snippet_spring_payment_controller`)	Gestionnaires de routes préconstruits pour Express, Next.js App Router, FastAPI, Gin, Laravel et Spring Boot.
Intégration – Recharge de portefeuille	`generate_topup_integration_snippet`	Pour les applications EXISTANTES : schéma de grand livre + webhook de crédit cumulatif + règlement de facture atomique, afin que les paiements crypto en trop/en moins/en retard/dupliqués deviennent des états de solde plutôt que des exceptions de paiement. S'associe à la compétence `payram-topup-wallet-integration`.
Évaluation de projet (mode local)	`assess_payram_project`	Analyse `package.json`, `requirements.txt`, `composer.json`, `go.mod`, `pom.xml`, `.env`, etc. Signale les frameworks détectés, l'état de l'environnement, les dépendances PayRam et les prochaines étapes priorisées avec suggestions d'outils.
Génération de structure	`scaffold_payram_app`	Génère des applications de démarrage complètes (Express, Next.js, FastAPI, Laravel, Gin, Spring Boot) avec paiements, paiements sortants, webhooks et une console navigateur. Placez les points de terminaison de paiement sortant derrière votre propre authentification admin avant le déploiement.
Données en direct (lecture seule, mode local)	`list_platforms`, `search_payments`, `lookup_payment`, `get_payment_summary`, `get_daily_volume`, `get_unswept_balances`, `list_currencies`, `list_recipients`	Interroge les données PayRam en direct. `list_currencies` est public (sans clé) ; les autres utilisent les jetons JWT dans `.env`. `list_recipients` s'associe au flux de bénéficiaire de paiement sortant.
Opérations en direct (mode local)	`create_payment_link` (écriture), `check_payment_readiness`, `check_node_sync`, `restart_payram_worker` (écriture)	`create_payment_link` crée un véritable lien de paiement via `API-Key`. `check_payment_readiness` signale les écarts par chaîne (portefeuille / devise / écouteur manquants) pour accepter les paiements. `check_node_sync` signale la santé des workers d'écoute + nœuds RPC et l'obsolescence des blocs. Sur le serveur hébergé, utilisez les tâches `payram_ops_playbook` correspondantes.

Les enregistrements d'outils se trouvent dans src/tools/index.ts ; les implémentations individuelles se trouvent dans src/tools/** avec des modèles spécifiques au langage sous les dossiers templates/.

Flux de travail guidés

0. Installer PayRam

Demandez : « Configurer PayRam sur pay.example.com » (ou utilisez les invites setup-payram / setup-payram-agent).
L'assistant appelle payram_setup_plan et parcourt les phases, en s'arrêtant à chaque étape humaine (compte root, URL du site, portefeuille froid, gaz mainnet).
Il termine avec payram_doctor, les sauvegardes (payram_runbook backup) et la vérification quotidienne (payram_ops_playbook daily_check).

1. Évaluer et adapter un projet existant

Demandez à Copilot : « Pouvez-vous intégrer PayRam dans ce projet ? »
L'assistant exécute assess_payram_project (mode local), en examinant les manifestes de dépendances et .env.
Suivez les étapes recommandées (installez payram, demandez des extraits de routes Express/FastAPI/Spring, ajoutez des webhooks, etc.).
Utilisez test_payram_connection une fois que les identifiants sont réels pour garantir que le backend peut atteindre votre serveur auto-hébergé.

2. Créer un Exemple Neuf

« Créez une démo Express PayRam » → scaffold_payram_app construit un projet Express avec paiements, versements, webhooks et une console UI.
Déposez les fichiers générés dans un dépôt vide ou comparez-les à votre répertoire existant pour un câblage de référence.

3. Exécuter le Flux de Préparation « Test PayRam »

Dites « test payram ». L'assistant automatiquement :
- Appelle prepare_payram_test pour partager la liste de contrôle de préparation.
- S'assure que .env existe (en le créant s'il manque) en utilisant generate_env_template.
- Attend de vrais identifiants avant d'invoquer test_payram_connection.
Examinez le résultat JSON structuré pour confirmer que l'API PayRam est accessible.

4. Câbler Paiements, Versements, Parrainages et Webhooks

Paiements : generate_payment_sdk_snippet (SDK JS) ou generate_payment_http_snippet (Python/Go/PHP/Java).
Routes multi-langues : snippet_nextjs_payment_route, snippet_fastapi_payment_route, etc.
Versements : generate_payout_sdk_snippet pour créer + generate_payout_status_snippet pour interroger.
Parrainages : generate_referral_route_snippet, generate_referral_validation_snippet.
Webhooks : generate_webhook_handler plus generate_webhook_event_router pour la diffusion + generate_mock_webhook_event pour tester chaque statut.

Développement

Commande	Description
`yarn dev`	Exécute le serveur MCP avec rechargement à chaud via `tsx`.
`yarn build`	Compile TypeScript vers `dist/`.
`yarn lint` / `yarn format`	ESLint + Prettier sur tout le dépôt.
`yarn test`	Exécute la suite Vitest (`tests/`).
`make precommit-test`	Exécute format → lint → test → build séquentiellement.

Le projet est TypeScript-first (ESM). La configuration Prettier se trouve dans .prettierrc.json ; ESLint est configuré via eslint.config.mjs. Des contributions fluides suivent l'assistant de commit dans Makefile → make commit.

Dépannage

Commencez par payram_doctor — un appel en lecture seule qui parcourt accessibilité → santé → TLS → version → workers et renvoie des causes classées avec des correctifs exacts. Pour des vérifications plus approfondies, suivez payram_ops_playbook (stuck_payment, node_sync, webhooks, logs).

Copilot n'appelle pas le bon outil : Vérifiez que l'invite d'automatisation Copilot est installée et que votre client MCP a chargé le serveur. Relancez « test payram » ou « évaluez mon projet » pour déclencher l'automatisation attendue.
test_payram_connection échoue avec 401 : Confirmez que la clé est une clé API de projet active (envoyée comme en-tête API-Key, pas Authorization).
Un outil de données indique que les identifiants sont indisponibles : le serveur hébergé ne détient jamais d'identifiants marchands. Utilisez la tâche payram_ops_playbook correspondante, ou exécutez le MCP en mode local.
Les liens de paiement affichent http://localhost : l'humain doit enregistrer Paramètres → URL du site depuis le domaine public (tâche payram_runbook set_site_url).
L'outil de documentation indique qu'un fichier manque : Vérifiez que votre arborescence locale docs/payram-docs-live/ contient le markdown demandé (get_payram_doc_by_id rejette les chemins avec ..).
Le serveur ne démarre pas : Assurez-vous d'avoir Node 20+ et exécutez yarn install. En mode local avec un HOST non-loopback et des identifiants PAYRAM_* définis, le serveur refuse de démarrer tant que MCP_SERVER_TOKEN n'est pas défini (voir Mode local).

Pour tout autre problème, inspectez les journaux structurés émis depuis src/utils/logger.ts (définissez LOG_LEVEL=debug) et ouvrez un problème/PR avec les détails de reproduction.