PayRam Crypto Card Payment Gateway

Servidor MCP PayRam — Pagamentos Cripto Auto-Hospedados para Agentes de IA

Pagamentos cripto e stablecoin auto-hospedados: sem bloqueio de conta, sem congelamento de fundos, dados de clientes nunca compartilhados. Seu agente de IA pode planejar, instalar e operar via MCP. Endpoint hospedado: https://mcp.payram.com/mcp · Site · Docs · Agentic · OpenClaw

Um servidor MCP (Model Context Protocol) que permite que qualquer agente de IA compatível com MCP — OpenClaw, Hermes, Claude, Cursor, GitHub Copilot e outros — implante, integre e opere uma stack de pagamentos cripto PayRam auto-hospedada.

Comece aqui: quatro ferramentas lideram o catálogo:

Ferramenta	O que faz
payram_setup_plan	Um plano de instalação personalizado, com cada etapa manual marcada
payram_doctor	Uma verificação pública, sem credenciais, de um servidor PayRam por URL
payram_troubleshoot	Descreva um problema ou cole um erro: causas conhecidas, como confirmar, a correção e a próxima ferramenta
payram_runbook	Tarefas administrativas: URL do site, domínio, SSL, firewall, atualização, backup, chains, Smart Bridge, Shopify/WooCommerce
payram_ops_playbook	Receitas de API do dia 2 que o agente executa com suas próprias credenciais

Ao redor delas, há avaliação de codebase, scaffolds de aplicativos iniciais, snippets multilíngues e documentação inline.

O servidor hospedado (mcp.payram.com) nunca armazena credenciais de comerciante. As operações do dia 2 são executadas via payram_ops_playbook: o agente chama sua API PayRam diretamente, e as credenciais nunca saem da máquina dele. As ferramentas de dados ao vivo (busca de pagamentos, links de pagamento, sincronização de nós, reinício de workers) e assess_payram_project existem apenas quando você executa o MCP em modo local.

Para agentes e crawlers: cartão do servidor · índice de skills · llms.txt · sitemap. O servidor também responde Accept: text/markdown em / com um resumo legível por agentes.

---

O que é PayRam? · PayRam 是什么？

PayRam é um gateway de pagamento cripto multi-chain auto-hospedado que você possui integralmente — sem cadastro e sem KYC/KYB para operá-lo. Um agente de IA (ou um desenvolvedor) pode montar uma loja e começar a aceitar pagamentos sem registrar uma conta na PayRam, em um banco ou em qualquer processador de pagamento. Implante em seu próprio VPS, gere chaves de API localmente e vá ao ar.

O que o torna diferente:

• Ninguém pode bloqueá-lo — não há conta para bloquear nem fundos para congelar. Dados de clientes nunca são compartilhados, e nada é reportado ou monitorado. O motivo é simples: a PayRam roda no seu servidor e os fundos caem na sua própria carteira.
• Configuração sem permissão — sem cadastro, sem KYC, sem KYB. Ninguém aprova você; ninguém pode desligá-lo. Ideal para agentes que criam lojas de forma autônoma e para mercados como a China, onde registrar-se em um processador ocidental não é uma opção.
• Checkout de cartão para cripto — compradores sem cripto podem pagar com cartão de crédito/débito e você recebe cripto, liquidado diretamente na sua carteira de autocustódia. É um canal integrado que você ativa na página de Pagamentos; o provedor de cartão faz suas próprias verificações no comprador.
• Multi-chain — aceite BTC, ETH, USDT, USDC e TRX nativamente em Bitcoin, Ethereum, Base, Polygon e Tron, com detecção automática de depósitos, confirmação on-chain, varreduras para cold storage e webhooks assinados. Os trilhos Smart Bridge também aceitam pagamentos em Solana, Bitcoin, Tron (USDT) e BNB Chain e os liquidam como USDC na Base.
• Sem chaves de depósito no servidor — contratos inteligentes varrem depósitos para sua carteira fria, então um servidor comprometido não pode redirecioná-los. A carteira quente do servidor paga o gás e assina pagamentos, então mantenha o saldo dela pequeno.

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

---

Como agentes de IA usam PayRam · AI 智能体如何使用 PayRam

PayRam é uma infraestrutura agent-first. Como a integração é via MCP, funciona com qualquer runtime compatível com MCP — OpenClaw, Hermes, Claude Desktop, Cursor, GitHub Copilot, n8n, LangChain e outros. Um fluxo típico de agente:

1. Conecte — adicione https://mcp.payram.com/mcp à configuração MCP do agente (nenhuma chave de API é necessária apenas para conectar).
2. Planeje — chame payram_setup_plan. Ele retorna as etapas ordenadas, quem executa cada uma e onde o agente deve parar para o humano (carteira fria, gás da mainnet, configurações somente root).
3. Instale — no VPS, em um terminal interativo, uma vez, execute bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet (ou --mainnet; o padrão do instalador é mainnet, então sempre passe a flag). Nunca canalize para bash.
4. Entregue — o humano reivindica a conta root imediatamente e salva Configurações → URL do Site do domínio público; até lá, os links de pagamento apontam para http://localhost.
5. Verifique — payram_doctor com a URL pública (nenhuma credencial necessária).
6. Aceite pagamentos — insira o código de integração específico do framework das ferramentas de snippet. Os webhooks são assinados (X-Payram-Signature, HMAC-SHA256 do corpo bruto com a chave de API do projeto).
7. Opere — payram_ops_playbook (daily_check, payment_options, node_sync, unswept_funds, create_payment_link, …) dá ao agente as chamadas de API exatas para executar com suas próprias credenciais. payram_runbook cobre alterações administrativas.

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

Para o passo a passo específico do OpenClaw (registro, testnet na Base Sepolia, padrões de chat-commerce para WhatsApp/Telegram/Discord), veja a skill payram-openclaw-integration e 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 服务器从不保存商户凭证。

Se o GitHub for difícil de acessar pela sua rede, você pode espelhar este repositório em outro host Git (git clone --mirror https://github.com/PayRam/payram-mcp.git). 如果你的网络难以访问 GitHub，可以把本仓库镜像到其他 Git 托管平台（git clone --mirror https://github.com/PayRam/payram-mcp.git）。

---

Índice

• O que é PayRam?
• Como agentes de IA usam PayRam
• Agent Skills
• Objetivos do Projeto
• Início Rápido
• Conecte-se pelo seu cliente MCP
• Modo local
• Credenciais
• Catálogo de Ferramentas
• Fluxos Guiados
• Desenvolvimento
• Solução de Problemas

---

Agent Skills

Porta de entrada do agente: https://mcp.payram.com/SKILL.md — uma skill raiz única que descreve a PayRam e roteia agentes para as quatro ferramentas iniciais. Também servido: /llms.txt.

Este repositório inclui 19 Agent Skills para assistentes de codificação de IA. Instale-as via skills.sh:

Instalar individualmente

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	Propósito
payram-setup	Plano de instalação e configuração do servidor: requisitos, instalador, URL do site, carteiras, primeiro link de pagamento
payram-agent-onboarding	Instalação headless por um agente: comandos CLI do agente, variáveis de ambiente, entregas manuais
payram-auth	Fluxo de autenticação JWT — login, renovação de token, logout, detalhes de plataformas externas
payram-analytics	Busca de pagamentos, volume, saldos e histórico de varredura via APIs REST diretas (JWT)
payram-crypto-payments	Visão geral da arquitetura, por que PayRam, ferramentas MCP
payram-payment-integration	Guia de integração de pagamento de início rápido
payram-self-hosted-payment-gateway	Implante e possua sua infraestrutura de pagamento
payram-checkout-integration	Fluxo de checkout com SDK + HTTP para 6 frameworks
payram-widget-integration	Botão "Adicionar Crédito" seguro (endpoint de backend, nunca uma chave de API pública) + manipuladores de webhook assinados
payram-webhook-integration	Manipuladores de webhook assinados (HMAC) para Express, Next.js, FastAPI, Gin, Laravel, Spring Boot
payram-stablecoin-payments	Aceitação de USDT/USDC em chains EVM e Tron
payram-bitcoin-payments	BTC com derivação de carteira HD e assinatura móvel
payram-payouts	Envie pagamentos cripto e gerencie programas de indicação
payram-no-kyc-crypto-payments	Aceitação de pagamentos sem KYC, sem cadastro, sem permissão
payram-openclaw-integration	Integre PayRam em runtimes OpenClaw / agente — registro MCP, testnet, chat commerce
compare-crypto-payments	Compare gateways: Stripe, BitPay, Coinbase, NOWPayments, BTCPay, PayRam, x402
payram-agent-journey	Mapa inicial: instalar (comerciante ou operador) → carteiras → gás/varredura → integrar → testar
payram-topup-wallet-integration	Aplicativos existentes: credite cripto ao saldo do usuário, debite faturas dele — ledger + fluxos
payram-testnet-testing	Pague seu próprio link de pagamento na testnet de ponta a ponta antes da mainnet

---

Objetivos do Projeto

• Acelerar a integração com um plano de configuração personalizado, runbooks, modelos de env e playbooks por framework.
• Operar sem armazenar credenciais: o servidor hospedado verifica uma PayRam por URL (payram_doctor) e entrega aos agentes receitas de API exatas (payram_ops_playbook) para executar com suas próprias credenciais.
• Adaptar repositórios existentes via ferramenta de avaliação de projeto (modo local), que escaneia manifestos de pacotes e arquivos .env, e então recomenda os snippets de integração certos.
• Fornecer snippets de copiar/colar abrangendo Pagamentos, Pagamentos, Indicações, Webhooks e backends multilíngues (Express, Next.js, FastAPI, Laravel, Gin, Spring Boot, etc.).
• Manter a documentação local para que o Copilot possa explicar conceitos, fluxos e painéis de indicações da PayRam sem sair do editor.
• Validar conectividade com sondas somente leitura que nunca criam pagamentos (payram_doctor, test_payram_connection).

---

Início Rápido

A maioria dos agentes só precisa do endpoint hospedado, https://mcp.payram.com/mcp (veja Conecte-se pelo seu cliente MCP). Para executar o servidor você mesmo:

1. Instalar dependências

   yarn install
   

2. Configurar o ambiente (necessário apenas para as ferramentas de dados em modo local)
   • Copie .env.example para .env.
   • Defina PAYRAM_BASE_URL para a sua URL PayRam, a mesma origem do painel (ex.: https://pay.example.com).
   • Defina PAYRAM_API_KEY, além das variáveis JWT para as ferramentas de dados. Consulte Modo local.
3. Executar o servidor

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

4. Adicionar o servidor MCP ao seu cliente: consulte Conectar a partir do seu cliente MCP. A URL do modo local é http://localhost:3333/mcp.
5. Verificação de integridade

   curl http://localhost:3333/healthz
   

Dica: Quando você disser ao Copilot "testar payram", ele executará automaticamente a lista de verificação de prontidão, garantirá que .env exista e só então chamará test_payram_connection com suas credenciais reais. O comportamento é definido pelo prompt de automação do Copilot—nenhum prompt manual é necessário.

---

Conectar a partir do seu cliente MCP

Endpoint: https://mcp.payram.com/mcp (HTTP Streamable, JSON-RPC sobre POST). Não há endpoint SSE, e /mcp/sse retorna 410. Sem cabeçalhos de autenticação: o servidor hospedado nunca armazena credenciais de comerciante, então as suas permanecem na sua máquina e nunca vão para o chat.

Cliente	Onde	Configurações
VS Code (Copilot Chat)	Configurações → Copilot: Model Context Protocol → Adicionar servidor HTTP	Nome payram, URL acima, cabeçalhos vazios
Cursor	Configurações → Servidores MCP → Adicionar → HTTP	Nome payram, URL acima
Claude Desktop / Code	Configurações → Servidores MCP → Adicionar servidor HTTP	Nome payram, URL acima
Qualquer cliente MCP	Registrar um endpoint HTTP	URL acima, sem cabeçalhos

Verificação: a lista de ferramentas deve começar com payram_setup_plan, payram_doctor, payram_troubleshoot, payram_runbook e payram_ops_playbook, seguida por scaffold_payram_app e pelas ferramentas de snippet generate_*. Em seguida, tente: "planejar uma instalação PayRam em pay.example.com", "verificar https://pay.example.com", "gerar uma rota FastAPI de criação de pagamento", "me dar um manipulador de webhook Next.js".

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

Prompt de automação do Copilot

Cole isto uma vez em um novo workspace para fazer "testar payram" executar automaticamente o fluxo completo de prontidão:

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

Execute o MCP ao lado do seu próprio PayRam para obter as ferramentas de dados ao 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 seleciona o modo local. Também é o padrão sempre que o servidor não estiver rodando na Vercel. PAYRAM_MCP_MODE=hosted nunca lê credenciais.
• Vinculação: o modo local vincula a 127.0.0.1 por padrão (porta PORT, padrão 3333).
• Vinculações não-loopback: defina HOST (ex.: HOST=0.0.0.0), então:
  • Defina MCP_ALLOWED_HOSTS (nomes de host separados por vírgula aceitos no cabeçalho Host).
  • Defina MCP_SERVER_TOKEN; os clientes então enviam Authorization: Bearer <token>.
  • Se as credenciais PAYRAM_* estiverem definidas, o servidor se recusa a iniciar em um HOST não-loopback sem MCP_SERVER_TOKEN. Prefira loopback mais um túnel SSH.
• Credenciais: as ferramentas de dados leem PAYRAM_* do ambiente (ou .env):
  • PAYRAM_BASE_URL
  • PAYRAM_API_KEY (links de pagamento)
  • PAYRAM_ACCESS_TOKEN / PAYRAM_REFRESH_TOKEN (JWT, ferramentas de dados)
  • PAYRAM_EXTERNAL_PLATFORM_ID (projeto padrão opcional)

Exemplo de configuração de cliente para um servidor local (somente modo local):

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

---

Credenciais: qual chave para quê

PayRam tem duas credenciais — os agentes travam quando as confundem:

Credencial	Aparência	Usada para	Como um agente a obtém (sem necessidade de painel)
Chave de API do comerciante (PAYRAM_API_KEY, cabeçalho API-Key)	chave por projeto	POST /api/v1/payment (links de pagamento), pagamentos ao comerciante, todas as chamadas servidor-a-servidor do comerciante, e assina webhooks (X-Payram-Signature)	bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) ensure-api-key — reutiliza ou gera a chave do projeto via POST /api/v1/external-platform/{id}/api-key e a salva em ~/.payraminfo/merchant-api-key.env
JWT (Authorization: Bearer)	token de acesso+atualização do login	APIs de administração/configuração (projetos, carteiras, análises) — receitas payram_ops_playbook e as ferramentas de dados do modo local	bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) signin (env PAYRAM_EMAIL/PAYRAM_PASSWORD); salvo em ~/.payraminfo/headless-tokens.env

O fluxo de configuração em uma etapa (bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet) produz ambas automaticamente e imprime onde elas estão. A API é de mesma origem que o painel, na porta 80/443 (https://<your-domain>/api/v1/..., ou http://localhost no servidor, nunca :8080). A chave de API pode criar pagamentos, então mantenha-a no lado do servidor e nunca a coloque em código de navegador ou chat. Use a tarefa payram_ops_playbook connect para configurar ambas para chamadas diretas à API.

---

Catálogo de Ferramentas

Categoria	Ferramenta	Finalidade
Comece aqui – Instalação	payram_setup_plan	Plano de instalação personalizado e ordenado (preparar → instalar → reivindicar root + URL do site → carteiras + Smart Bridge → chave de API + primeiro link → endurecer → integrar) com etapas para agente e humano, além de pontos de parada obrigatórios.
Comece aqui – Diagnóstico	payram_doctor, payram_troubleshoot	payram_doctor: verificação pública em etapas, sem credenciais, por URL (acessibilidade → saúde → TLS → versão → workers) com causas prováveis classificadas + correções exatas. Verificação opcional de validade da chave de API que não cria nada. Execute isso PRIMEIRO quando algo falhar. payram_troubleshoot: associe um sintoma ou erro colado a causas e correções conhecidas.
Comece aqui – Administração	payram_runbook	Tarefas administrativas passo a passo com portões humanos: 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.
Comece aqui – Operações	payram_ops_playbook	Receitas de API diretas que o agente executa sozinho: 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.
Conectividade	test_payram_connection	Verificação somente leitura de acessibilidade/saúde, além de validação opcional da chave de API. Nunca cria pagamentos.
Configuração	generate_env_template, generate_setup_checklist, suggest_file_structure, get_agent_setup_flow, onboard_agent_setup	Fornece boilerplate de ambiente, listas de verificação para comerciantes, layouts de projeto recomendados e o guia de integração para agente headless.
Contexto / Documentação	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.	Fornece conhecimento em Markdown inline proveniente de docs/ para que o Copilot possa responder perguntas conceituais. Algumas ferramentas adicionam lembretes automáticos de "diga test payram".
Integração – Pagamentos	generate_payment_sdk_snippet, generate_payment_http_snippet, generate_payment_status_snippet, generate_payment_route_snippet	Gera código de SDK, HTTP bruto ou rotas Express/Next.js para fluxos de criação e status.
Integração – Pagamentos de saída (Payouts)	generate_payout_sdk_snippet, generate_payout_recipient_flow_snippet, generate_payout_status_snippet	Pagamento de saída direto (sem OTP), o fluxo de destinatário salvo em 3 etapas (criar destinatário → validar OTP → pagar) e consulta de status.
Integração – Indicações (Referrals)	generate_referral_sdk_snippet, generate_referral_validation_snippet, generate_referral_status_snippet, generate_referral_route_snippet	Cobre autenticação de indicação, vinculação, validação, status e rotas express/next.
Integração – Webhooks	generate_webhook_handler, generate_webhook_event_router, generate_mock_webhook_event	Produz handlers para Express/Next/FastAPI/Gin/Laravel/Spring Boot, roteadores de fan-out e testadores de webhook em cURL/Python/Go/PHP/Java.
Integração – Pagamentos multilíngues	Família snippet_* (snippet_express_payment_route, snippet_nextjs_payment_route, snippet_fastapi_payment_route, snippet_laravel_payment_route, snippet_go_payment_handler, snippet_spring_payment_controller)	Handlers de rota prontos para Express, Next.js App Router, FastAPI, Gin, Laravel e Spring Boot.
Integração – Carteira de recarga (Top-Up)	generate_topup_integration_snippet	Para aplicativos EXISTENTES: esquema de ledger + webhook de crédito cumulativo + liquidação atômica de faturas, para que pagamentos cripto acima/abaixo/atrasados/duplicados se tornem estados de saldo em vez de exceções de pagamento. Combina com a habilidade payram-topup-wallet-integration.
Avaliação de projeto (modo local)	assess_payram_project	Escaneia package.json, requirements.txt, composer.json, go.mod, pom.xml, .env, etc. Relata frameworks detectados, status do ambiente, dependências PayRam e próximos passos priorizados com sugestões de ferramentas.
Geração de estrutura (Scaffolding)	scaffold_payram_app	Gera aplicativos iniciais completos (Express, Next.js, FastAPI, Laravel, Gin, Spring Boot) com pagamentos, payouts, webhooks e um console no navegador. Coloque os endpoints de payout atrás da sua própria autenticação de administrador antes de implantar.
Dados ao vivo (somente leitura, modo local)	list_platforms, search_payments, lookup_payment, get_payment_summary, get_daily_volume, get_unswept_balances, list_currencies, list_recipients	Consulta dados ao vivo do PayRam. list_currencies é público (sem chave); os demais usam os tokens JWT em .env. list_recipients combina com o fluxo de destinatário de payout.
Operações ao vivo (modo local)	create_payment_link (gravação), check_payment_readiness, check_node_sync, restart_payram_worker (gravação)	create_payment_link cria um link de checkout real via API-Key. check_payment_readiness relata lacunas por rede (carteira / moeda / listener ausentes) para aceitar pagamentos. check_node_sync relata a saúde do listener-worker + nó RPC e a defasagem de blocos. No servidor hospedado, use as tarefas payram_ops_playbook correspondentes.

Os registros de ferramentas ficam em src/tools/index.ts; as implementações individuais ficam em src/tools/** com modelos específicos por linguagem nas pastas templates/.

---

Fluxos de Trabalho Guiados

0. Instalar PayRam

1. Pergunte: "Configurar PayRam em pay.example.com" (ou use os prompts setup-payram / setup-payram-agent).
2. O assistente chama payram_setup_plan e percorre as fases, parando em cada etapa humana (conta root, URL do site, carteira fria, gás da mainnet).
3. Ele finaliza com payram_doctor, backups (payram_runbook backup) e a verificação diária (payram_ops_playbook daily_check).

1. Avaliar e Adaptar um Projeto Existente

1. Pergunte ao Copilot: "Você consegue integrar o PayRam neste projeto?"
2. O assistente executa assess_payram_project (modo local), revisando manifestos de dependências e .env.
3. Siga os passos recomendados (instale payram, solicite trechos de rotas Express/FastAPI/Spring, adicione webhooks, etc.).
4. Use test_payram_connection quando as credenciais forem reais para garantir que o backend consiga alcançar seu servidor auto-hospedado.

2. Criar um Exemplo Novo do Zero

1. "Crie uma demonstração Express do PayRam" → scaffold_payram_app constrói um projeto Express com pagamentos, pagamentos, webhooks e um console de UI.
2. Coloque os arquivos gerados em um repositório vazio ou compare com seu diretório existente para referência de integração.

3. Execute o Fluxo de Prontidão "Testar PayRam"

1. Diga "testar payram". O assistente automaticamente:
   • Chama prepare_payram_test para compartilhar a lista de verificação de prontidão.
   • Garante que .env exista (criando-o se estiver ausente) usando generate_env_template.
   • Aguarda credenciais reais antes de invocar test_payram_connection.
2. Revise o resultado JSON estruturado para confirmar que a API do PayRam está acessível.

4. Integre Pagamentos, Pagamentos, Indicações e Webhooks

• Pagamentos: generate_payment_sdk_snippet (SDK JS) ou generate_payment_http_snippet (Python/Go/PHP/Java).
• Rotas multilíngues: snippet_nextjs_payment_route, snippet_fastapi_payment_route, etc.
• Pagamentos: generate_payout_sdk_snippet para criar + generate_payout_status_snippet para consulta.
• Indicações: generate_referral_route_snippet, generate_referral_validation_snippet.
• Webhooks: generate_webhook_handler mais generate_webhook_event_router para distribuição + generate_mock_webhook_event para testar cada status.

---

Desenvolvimento

Comando	Descrição
yarn dev	Executa o servidor MCP com recarga automática via tsx.
yarn build	Compila TypeScript para dist/.
yarn lint / yarn format	ESLint + Prettier em todo o repositório.
yarn test	Executa a suíte Vitest (tests/).
make precommit-test	Executa format → lint → test → build sequencialmente.

O projeto é TypeScript-first (ESM). A configuração do Prettier está em .prettierrc.json; o ESLint é configurado via eslint.config.mjs. Contribuições tranquilas seguem o auxiliar de commit em Makefile → make commit.

---

Solução de Problemas

Comece com payram_doctor — uma única chamada somente leitura que percorre acessibilidade → saúde → TLS → versão → workers e retorna causas classificadas com correções exatas. Para verificações mais profundas, siga payram_ops_playbook (stuck_payment, node_sync, webhooks, logs).

• O Copilot não chama a ferramenta certa: Verifique se o prompt de automação do Copilot está instalado e se seu cliente MCP carregou o servidor. Execute novamente "testar payram" ou "avaliar meu projeto" para acionar a automação esperada.
• test_payram_connection falha com 401: Confirme se a chave é uma chave de API de projeto ativa (enviada como cabeçalho API-Key, não Authorization).
• Uma ferramenta de dados diz que as credenciais não estão disponíveis: o servidor hospedado nunca armazena credenciais do comerciante. Use a tarefa payram_ops_playbook correspondente, ou execute o MCP em modo local.
• Links de pagamento mostram http://localhost: o humano deve salvar Configurações → URL do Site no domínio público (tarefa payram_runbook set_site_url).
• A ferramenta de documentação diz que um arquivo está ausente: Verifique se sua árvore local docs/payram-docs-live/ contém o markdown solicitado (get_payram_doc_by_id rejeita caminhos com ..).
• O servidor não inicia: Garanta Node 20+ e execute yarn install. No modo local com um HOST não-loopback e credenciais PAYRAM_* definidas, o servidor se recusa a iniciar até que MCP_SERVER_TOKEN seja definido (veja Modo local).

Para qualquer outra coisa, inspecione os logs estruturados emitidos de src/utils/logger.ts (defina LOG_LEVEL=debug) e abra uma issue/PR com detalhes de reprodução.