PayRam Crypto Card Payment Gateway

PayRam MCP Server — Самостоятельно размещаемые криптоплатежи для AI-агентов

Самостоятельно размещаемые крипто- и стейблкоин-платежи: никакой блокировки аккаунта, никакого замораживания средств, данные клиентов никогда не передаются третьим лицам. Ваш AI-агент может планировать, устанавливать и управлять этим через MCP. Размещённая конечная точка: https://mcp.payram.com/mcp · Веб-сайт · Документация · Agentic · OpenClaw

MCP (Model Context Protocol) сервер, который позволяет любому MCP-совместимому AI-агенту — OpenClaw, Hermes, Claude, Cursor, GitHub Copilot и другим — разворачивать, интегрировать и управлять самостоятельно размещаемым стеком криптоплатежей PayRam.

Начните здесь: четыре инструмента возглавляют каталог:

Инструмент	Что он делает
payram_setup_plan	Персонализированный план установки с отметкой каждой точки передачи человеку
payram_doctor	Публичная проверка сервера PayRam по URL без учётных данных
payram_troubleshoot	Опишите проблему или вставьте ошибку: известные причины, как подтвердить, исправление и следующий инструмент
payram_runbook	Задачи администратора: URL сайта, домен, SSL, брандмауэр, обновление, резервное копирование, цепочки, Smart Bridge, Shopify/WooCommerce
payram_ops_playbook	Рецепты API для второго дня эксплуатации, которые агент выполняет сам со своими учётными данными

Вокруг них находятся оценка кодовой базы, шаблоны стартовых приложений, многоязычные фрагменты кода и встроенная документация.

Размещённый сервер (mcp.payram.com) никогда не хранит учётные данные продавца. Операции второго дня выполняются через payram_ops_playbook: агент вызывает ваш API PayRam напрямую, и учётные данные никогда не покидают его машину. Инструменты для работы с живыми данными (поиск платежей, платёжные ссылки, синхронизация узлов, перезапуск воркеров) и assess_payram_project существуют только тогда, когда вы запускаете MCP самостоятельно в локальном режиме.

Для агентов и краулеров: карточка сервера · индекс навыков · llms.txt · карта сайта. Сервер также отвечает на Accept: text/markdown на / с читаемым для агента резюме.

---

Что такое PayRam? · PayRam 是什么？

PayRam — это самостоятельно размещаемый, мультичейновый криптоплатёжный шлюз, которым вы владеете полностью — без регистрации и без KYC/KYB для его работы. AI-агент (или разработчик) может развернуть магазин и начать принимать платежи без регистрации аккаунта у PayRam, банка или любого платёжного процессора. Разверните на собственном VPS, сгенерируйте API-ключи локально, запускайтесь.

Что делает его особенным:

• Никто не может вас заблокировать — нет аккаунта, который можно заблокировать, и нет средств, которые можно заморозить. Данные клиентов никогда не передаются, и ничего не сообщается и не отслеживается. Причина проста: PayRam работает на вашем сервере, а средства поступают в ваш собственный кошелёк.
• Развёртывание без разрешений — без регистрации, без KYC, без KYB. Никто вас не утверждает; никто не может вас отключить. Идеально для агентов, автономно создающих магазины, и для таких рынков, как Китай, где регистрация у западного процессора невозможна.
• Оплата картой в криптовалюту — покупатели без криптовалюты могут оплатить кредитной/дебетовой картой, а вы получаете криптовалюту, которая зачисляется прямо в ваш кошелёк с самостоятельным хранением. Это встроенный канал, который вы включаете на странице «Платежи»; поставщик карт проводит собственные проверки покупателя.
• Мультичейн — принимайте BTC, ETH, USDT, USDC и TRX нативно в сетях Bitcoin, Ethereum, Base, Polygon и Tron с автоматическим обнаружением депозитов, подтверждением в цепочке, переводом средств на холодное хранилище и подписанными вебхуками. Каналы Smart Bridge также принимают платежи в Solana, Bitcoin, Tron (USDT) и BNB Chain и зачисляют их как USDC в Base.
• Нет ключей депозита на сервере — смарт-контракты переводят депозиты на ваш холодный кошелёк, поэтому скомпрометированный сервер не сможет их перенаправить. Горячий кошелёк сервера оплачивает газ и подписывает выплаты, поэтому держите его баланс небольшим.

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

---

Как AI-агенты используют PayRam · AI 智能体如何使用 PayRam

PayRam — это инфраструктура, ориентированная на агентов (agent-first). Поскольку интеграция осуществляется через MCP, он работает с любой MCP-совместимой средой выполнения — OpenClaw, Hermes, Claude Desktop, Cursor, GitHub Copilot, n8n, LangChain и другими. Типичный поток работы агента:

1. Подключение — добавьте https://mcp.payram.com/mcp в MCP-конфигурацию агента (для подключения API-ключ не нужен).
2. Планирование — вызовите payram_setup_plan. Он вернёт упорядоченные шаги, кто выполняет каждый из них и где агент должен остановиться для человека (холодный кошелёк, газ в mainnet, настройки только для root).
3. Установка — на VPS, в интерактивном терминале, один раз выполните bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet (или --mainnet; установщик по умолчанию использует mainnet, поэтому всегда передавайте флаг). Никогда не передавайте его в bash.
4. Передача — человек немедленно забирает root-аккаунт и сохраняет Настройки → URL сайта с публичного домена; до этого момента платёжные ссылки указывают на http://localhost.
5. Проверка — payram_doctor с публичным URL (учётные данные не требуются).
6. Приём платежей — вставьте код интеграции для конкретного фреймворка из инструментов с фрагментами. Вебхуки подписаны (X-Payram-Signature, HMAC-SHA256 от исходного тела с API-ключом проекта).
7. Эксплуатация — payram_ops_playbook (daily_check, payment_options, node_sync, unswept_funds, create_payment_link, …) даёт агенту точные вызовы API для выполнения с его собственными учётными данными. payram_runbook охватывает изменения администратора.

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

Для пошагового руководства, специфичного для OpenClaw (регистрация, тестовая сеть Base Sepolia, паттерны chat-commerce для WhatsApp/Telegram/Discord), см. навык payram-openclaw-integration и 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 服务器从不保存商户凭证。

Если GitHub труднодоступен из вашей сети, вы можете зеркалировать этот репозиторий на другой Git-хостинг (git clone --mirror https://github.com/PayRam/payram-mcp.git). 如果你的网络难以访问 GitHub，可以把本仓库镜像到其他 Git 托管平台（git clone --mirror https://github.com/PayRam/payram-mcp.git）。

---

Содержание

• Что такое PayRam?
• Как AI-агенты используют PayRam
• Навыки агента
• Цели проекта
• Быстрый старт
• Подключение из вашего MCP-клиента
• Локальный режим
• Учётные данные
• Каталог инструментов
• Управляемые рабочие процессы
• Разработка
• Устранение неполадок

---

Навыки агента

Входная дверь агента: https://mcp.payram.com/SKILL.md — единый корневой навык, который описывает PayRam и направляет агентов к четырём стартовым инструментам. Также доступен: /llms.txt.

Этот репозиторий включает 19 навыков агента для AI-ассистентов по программированию. Установите их через skills.sh:

Установка по отдельности

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

Навык	Назначение
payram-setup	План установки и настройка сервера: требования, установщик, URL сайта, кошельки, первая платёжная ссылка
payram-agent-onboarding	Безголовая установка агентом: команды CLI агента, переменные окружения, передача человеку
payram-auth	Поток аутентификации JWT — вход, обновление токена, выход, детали внешних платформ
payram-analytics	Поиск платежей, объём, балансы и история переводов через прямые REST API (JWT)
payram-crypto-payments	Обзор архитектуры, почему PayRam, инструменты MCP
payram-payment-integration	Краткое руководство по интеграции платежей
payram-self-hosted-payment-gateway	Разверните и владейте своей платёжной инфраструктурой
payram-checkout-integration	Процесс оформления заказа с SDK + HTTP для 6 фреймворков
payram-widget-integration	Безопасная кнопка «Пополнить» (бэкенд-эндпоинт, никогда не публичный API-ключ) + обработчики подписанных вебхуков
payram-webhook-integration	Обработчики подписанных вебхуков (HMAC) для Express, Next.js, FastAPI, Gin, Laravel, Spring Boot
payram-stablecoin-payments	Приём USDT/USDC в EVM-цепочках и Tron
payram-bitcoin-payments	BTC с выводом HD-кошелька и мобильным подписанием
payram-payouts	Отправка криптовыплат и управление реферальными программами
payram-no-kyc-crypto-payments	Приём платежей без KYC, без регистрации, без разрешений
payram-openclaw-integration	Интеграция PayRam в OpenClaw / среды выполнения агентов — регистрация MCP, тестовая сеть, chat commerce
compare-crypto-payments	Сравнение шлюзов: Stripe, BitPay, Coinbase, NOWPayments, BTCPay, PayRam, x402
payram-agent-journey	Стартовая карта: установка (продавец или оператор) → кошельки → газ/переводы → интеграция → тест
payram-topup-wallet-integration	Существующие приложения: зачисление криптовалюты на баланс пользователя, списание по инвойсам — реестр + потоки
payram-testnet-testing	Оплата собственной платёжной ссылки в тестовой сети от начала до конца перед mainnet

---

Цели проекта

• Ускорить онбординг с помощью персонализированного плана настройки, инструкций, шаблонов окружения и плейбуков для каждого фреймворка.
• Работать без хранения учётных данных: размещённый сервер проверяет PayRam по URL (payram_doctor) и передаёт агентам точные рецепты API (payram_ops_playbook) для выполнения с их собственными учётными данными.
• Модернизировать существующие репозитории с помощью инструмента оценки проекта (локальный режим), который сканирует манифесты пакетов и файлы .env, а затем рекомендует подходящие фрагменты интеграции.
• Предоставлять готовые фрагменты кода для платежей, выплат, реферальных программ, вебхуков и многоязычных бэкендов (Express, Next.js, FastAPI, Laravel, Gin, Spring Boot и т. д.).
• Держать документацию локально, чтобы Copilot мог объяснять концепции PayRam, потоки и реферальные панели, не выходя из редактора.
• Проверять связь с помощью read-only проб, которые никогда не создают платежи (payram_doctor, test_payram_connection).

---

Быстрый старт

Большинству агентов нужна только размещённая конечная точка, https://mcp.payram.com/mcp (см. Подключение из вашего MCP-клиента). Чтобы запустить сервер самостоятельно:

1. Установите зависимости

   yarn install
   

2. Настройте окружение (только для инструментов локального режима данных)
   • Скопируйте .env.example в .env.
   • Установите PAYRAM_BASE_URL на ваш PayRam URL, тот же источник, что и панель управления (например, https://pay.example.com).
   • Установите PAYRAM_API_KEY, а также JWT-переменные для инструментов данных. См. Локальный режим.
3. Запустите сервер

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

4. Добавьте MCP-сервер в ваш клиент: см. Подключение из вашего MCP-клиента. URL локального режима: http://localhost:3333/mcp.
5. Проверка работоспособности

   curl http://localhost:3333/healthz
   

Совет: Когда вы говорите Copilot "test payram", он автоматически запускает контрольный список готовности, убеждается, что .env существует, и только затем вызывает test_payram_connection с вашими реальными учетными данными. Поведение определяется автоматизационным промптом Copilot — ручной ввод не требуется.

---

Подключение из вашего MCP-клиента

Конечная точка: https://mcp.payram.com/mcp (Streamable HTTP, JSON-RPC через POST). SSE-конечной точки нет, и /mcp/sse возвращает 410. Без заголовков аутентификации: размещенный сервер никогда не хранит учетные данные продавца, поэтому ваши остаются на вашей машине и никогда не попадают в чат.

Клиент	Где	Настройки
VS Code (Copilot Chat)	Настройки → Copilot: Model Context Protocol → Add HTTP server	Имя payram, URL выше, заголовки пустые
Cursor	Настройки → MCP Servers → Add → HTTP	Имя payram, URL выше
Claude Desktop / Code	Настройки → MCP Servers → Add HTTP server	Имя payram, URL выше
Любой MCP-клиент	Зарегистрируйте HTTP-конечную точку	URL выше, без заголовков

Проверка: список инструментов должен начинаться с payram_setup_plan, payram_doctor, payram_troubleshoot, payram_runbook и payram_ops_playbook, за которыми следуют scaffold_payram_app и инструменты фрагментов generate_*. Затем попробуйте: "plan a PayRam install on pay.example.com", "check https://pay.example.com", "generate a FastAPI create-payment route", "give me a Next.js webhook handler".

Промпты: setup-payram, setup-payram-agent, integrate-payment, troubleshoot-payment, daily-ops. Ресурсы: payram://docs/setup-guide, payram://docs/api-reference, а также шаблоны payram://ops/playbook/{task} и payram://runbooks/{task}.

Автоматизационный промпт Copilot

Вставьте это один раз в новое рабочее пространство, чтобы "test payram" автоматически запускал полный процесс готовности:

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.

---

Локальный режим

Запустите MCP рядом с вашим собственным PayRam, чтобы получить живые инструменты данных:

• 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

• Режим: PAYRAM_MCP_MODE=local выбирает локальный режим. Он также используется по умолчанию, когда сервер не запущен на Vercel. PAYRAM_MCP_MODE=hosted никогда не читает учетные данные.
• Привязка: локальный режим по умолчанию привязывается к 127.0.0.1 (порт PORT, по умолчанию 3333).
• Привязки вне loopback: установите HOST (например, HOST=0.0.0.0), затем:
  • Установите MCP_ALLOWED_HOSTS (имена хостов через запятую, принимаемые в заголовке Host).
  • Установите MCP_SERVER_TOKEN; клиенты затем отправляют Authorization: Bearer <token>.
  • Если установлены учетные данные PAYRAM_*, сервер отказывается запускаться на HOST вне loopback без MCP_SERVER_TOKEN. Предпочитайте loopback с SSH-туннелем.
• Учетные данные: инструменты данных читают PAYRAM_* из окружения (или .env):
  • PAYRAM_BASE_URL
  • PAYRAM_API_KEY (платежные ссылки)
  • PAYRAM_ACCESS_TOKEN / PAYRAM_REFRESH_TOKEN (JWT, инструменты данных)
  • PAYRAM_EXTERNAL_PLATFORM_ID (необязательный проект по умолчанию)

Пример конфигурации клиента для локального сервера (только локальный режим):

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

---

Учетные данные: какой ключ для чего

PayRam имеет два учетных данных — агенты зависают, когда их путают:

Учетные данные	Выглядят как	Используются для	Как агент их получает (без панели управления)
Merchant API key (PAYRAM_API_KEY, заголовок API-Key)	ключ на проект	POST /api/v1/payment (платежные ссылки), выплаты продавцу, все серверные вызовы продавца, а также подписывает вебхуки (X-Payram-Signature)	bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) ensure-api-key — повторно использует или создает ключ проекта через POST /api/v1/external-platform/{id}/api-key и сохраняет его в ~/.payraminfo/merchant-api-key.env
JWT (Authorization: Bearer)	access+refresh токен от входа	API администрирования/настройки (проекты, кошельки, аналитика) — рецепты payram_ops_playbook и инструменты локального режима данных	bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) signin (env PAYRAM_EMAIL/PAYRAM_PASSWORD); сохраняется в ~/.payraminfo/headless-tokens.env

Одношаговый процесс настройки (bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet) создает оба автоматически и выводит, где они находятся. API находится на том же источнике, что и панель управления, на порту 80/443 (https://<your-domain>/api/v1/..., или http://localhost на сервере, никогда :8080). API-ключ может создавать выплаты, поэтому храните его на стороне сервера и никогда не помещайте в код браузера или чат. Используйте задачу payram_ops_playbook connect, чтобы настроить оба для прямых вызовов API.

---

Каталог инструментов

Категория	Инструмент	Назначение
Начните здесь – Установка	payram_setup_plan	Персонализированный упорядоченный план установки (подготовка → установка → получение root и Site URL → кошельки + Smart Bridge → API-ключ + первая ссылка → усиление → интеграция) с шагами агента и человека, а также обязательными остановками.
Начните здесь – Диагностика	payram_doctor, payram_troubleshoot	payram_doctor: публичная, не требующая учетных данных поэтапная проверка по URL (доступность → работоспособность → TLS → версия → воркеры) с ранжированными вероятными причинами + точными исправлениями. Необязательная проверка действительности API-ключа, которая ничего не создает. Запускайте ЭТО ПЕРВЫМ при любом сбое. payram_troubleshoot: сопоставление симптома или вставленной ошибки с известными причинами и исправлениями.
Начните здесь – Администрирование	payram_runbook	Пошаговые административные задачи с человеческими проверками: 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.
Начните здесь – Операции	payram_ops_playbook	Рецепты прямого API, которые агент выполняет сам: 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.
Связь	test_payram_connection	Проверка доступности/работоспособности только для чтения плюс необязательная проверка API-ключа. Никогда не создает платежи.
Настройка	generate_env_template, generate_setup_checklist, suggest_file_structure, get_agent_setup_flow, onboard_agent_setup	Предоставляет шаблоны env, чек-листы мерчанта, рекомендуемые структуры проектов и руководство по онбордингу headless-агента.
Контекст / Документация	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, и т.д.	Предоставляют встроенные знания в формате Markdown из docs/, чтобы Copilot мог отвечать на концептуальные вопросы. Некоторые инструменты автоматически добавляют напоминания «скажите test payram».
Интеграция – Платежи	generate_payment_sdk_snippet, generate_payment_http_snippet, generate_payment_status_snippet, generate_payment_route_snippet	Генерируют код SDK, raw HTTP или маршрутов Express/Next.js для потоков создания и проверки статуса.
Интеграция – Выплаты	generate_payout_sdk_snippet, generate_payout_recipient_flow_snippet, generate_payout_status_snippet	Прямая выплата (без OTP), 3-шаговый поток сохраненного получателя (создать получателя → подтвердить OTP → выплатить) и опрос статуса.
Интеграция – Рефералы	generate_referral_sdk_snippet, generate_referral_validation_snippet, generate_referral_status_snippet, generate_referral_route_snippet	Охватывают реферальную аутентификацию, привязку, проверку, статус и маршруты express/next.
Интеграция – Вебхуки	generate_webhook_handler, generate_webhook_event_router, generate_mock_webhook_event	Создают обработчики для Express/Next/FastAPI/Gin/Laravel/Spring Boot, маршрутизаторы fan-out и тестеры вебхуков на cURL/Python/Go/PHP/Java.
Интеграция – Многоязычные платежи	семейство 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)	Готовые обработчики маршрутов для Express, Next.js App Router, FastAPI, Gin, Laravel и Spring Boot.
Интеграция – Пополнение кошелька	generate_topup_integration_snippet	Для СУЩЕСТВУЮЩИХ приложений: схема ledger + вебхук кумулятивного кредита + атомарное закрытие инвойса, чтобы переплаты/недоплаты/задержки/дубликаты криптоплатежей становились состояниями баланса, а не платежными исключениями. Сочетается с навыком payram-topup-wallet-integration.
Интеграция – Оценка проекта (локальный режим)	assess_payram_project	Сканирует package.json, requirements.txt, composer.json, go.mod, pom.xml, .env и т.д. Сообщает об обнаруженных фреймворках, статусе env, зависимостях PayRam и приоритетных следующих шагах с предложениями инструментов.
Скаффолдинг	scaffold_payram_app	Генерирует полные стартовые приложения (Express, Next.js, FastAPI, Laravel, Gin, Spring Boot) с платежами, выплатами, вебхуками и браузерной консолью. Перед развертыванием поместите эндпоинты выплат за собственную административную аутентификацию.
Живые данные (только чтение, локальный режим)	list_platforms, search_payments, lookup_payment, get_payment_summary, get_daily_volume, get_unswept_balances, list_currencies, list_recipients	Запросы к живым данным PayRam. list_currencies является публичным (без ключа); остальные используют JWT-токены из .env. list_recipients сочетается с потоком получателя выплат.
Живые операции (локальный режим)	create_payment_link (запись), check_payment_readiness, check_node_sync, restart_payram_worker (запись)	create_payment_link создает реальную ссылку для оплаты через API-Key. check_payment_readiness сообщает о пробелах по цепочкам (отсутствующий кошелек / валюта / слушатель) для приема платежей. check_node_sync сообщает о работоспособности слушателя-воркера + RPC-ноды и устаревании блоков. На хостинг-сервере используйте соответствующие задачи payram_ops_playbook.

Регистрации инструментов находятся в src/tools/index.ts; отдельные реализации расположены в src/tools/** с языковыми шаблонами в папках templates/.

---

Управляемые рабочие процессы

0. Установка PayRam

1. Спросите: «Настройте PayRam на pay.example.com» (или используйте подсказки setup-payram / setup-payram-agent).
2. Ассистент вызывает payram_setup_plan и проходит фазы, останавливаясь на каждом человеческом шаге (root-аккаунт, Site URL, холодный кошелек, газ mainnet).
3. Завершает с помощью payram_doctor, резервных копий (payram_runbook backup) и ежедневной проверки (payram_ops_playbook daily_check).

1. Оценка и модернизация существующего проекта

1. Спросите Copilot: «Можете интегрировать PayRam в этот проект?»
2. Ассистент запускает assess_payram_project (локальный режим), проверяя манифесты зависимостей и .env.
3. Следуйте рекомендованным шагам (установите payram, запросите фрагменты маршрутов Express/FastAPI/Spring, добавьте вебхуки и т. д.).
4. Используйте test_payram_connection, когда учетные данные станут реальными, чтобы убедиться, что бэкенд может связаться с вашим самостоятельно размещенным сервером.

2. Создайте новый пример с нуля

1. «Создайте демо PayRam Express» → scaffold_payram_app создает проект Express с платежами, выплатами, вебхуками и консолью пользовательского интерфейса.
2. Поместите сгенерированные файлы в пустой репозиторий или сравните с существующим каталогом для эталонной настройки.

3. Запустите поток готовности «Тест PayRam»

1. Скажите «test payram». Ассистент автоматически:
   • Вызывает prepare_payram_test, чтобы поделиться контрольным списком готовности.
   • Убеждается, что .env существует (создавая его, если отсутствует), используя generate_env_template.
   • Ожидает реальные учетные данные перед вызовом test_payram_connection.
2. Просмотрите структурированный результат JSON, чтобы подтвердить доступность API PayRam.

4. Настройте платежи, выплаты, реферальные программы и вебхуки

• Платежи: generate_payment_sdk_snippet (JS SDK) или generate_payment_http_snippet (Python/Go/PHP/Java).
• Многоязычные маршруты: snippet_nextjs_payment_route, snippet_fastapi_payment_route и т. д.
• Выплаты: generate_payout_sdk_snippet для создания + generate_payout_status_snippet для опроса.
• Реферальные программы: generate_referral_route_snippet, generate_referral_validation_snippet.
• Вебхуки: generate_webhook_handler плюс generate_webhook_event_router для рассылки + generate_mock_webhook_event для тестирования каждого статуса.

---

Разработка

Команда	Описание
yarn dev	Запуск MCP-сервера с горячей перезагрузкой через tsx.
yarn build	Компиляция TypeScript в dist/.
yarn lint / yarn format	ESLint + Prettier по всему репозиторию.
yarn test	Выполнение набора тестов Vitest (tests/).
make precommit-test	Последовательный запуск format → lint → test → build.

Проект ориентирован на TypeScript (ESM). Конфигурация Prettier находится в .prettierrc.json; ESLint настраивается через eslint.config.mjs. Гладкие вклады следуют помощнику коммитов в Makefile → make commit.

---

Устранение неполадок

Начните с payram_doctor — один вызов только для чтения, который проверяет доступность → здоровье → TLS → версию → воркеры и возвращает ранжированные причины с точными исправлениями. Для более глубоких проверок следуйте payram_ops_playbook (stuck_payment, node_sync, webhooks, logs).

• Copilot не вызывает нужный инструмент: Проверьте, что подсказка автоматизации Copilot установлена, и ваш MCP-клиент загрузил сервер. Повторно запустите «test payram» или «assess my project», чтобы активировать ожидаемую автоматизацию.
• test_payram_connection завершается с ошибкой 401: Убедитесь, что ключ является активным ключом API проекта (отправляется как заголовок API-Key, а не Authorization).
• Инструмент данных сообщает, что учетные данные недоступны: размещенный сервер никогда не хранит учетные данные продавца. Используйте соответствующую задачу payram_ops_playbook или запустите MCP в локальном режиме.
• Платежные ссылки показывают http://localhost: человек должен сохранить Settings → Site URL с публичного домена (задача payram_runbook set_site_url).
• Инструмент документации сообщает, что файл отсутствует: Проверьте, что ваше локальное дерево docs/payram-docs-live/ содержит запрошенный markdown (get_payram_doc_by_id отклоняет пути с ..).
• Сервер не запускается: Убедитесь, что Node 20+ установлен, и выполните yarn install. В локальном режиме с не-loopback HOST и установленными учетными данными PAYRAM_* сервер отказывается запускаться, пока не установлен MCP_SERVER_TOKEN (см. Локальный режим).

Для всего остального проверьте структурированные журналы, выводимые из src/utils/logger.ts (установите LOG_LEVEL=debug), и откройте issue/PR с деталями воспроизведения.