PayRam Crypto Card Payment Gateway

Servidor MCP de PayRam — Pagos Cripto Autohospedados para Agentes de IA

Pagos cripto y con stablecoins autohospedados: sin bloqueo de cuenta, sin congelación de fondos, los datos de los clientes nunca se comparten. Tu agente de IA puede planificar, instalar y operar el sistema a través de MCP. Endpoint alojado: https://mcp.payram.com/mcp · Sitio web · Documentación · Agentic · OpenClaw

Un servidor MCP (Model Context Protocol) que permite a cualquier agente de IA compatible con MCP — OpenClaw, Hermes, Claude, Cursor, GitHub Copilot y otros — implementar, integrar y operar una pila de pagos cripto PayRam autohospedada.

Empieza aquí: cuatro herramientas lideran el catálogo:

Herramienta	Qué hace
payram_setup_plan	Un plan de instalación personalizado, con cada traspaso humano marcado
payram_doctor	Una comprobación pública, sin credenciales, de un servidor PayRam mediante URL
payram_troubleshoot	Describe un problema o pega un error: causas conocidas, cómo confirmarlo, la solución y la siguiente herramienta
payram_runbook	Tareas de administración: URL del sitio, dominio, SSL, firewall, actualización, copias de seguridad, cadenas, Smart Bridge, Shopify/WooCommerce
payram_ops_playbook	Recetas API de día 2 que el agente ejecuta por sí mismo con sus propias credenciales

A su alrededor se encuentran la evaluación del código base, plantillas de aplicaciones de inicio, fragmentos multilingües y documentación integrada.

El servidor alojado (mcp.payram.com) nunca guarda credenciales de comerciante. Las operaciones de día 2 se ejecutan a través de payram_ops_playbook: el agente llama directamente a tu API de PayRam y las credenciales nunca salen de su máquina. Las herramientas de datos en vivo (búsqueda de pagos, enlaces de pago, sincronización de nodos, reinicio de workers) y assess_payram_project solo existen cuando ejecutas el MCP tú mismo en modo local.

Para agentes y rastreadores: tarjeta de servidor · índice de habilidades · llms.txt · mapa del sitio. El servidor también responde a Accept: text/markdown en / con un resumen legible por agentes.

---

¿Qué es PayRam? · PayRam 是什么？

PayRam es una pasarela de pagos cripto multicadena autohospedada que posees por completo, sin registro ni KYC/KYB para operarla. Un agente de IA (o un desarrollador) puede montar una tienda y empezar a aceptar pagos sin registrarse en PayRam, en un banco ni en ningún procesador de pagos. Despliega en tu propio VPS, genera claves API localmente y sal a producción.

Qué lo hace diferente:

• Nadie puede bloquearte — no hay cuenta que bloquear ni fondos que congelar. Los datos de los clientes nunca se comparten y nada se reporta ni se monitoriza. La razón es simple: PayRam se ejecuta en tu servidor y los fondos llegan a tu propia cartera.
• Configuración sin permisos — sin registro, sin KYC, sin KYB. Nadie te aprueba; nadie puede desconectarte. Ideal para agentes que crean tiendas de forma autónoma y para mercados como China, donde registrarse con un procesador occidental no es una opción.
• Pago con tarjeta a cripto — los compradores sin cripto pueden pagar con tarjeta de crédito/débito y tú recibes cripto, liquidado directamente en tu cartera de autocustodia. Es un canal integrado que activas desde la página de Pagos; el proveedor de tarjetas realiza sus propias comprobaciones sobre el comprador.
• Multicadena — acepta BTC, ETH, USDT, USDC y TRX de forma nativa en Bitcoin, Ethereum, Base, Polygon y Tron, con detección automática de depósitos, confirmación en cadena, barridos a almacenamiento en frío y webhooks firmados. Los raíles de Smart Bridge también aceptan pagos en Solana, Bitcoin, Tron (USDT) y BNB Chain y los liquidan como USDC en Base.
• Sin claves de depósito en el servidor — los contratos inteligentes barren los depósitos a tu cartera fría, por lo que un servidor comprometido no puede redirigirlos. La cartera caliente del servidor paga el gas y firma los pagos, así que mantén su saldo pequeño.

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

---

Cómo usan PayRam los agentes de IA · AI 智能体如何使用 PayRam

PayRam es infraestructura prioritaria para agentes (agent-first). Como la integración se realiza mediante MCP, funciona con cualquier runtime compatible con MCP — OpenClaw, Hermes, Claude Desktop, Cursor, GitHub Copilot, n8n, LangChain y más. Un flujo típico de agente:

1. Conectar — añade https://mcp.payram.com/mcp a la configuración MCP del agente (no se necesita clave API solo para conectar).
2. Planificar — llama a payram_setup_plan. Devuelve los pasos ordenados, quién ejecuta cada uno y dónde debe detenerse el agente para el humano (cartera fría, gas de mainnet, ajustes solo root).
3. Instalar — en el VPS, en una terminal interactiva, una vez, ejecuta bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet (o --mainnet; el instalador usa mainnet por defecto, así que pasa siempre la bandera). Nunca lo canalices a bash.
4. Traspaso — el humano reclama la cuenta root de inmediato y guarda Settings → Site URL desde el dominio público; hasta entonces, los enlaces de pago apuntan a http://localhost.
5. Comprobar — payram_doctor con la URL pública (sin necesidad de credenciales).
6. Aceptar pagos — inserta el código de integración específico del framework desde las herramientas de fragmentos. Los webhooks están firmados (X-Payram-Signature, HMAC-SHA256 del cuerpo sin procesar con la clave API del proyecto).
7. Operar — payram_ops_playbook (daily_check, payment_options, node_sync, unswept_funds, create_payment_link, …) proporciona al agente las llamadas API exactas para ejecutar con sus propias credenciales. payram_runbook cubre los cambios administrativos.

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

Para el tutorial específico de OpenClaw (registro, testnet en Base Sepolia, patrones de comercio por chat para WhatsApp/Telegram/Discord), consulta la habilidad payram-openclaw-integration y 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 es difícil de alcanzar desde tu red, puedes duplicar este repositorio en otro host de Git (git clone --mirror https://github.com/PayRam/payram-mcp.git). 如果你的网络难以访问 GitHub，可以把本仓库镜像到其他 Git 托管平台（git clone --mirror https://github.com/PayRam/payram-mcp.git）。

---

Tabla de contenidos

• ¿Qué es PayRam?
• Cómo usan PayRam los agentes de IA
• Habilidades del agente
• Objetivos del proyecto
• Inicio rápido
• Conectar desde tu cliente MCP
• Modo local
• Credenciales
• Catálogo de herramientas
• Flujos de trabajo guiados
• Desarrollo
• Solución de problemas

---

Habilidades del agente

Puerta de entrada del agente: https://mcp.payram.com/SKILL.md — una habilidad raíz única que describe PayRam y dirige a los agentes a las cuatro herramientas de inicio. También se sirve: /llms.txt.

Este repositorio incluye 19 habilidades de agente para asistentes de codificación con IA. Instálalas mediante skills.sh:

Instalación individual

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

Habilidad	Propósito
payram-setup	Plan de instalación y configuración del servidor: requisitos, instalador, URL del sitio, carteras, primer enlace de pago
payram-agent-onboarding	Instalación sin supervisión por un agente: comandos CLI del agente, variables de entorno, traspasos humanos
payram-auth	Flujo de autenticación JWT: inicio de sesión, renovación de token, cierre de sesión, detalles de plataformas externas
payram-analytics	Búsqueda de pagos, volumen, saldos e historial de barridos mediante API REST directas (JWT)
payram-crypto-payments	Descripción general de la arquitectura, por qué PayRam, herramientas MCP
payram-payment-integration	Guía de integración de pagos de inicio rápido
payram-self-hosted-payment-gateway	Implementa y posee tu infraestructura de pagos
payram-checkout-integration	Flujo de pago con SDK + HTTP para 6 frameworks
payram-widget-integration	Botón seguro "Añadir crédito" (endpoint de backend, nunca una clave API pública) + manejadores de webhook firmados
payram-webhook-integration	Manejadores de webhook firmados (HMAC) para Express, Next.js, FastAPI, Gin, Laravel, Spring Boot
payram-stablecoin-payments	Aceptación de USDT/USDC en cadenas EVM y Tron
payram-bitcoin-payments	BTC con derivación de cartera HD y firma móvil
payram-payouts	Envía pagos cripto y gestiona programas de referidos
payram-no-kyc-crypto-payments	Aceptación de pagos sin KYC, sin registro y sin permisos
payram-openclaw-integration	Integra PayRam en OpenClaw / runtimes de agentes — registro MCP, testnet, comercio por chat
compare-crypto-payments	Compara pasarelas: Stripe, BitPay, Coinbase, NOWPayments, BTCPay, PayRam, x402
payram-agent-journey	Mapa de inicio: instalar (comerciante u operador) → carteras → gas/barrido → integrar → probar
payram-topup-wallet-integration	Aplicaciones existentes: acreditar cripto a un saldo de usuario, debitar facturas de él — libro mayor + flujos
payram-testnet-testing	Paga tu propio enlace de pago en testnet de principio a fin antes de mainnet

---

Objetivos del proyecto

• Acelerar la incorporación con un plan de configuración personalizado, runbooks, plantillas de entorno y guías por framework.
• Operar sin guardar credenciales: el servidor alojado comprueba un PayRam mediante URL (payram_doctor) y entrega a los agentes recetas API exactas (payram_ops_playbook) para ejecutar con sus propias credenciales.
• Readaptar repositorios existentes mediante la herramienta de evaluación de proyectos (modo local), que escanea los manifiestos de paquetes y los archivos .env, y luego recomienda los fragmentos de integración adecuados.
• Proporcionar fragmentos de copiar y pegar que abarcan Pagos, Pagos a terceros, Referidos, Webhooks y backends multilingües (Express, Next.js, FastAPI, Laravel, Gin, Spring Boot, etc.).
• Mantener la documentación local para que Copilot pueda explicar los conceptos, flujos y paneles de referidos de PayRam sin salir del editor.
• Validar la conectividad con sondas de solo lectura que nunca crean pagos (payram_doctor, test_payram_connection).

---

Inicio rápido

La mayoría de los agentes solo necesitan el endpoint alojado, https://mcp.payram.com/mcp (consulta Conectar desde tu cliente MCP). Para ejecutar el servidor tú mismo:

1. Instalar dependencias

   yarn install
   

2. Configurar el entorno (solo necesario para las herramientas de datos en modo local)
   • Copia .env.example a .env.
   • Establece PAYRAM_BASE_URL a tu URL de PayRam, el mismo origen que el panel (por ejemplo, https://pay.example.com).
   • Establece PAYRAM_API_KEY, además de las variables JWT para las herramientas de datos. Consulta Modo local.
3. Ejecutar el servidor

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

4. Agregar el servidor MCP a tu cliente: consulta Conectar desde tu cliente MCP. La URL en modo local es http://localhost:3333/mcp.
5. Verificación de salud

   curl http://localhost:3333/healthz
   

Consejo: Cuando le digas a Copilot "test payram", ejecutará automáticamente la lista de verificación de preparación, asegurará que .env exista, y solo entonces llamará a test_payram_connection con tus credenciales reales. El comportamiento está definido por el prompt de automatización de Copilot—no se requiere solicitud manual.

---

Conectar desde tu cliente MCP

Endpoint: https://mcp.payram.com/mcp (HTTP Streamable, JSON-RPC sobre POST). No hay endpoint SSE, y /mcp/sse devuelve 410. Sin cabeceras de autenticación: el servidor alojado nunca guarda credenciales de comerciante, por lo que las tuyas permanecen en tu máquina y nunca entran en el chat.

Cliente	Dónde	Configuración
VS Code (Copilot Chat)	Configuración → Copilot: Model Context Protocol → Agregar servidor HTTP	Nombre payram, URL anterior, cabeceras vacías
Cursor	Configuración → Servidores MCP → Agregar → HTTP	Nombre payram, URL anterior
Claude Desktop / Code	Configuración → Servidores MCP → Agregar servidor HTTP	Nombre payram, URL anterior
Cualquier cliente MCP	Registrar un endpoint HTTP	URL anterior, sin cabeceras

Verificación: la lista de herramientas debería comenzar con payram_setup_plan, payram_doctor, payram_troubleshoot, payram_runbook y payram_ops_playbook, seguidas de scaffold_payram_app y las herramientas de fragmentos generate_*. Luego prueba: "planificar una instalación de PayRam en pay.example.com", "verificar https://pay.example.com", "generar una ruta de creación de pago en FastAPI", "dame un manejador de webhook en Next.js".

Prompts: setup-payram, setup-payram-agent, integrate-payment, troubleshoot-payment, daily-ops. Recursos: payram://docs/setup-guide, payram://docs/api-reference, y las plantillas payram://ops/playbook/{task} y payram://runbooks/{task}.

Prompt de automatización de Copilot

Pega esto una vez en un espacio de trabajo nuevo para que "test payram" ejecute automáticamente el flujo completo de preparación:

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.

---

Modo local

Ejecuta el MCP junto a tu propio PayRam para obtener las herramientas de datos en vivo:

• 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

• Modo: PAYRAM_MCP_MODE=local selecciona el modo local. También es el predeterminado siempre que el servidor no se ejecute en Vercel. PAYRAM_MCP_MODE=hosted nunca lee credenciales.
• Enlace: el modo local se enlaza a 127.0.0.1 por defecto (puerto PORT, predeterminado 3333).
• Enlaces no loopback: establece HOST (por ejemplo, HOST=0.0.0.0), luego:
  • Establece MCP_ALLOWED_HOSTS (nombres de host separados por comas aceptados en la cabecera Host).
  • Establece MCP_SERVER_TOKEN; los clientes envían entonces Authorization: Bearer <token>.
  • Si se establecen las credenciales PAYRAM_*, el servidor se niega a iniciar en un HOST no loopback sin MCP_SERVER_TOKEN. Prefiere loopback más un túnel SSH.
• Credenciales: las herramientas de datos leen PAYRAM_* del entorno (o .env):
  • PAYRAM_BASE_URL
  • PAYRAM_API_KEY (enlaces de pago)
  • PAYRAM_ACCESS_TOKEN / PAYRAM_REFRESH_TOKEN (JWT, herramientas de datos)
  • PAYRAM_EXTERNAL_PLATFORM_ID (proyecto predeterminado opcional)

Ejemplo de configuración de cliente para un servidor local (solo modo local):

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

---

Credenciales: qué clave para qué

PayRam tiene dos credenciales — los agentes se detienen cuando las confunden:

Credencial	Se ve como	Se usa para	Cómo la obtiene un agente (sin necesidad de panel)
Clave API de comerciante (PAYRAM_API_KEY, cabecera API-Key)	clave por proyecto	POST /api/v1/payment (enlaces de pago), pagos al comerciante, todas las llamadas servidor a servidor del comerciante, y firma webhooks (X-Payram-Signature)	bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) ensure-api-key — reutiliza o crea la clave del proyecto mediante POST /api/v1/external-platform/{id}/api-key y la guarda en ~/.payraminfo/merchant-api-key.env
JWT (Authorization: Bearer)	token de acceso+refresco del inicio de sesión	APIs de administración/configuración (proyectos, billeteras, análisis) — recetas payram_ops_playbook y las herramientas de datos en modo local	bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) signin (env PAYRAM_EMAIL/PAYRAM_PASSWORD); guardado en ~/.payraminfo/headless-tokens.env

El flujo de configuración en un solo paso (bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet) produce ambas automáticamente e imprime dónde se encuentran. La API es del mismo origen que el panel, en el puerto 80/443 (https://<your-domain>/api/v1/..., o http://localhost en el servidor, nunca :8080). La clave API puede crear pagos, así que mantenla en el lado del servidor y nunca la pongas en código de navegador o en el chat. Usa la tarea payram_ops_playbook connect para configurar ambas para llamadas API directas.

---

Catálogo de herramientas

Categoría	Herramienta	Propósito
Empezar aquí – Instalación	payram_setup_plan	Plan de instalación personalizado y ordenado (preparar → instalar → reclamar root + URL del sitio → carteras + Smart Bridge → clave API + primer enlace → endurecer → integrar) con pasos para agente vs. humano y puntos de detención obligatorios.
Empezar aquí – Diagnóstico	payram_doctor, payram_troubleshoot	payram_doctor: verificación pública por etapas sin credenciales mediante URL (accesibilidad → salud → TLS → versión → workers) con causas probables clasificadas + correcciones exactas. Verificación opcional de validez de clave API que no crea nada. Ejecútelo PRIMERO cuando algo falle. payram_troubleshoot: relaciona un síntoma o error pegado con causas y correcciones conocidas.
Empezar aquí – Administración	payram_runbook	Tareas administrativas paso a paso con compuertas humanas: 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.
Empezar aquí – Operaciones	payram_ops_playbook	Recetas de API directas que el agente ejecuta por sí mismo: 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.
Conectividad	test_payram_connection	Verificación de accesibilidad/salud de solo lectura más validación opcional de clave API. Nunca crea pagos.
Configuración	generate_env_template, generate_setup_checklist, suggest_file_structure, get_agent_setup_flow, onboard_agent_setup	Entrega plantillas de entorno, listas de verificación para comerciantes, estructuras de proyecto recomendadas y la guía de incorporación para agentes sin interfaz.
Contexto / Documentación	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.	Proporciona conocimiento en Markdown en línea proveniente de docs/ para que Copilot pueda responder preguntas conceptuales. Algunas herramientas añaden recordatorios de "diga test payram" automáticamente.
Integración – Pagos	generate_payment_sdk_snippet, generate_payment_http_snippet, generate_payment_status_snippet, generate_payment_route_snippet	Genera código de SDK, HTTP sin procesar o rutas Express/Next.js para flujos de creación y estado.
Integración – Pagos a comerciantes	generate_payout_sdk_snippet, generate_payout_recipient_flow_snippet, generate_payout_status_snippet	Pago directo (sin OTP), el flujo de destinatario guardado en 3 pasos (crear destinatario → validar OTP → pagar) y sondeo de estado.
Integración – Referidos	generate_referral_sdk_snippet, generate_referral_validation_snippet, generate_referral_status_snippet, generate_referral_route_snippet	Cubren autenticación de referidos, vinculación, validación, estado y rutas express/next.
Integración – Webhooks	generate_webhook_handler, generate_webhook_event_router, generate_mock_webhook_event	Producen manejadores para Express/Next/FastAPI/Gin/Laravel/Spring Boot, enrutadores de distribución y probadores de webhooks en cURL/Python/Go/PHP/Java.
Integración – Pagos multilingües	snippet_* familia (snippet_express_payment_route, snippet_nextjs_payment_route, snippet_fastapi_payment_route, snippet_laravel_payment_route, snippet_go_payment_handler, snippet_spring_payment_controller)	Manejadores de rutas preconstruidos para Express, Next.js App Router, FastAPI, Gin, Laravel y Spring Boot.
Integración – Recarga de cartera	generate_topup_integration_snippet	Para aplicaciones EXISTENTES: esquema de libro mayor + webhook de crédito acumulativo + liquidación atómica de facturas, de modo que los pagos cripto excesivos/insuficientes/tardíos/duplicados se conviertan en estados de saldo en lugar de excepciones de pago. Se combina con la habilidad payram-topup-wallet-integration.
Integración – Evaluación de proyecto (modo local)	assess_payram_project	Escanea package.json, requirements.txt, composer.json, go.mod, pom.xml, .env, etc. Informa sobre frameworks detectados, estado del entorno, dependencias de PayRam y próximos pasos priorizados con sugerencias de herramientas.
Andamiaje	scaffold_payram_app	Genera aplicaciones iniciales completas (Express, Next.js, FastAPI, Laravel, Gin, Spring Boot) con pagos, pagos a comerciantes, webhooks y una consola de navegador. Coloque los endpoints de pagos detrás de su propia autenticación de administrador antes de implementar.
Datos en vivo (solo lectura, modo local)	list_platforms, search_payments, lookup_payment, get_payment_summary, get_daily_volume, get_unswept_balances, list_currencies, list_recipients	Consulta datos en vivo de PayRam. list_currencies es público (sin clave); el resto usa los tokens JWT en .env. list_recipients se combina con el flujo de destinatario de pagos.
Operaciones en vivo (modo local)	create_payment_link (escritura), check_payment_readiness, check_node_sync, restart_payram_worker (escritura)	create_payment_link crea un enlace de pago real mediante API-Key. check_payment_readiness informa brechas por cadena (cartera / moneda / listener faltantes) para aceptar pagos. check_node_sync informa la salud de listener-worker + nodo RPC y el estancamiento de bloques. En el servidor alojado, use las tareas payram_ops_playbook correspondientes.

Los registros de herramientas viven en src/tools/index.ts; las implementaciones individuales se encuentran en src/tools/** con plantillas específicas por idioma en las carpetas templates/.

---

Flujos de trabajo guiados

0. Instalar PayRam

1. Pida: "Configura PayRam en pay.example.com" (o use los avisos setup-payram / setup-payram-agent).
2. El asistente llama a payram_setup_plan y recorre las fases, deteniéndose en cada paso humano (cuenta root, URL del sitio, cartera fría, gas de mainnet).
3. Finaliza con payram_doctor, copias de seguridad (payram_runbook backup) y la verificación diaria (payram_ops_playbook daily_check).

1. Evaluar y adaptar un proyecto existente

1. Pregunta a Copilot: "¿Puedes integrar PayRam en este proyecto?"
2. El asistente ejecuta assess_payram_project (modo local), revisando manifiestos de dependencias y .env.
3. Sigue los pasos recomendados (instala payram, solicita fragmentos de rutas Express/FastAPI/Spring, agrega webhooks, etc.).
4. Usa test_payram_connection una vez que las credenciales sean reales para asegurar que el backend pueda alcanzar tu servidor autoalojado.

2. Crear un Ejemplo Nuevo desde Cero

1. "Crea un demo Express de PayRam" → scaffold_payram_app construye un proyecto Express con pagos, pagos a terceros, webhooks y una consola de interfaz de usuario.
2. Coloca los archivos generados en un repositorio vacío o compáralos con tu directorio existente para ver el cableado de referencia.

3. Ejecutar el Flujo de Preparación "Probar PayRam"

1. Di "probar payram". El asistente automáticamente:
   • Llama a prepare_payram_test para compartir la lista de verificación de preparación.
   • Se asegura de que .env exista (creándolo si falta) usando generate_env_template.
   • Espera credenciales reales antes de invocar test_payram_connection.
2. Revisa el resultado JSON estructurado para confirmar que la API de PayRam es accesible.

4. Conectar Pagos, Pagos a Terceros, Referidos y Webhooks

• Pagos: generate_payment_sdk_snippet (SDK de JS) o generate_payment_http_snippet (Python/Go/PHP/Java).
• Rutas multilingües: snippet_nextjs_payment_route, snippet_fastapi_payment_route, etc.
• Pagos a terceros: generate_payout_sdk_snippet para crear + generate_payout_status_snippet para consultar.
• Referidos: generate_referral_route_snippet, generate_referral_validation_snippet.
• Webhooks: generate_webhook_handler más generate_webhook_event_router para distribución + generate_mock_webhook_event para probar cada estado.

---

Desarrollo

Comando	Descripción
yarn dev	Ejecuta el servidor MCP con recarga automática mediante tsx.
yarn build	Compila TypeScript a dist/.
yarn lint / yarn format	ESLint + Prettier en todo el repositorio.
yarn test	Ejecuta la suite de Vitest (tests/).
make precommit-test	Ejecuta formato → lint → test → build secuencialmente.

El proyecto es TypeScript-first (ESM). La configuración de Prettier está en .prettierrc.json; ESLint se configura mediante eslint.config.mjs. Las contribuciones fluidas siguen el asistente de commits en Makefile → make commit.

---

Solución de Problemas

Comienza con payram_doctor — una sola llamada de solo lectura que recorre accesibilidad → salud → TLS → versión → trabajadores y devuelve causas clasificadas con correcciones exactas. Para verificaciones más profundas, sigue payram_ops_playbook (stuck_payment, node_sync, webhooks, logs).

• Copilot no llama a la herramienta correcta: Verifica que el prompt de automatización de Copilot esté instalado y que tu cliente MCP haya cargado el servidor. Vuelve a ejecutar "probar payram" o "evaluar mi proyecto" para activar la automatización esperada.
• test_payram_connection falla con 401: Confirma que la clave es una clave de API de proyecto activa (enviada como el encabezado API-Key, no Authorization).
• Una herramienta de datos dice que las credenciales no están disponibles: el servidor alojado nunca guarda credenciales de comerciante. Usa la tarea payram_ops_playbook correspondiente, o ejecuta el MCP en modo local.
• Los enlaces de pago muestran http://localhost: el humano debe guardar Configuración → URL del sitio desde el dominio público (tarea payram_runbook set_site_url).
• La herramienta de documentación dice que falta un archivo: Verifica que tu árbol local de docs/payram-docs-live/ contenga el markdown solicitado (get_payram_doc_by_id rechaza rutas con ..).
• El servidor no arranca: Asegúrate de tener Node 20+ y ejecuta yarn install. En modo local con un HOST no loopback y credenciales PAYRAM_* configuradas, el servidor se niega a arrancar hasta que se establezca MCP_SERVER_TOKEN (ver Modo local).

Para cualquier otra cosa, inspecciona los registros estructurados emitidos desde src/utils/logger.ts (establece LOG_LEVEL=debug) y abre un issue/PR con detalles de reproducción.