PayRam Crypto Card Payment Gateway
공식에이전트, 오픈클로, 헤르메스 등을 위한 자체 호스팅 결제 게이트웨이
PayRam Crypto Card Payment Gateway MCP(으)로 무엇을 할 수 있나요?
- 개인화된 설치 계획 수립 —
payram_setup_plan을 통해 사람의 개입이 포함된 단계별 PayRam 배포 계획을 요청하세요. - 서버 상태 진단 —
payram_doctor를 사용하여 자격 증명 없이 모든 PayRam URL을 점검하고 문제와 해결 방법을 파악하세요. - 오류 문제 해결 — 오류 또는 증상을 붙여넣어
payram_troubleshoot를 통해 알려진 원인, 확인 사항, 다음 단계를 확인하세요. - 관리자 런북 받기 —
payram_runbook에서 SSL, 백업, 도메인 변경과 같은 단계별 관리자 작업을 요청하세요. - 2일차 운영 실행 — 에이전트가
payram_ops_playbook을 통해 일일 점검, 노드 동기화, 결제 링크용 API 레시피를 실행하게 하세요. - 통합 코드 생성 — Express 또는 Next.js와 같은 프레임워크용 복사-붙여넣기 결제, 지급, 웹훅 스니펫을 요청하세요.
문서
PayRam MCP 서버 — 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 | URL로 PayRam 서버를 확인하는 공개적이고 자격 증명이 필요 없는 점검 |
payram_troubleshoot | 문제 설명 또는 오류 붙여넣기: 알려진 원인, 확인 방법, 해결책, 다음 도구 |
payram_runbook | 관리 작업: 사이트 URL, 도메인, SSL, 방화벽, 업그레이드, 백업, 체인, Smart Bridge, Shopify/WooCommerce |
payram_ops_playbook | 에이전트가 자체 자격 증명으로 직접 실행하는 Day-2 API 레시피 |
그 주변에는 코드베이스 평가, 스타터 앱 스캐폴드, 다국어 스니펫 및 인라인 문서가 있습니다.
호스팅 서버(mcp.payram.com)는 판매자 자격 증명을 절대 보유하지 않습니다. Day-2 작업은 payram_ops_playbook를 통해 실행됩니다: 에이전트가 PayRam API를 직접 호출하며, 자격 증명은 에이전트의 머신을 벗어나지 않습니다. 실시간 데이터 도구(결제 검색, 결제 링크, 노드 동기화, 작업자 재시작) 및 assess_payram_project는 로컬 모드에서 MCP를 직접 실행할 때만 존재합니다.
에이전트 및 크롤러용: 서버 카드 · 스킬 인덱스 · llms.txt · 사이트맵. 서버는 또한 /에서 Accept: text/markdown에 에이전트가 읽을 수 있는 요약으로 응답합니다.
PayRam이란 무엇인가요? · PayRam 是什么？
PayRam은 완전히 자체 호스팅되는 멀티체인 암호화폐 결제 게이트웨이로, 가입이나 KYC/KYB 없이 운영할 수 있습니다. AI 에이전트(또는 개발자)는 PayRam, 은행 또는 어떤 결제 처리업체에도 계정을 등록하지 않고 상점을 세우고 결제를 받기 시작할 수 있습니다. 자체 VPS에 배포하고, 로컬에서 API 키를 생성하고, 바로 운영을 시작하세요.
차별점:
- 아무도 당신을 잠글 수 없습니다 — 잠글 계정도, 동결할 자금도 없습니다. 고객 데이터는 절대 공유되지 않으며, 어떤 보고나 모니터링도 없습니다. 이유는 간단합니다: PayRam은 당신의 서버에서 실행되고 자금은 당신의 지갑에 도착합니다.
- 허가 없는 설정 — 가입 없음, KYC 없음, KYB 없음. 누구도 당신을 승인하지 않으며, 누구도 당신을 차단할 수 없습니다. 에이전트가 자율적으로 상점을 세우는 경우와 중국과 같이 서양 결제 처리업체에 등록할 수 없는 시장에 이상적입니다.
- 카드-투-암호화폐 체크아웃 — 암호화폐가 없는 구매자는 신용/직불 카드로 결제할 수 있고, 당신은 자체 보관 지갑으로 직접 정산되는 암호화폐를 받습니다. Payments 페이지에서 켜는 내장 채널입니다; 카드 제공업체가 구매자에 대한 자체 검사를 실행합니다.
- 멀티체인 — Bitcoin, Ethereum, Base, Polygon, Tron에서 BTC, ETH, USDT, USDC, TRX를 기본 지원하며, 자동 입금 감지, 온체인 확인, 콜드 스토리지로의 스윕, 서명된 웹훅을 제공합니다. Smart Bridge 레일은 Solana, Bitcoin, Tron(USDT) 및 BNB Chain에서도 결제를 받아 Base에서 USDC로 정산합니다.
- 서버에 입금 키 없음 — 스마트 계약이 입금을 콜드 월렛으로 스윕하므로, 서버가 손상되어도 자금을 다른 곳으로 보낼 수 없습니다. 서버의 핫 월렛은 가스비를 지불하고 출금에 서명하므로 잔액을 작게 유지하세요.
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를 통해 이루어지므로 OpenClaw, Hermes, Claude Desktop, Cursor, GitHub Copilot, n8n, LangChain 등 MCP를 지원하는 모든 런타임과 작동합니다. 일반적인 에이전트 흐름:
- 연결 — 에이전트의 MCP 구성에
https://mcp.payram.com/mcp을 추가합니다(연결만 하려면 API 키가 필요 없음). - 계획 —
payram_setup_plan을 호출합니다. 순서가 지정된 단계, 각 단계를 실행할 주체, 에이전트가 인간을 위해 멈춰야 하는 지점(콜드 월렛, 메인넷 가스, 루트 전용 설정)을 반환합니다. - 설치 — VPS에서 대화형 터미널에서 한 번
bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet(또는--mainnet; 설치 프로그램 기본값은 메인넷이므로 항상 플래그를 전달하세요)을 실행합니다. 절대bash으로 파이프하지 마세요. - 인계 — 인간이 즉시 루트 계정을 확보하고 공개 도메인에서 설정 → 사이트 URL을 저장합니다; 그때까지 결제 링크는
http://localhost을 가리킵니다. - 확인 — 공개 URL로
payram_doctor을 실행합니다(자격 증명 불필요). - 결제 수락 — 스니펫 도구에서 프레임워크별 통합 코드를 붙여넣습니다. 웹훅은 서명됩니다(
X-Payram-Signature, 프로젝트 API 키를 사용한 원시 본문의 HMAC-SHA256). - 운영 —
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 테스트넷, 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.
이 저장소에는 AI 코딩 어시스턴트를 위한 19개의 에이전트 스킬이 포함되어 있습니다. 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 | 6개 프레임워크용 SDK + HTTP 체크아웃 흐름 |
payram-widget-integration | 안전한 "크레딧 추가" 버튼(백엔드 엔드포인트, 공개 API 키 절대 사용 금지) + 서명된 웹훅 핸들러 |
payram-webhook-integration | Express, Next.js, FastAPI, Gin, Laravel, Spring Boot용 서명된 웹훅(HMAC) 핸들러 |
payram-stablecoin-payments | EVM 체인 및 Tron에서 USDT/USDC 수락 |
payram-bitcoin-payments | HD 지갑 파생 및 모바일 서명을 통한 BTC |
payram-payouts | 암호화폐 출금 전송 및 추천 프로그램 관리 |
payram-no-kyc-crypto-payments | KYC 없음, 가입 없음, 허가 없는 결제 수락 |
payram-openclaw-integration | PayRam을 OpenClaw / 에이전트 런타임에 통합 — MCP 등록, 테스트넷, 채팅 커머스 |
compare-crypto-payments | 게이트웨이 비교: Stripe, BitPay, Coinbase, NOWPayments, BTCPay, PayRam, x402 |
payram-agent-journey | 시작 맵: 설치(판매자 또는 운영자) → 지갑 → 가스/스윕 → 통합 → 테스트 |
payram-topup-wallet-integration | 기존 앱: 사용자 잔액에 암호화폐 크레딧, 인보이스 차변 — 원장 + 흐름 |
payram-testnet-testing | 메인넷 전에 테스트넷에서 자체 결제 링크를 종단 간 결제 |
프로젝트 목표
- 온보딩 가속화 — 맞춤형 설정 계획, 런북, 환경 템플릿 및 프레임워크별 플레이북 제공.
- 자격 증명 없이 운영 — 호스팅 서버는 URL로 PayRam을 확인하고(
payram_doctor) 에이전트에게 자체 자격 증명으로 실행할 정확한 API 레시피(payram_ops_playbook)를 제공합니다. - 기존 저장소 개조 — 프로젝트 평가 도구(로컬 모드)를 통해 패키지 매니페스트와
.env파일을 스캔한 후 올바른 통합 스니펫을 추천합니다. - 복사/붙여넣기 스니펫 제공 — Payments, Payouts, Referrals, Webhooks 및 다국어 백엔드(Express, Next.js, FastAPI, Laravel, Gin, Spring Boot 등) 포괄.
- 문서를 로컬로 유지 — Copilot이 편집기를 벗어나지 않고 PayRam 개념, 흐름 및 추천 대시보드를 설명할 수 있도록.
- 연결성 검증 — 결제를 생성하지 않는 읽기 전용 프로브로 확인(
payram_doctor,test_payram_connection).
빠른 시작
대부분의 에이전트는 호스팅 엔드포인트 https://mcp.payram.com/mcp만 필요합니다(MCP 클라이언트에서 연결 참조). 서버를 직접 실행하려면:
- 의존성 설치
yarn install - 환경 구성 (로컬 모드 데이터 도구에만 필요)
.env.example을(를).env에 복사합니다.PAYRAM_BASE_URL을(를) 대시보드와 동일한 출처인 PayRam URL로 설정합니다 (예:https://pay.example.com).PAYRAM_API_KEY및 데이터 도구용 JWT 변수를 설정합니다. 로컬 모드를 참조하세요.
- 서버 실행
yarn dev # Streamable HTTP on http://127.0.0.1:3333/mcp (local mode; there is no SSE transport) - 클라이언트에 MCP 서버 추가: MCP 클라이언트에서 연결을 참조하세요. 로컬 모드 URL은
http://localhost:3333/mcp입니다. - 상태 확인
curl http://localhost:3333/healthz
팁: Copilot에 "test payram"이라고 말하면 자동으로 준비 상태 체크리스트를 실행하고,
.env이(가) 존재하는지 확인한 후에만 실제 자격 증명으로test_payram_connection을(를) 호출합니다. 이 동작은 Copilot 자동화 프롬프트에 정의되어 있습니다—수동 프롬프트가 필요 없습니다.
MCP 클라이언트에서 연결
엔드포인트: https://mcp.payram.com/mcp (Streamable HTTP, POST를 통한 JSON-RPC). SSE 엔드포인트는 없으며, /mcp/sse은(는) 410을 반환합니다. 인증 헤더 없음: 호스팅 서버는 판매자 자격 증명을 보관하지 않으므로, 자격 증명은 사용자 머신에만 남아 채팅으로 전송되지 않습니다.
| 클라이언트 | 위치 | 설정 |
|---|---|---|
| VS Code (Copilot Chat) | 설정 → Copilot: Model Context Protocol → HTTP 서버 추가 | 이름 payram, 위 URL, 헤더 비어 있음 |
| Cursor | 설정 → MCP 서버 → 추가 → HTTP | 이름 payram, 위 URL |
| Claude Desktop / Code | 설정 → MCP 서버 → HTTP 서버 추가 | 이름 payram, 위 URL |
| 모든 MCP 클라이언트 | HTTP 엔드포인트 등록 | 위 URL, 헤더 없음 |
확인: 도구 목록은 payram_setup_plan, payram_doctor, payram_troubleshoot, payram_runbook, payram_ops_playbook(으)로 시작하고, 그 뒤에 scaffold_payram_app 및 generate_* 스니펫 도구가 이어져야 합니다. 그런 다음 "pay.example.com에 PayRam 설치 계획", "https://pay.example.com 확인", "FastAPI 결제 생성 라우트 생성", "Next.js 웹훅 핸들러 제공"을 시도해 보세요.
프롬프트: 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.
로컬 모드
자체 PayRam 옆에서 MCP를 실행하여 실시간 데이터 도구를 사용하세요:
list_platforms,search_payments,lookup_payment,get_payment_summary,get_daily_volume,get_unswept_balances,list_currencies,list_recipientscreate_payment_link,check_payment_readiness,check_node_sync,restart_payram_workerassess_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). - 비루프백 바인딩:
HOST을(를) 설정한 경우 (예:HOST=0.0.0.0), 그런 다음:MCP_ALLOWED_HOSTS을(를) 설정합니다 (Host헤더에서 허용되는 쉼표로 구분된 호스트 이름).MCP_SERVER_TOKEN을(를) 설정합니다; 클라이언트는Authorization: Bearer <token>을(를) 보냅니다.PAYRAM_*자격 증명이 설정된 경우, 서버는MCP_SERVER_TOKEN없이 비루프백HOST에서 시작을 거부합니다. 루프백과 SSH 터널을 선호하세요.
- 자격 증명: 데이터 도구는 환경(또는
.env)에서PAYRAM_*을(를) 읽습니다:PAYRAM_BASE_URLPAYRAM_API_KEY(결제 링크)PAYRAM_ACCESS_TOKEN/PAYRAM_REFRESH_TOKEN(JWT, 데이터 도구)PAYRAM_EXTERNAL_PLATFORM_ID(선택적 기본 프로젝트)
로컬 서버용 예제 클라이언트 구성 (로컬 모드 전용):
{
"mcpServers": {
"payram-local": { "url": "http://localhost:3333/mcp" }
}
}
자격 증명: 어떤 키가 무엇에 사용되는가
PayRam에는 두 가지 자격 증명이 있습니다 — 에이전트가 이를 혼동하면 멈춥니다:
| 자격 증명 | 형태 | 용도 | 에이전트가 얻는 방법 (대시보드 불필요) |
|---|---|---|---|
판매자 API 키 (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) | 로그인에서 액세스+리프레시 토큰 | 관리자/설정 API (프로젝트, 지갑, 분석) — payram_ops_playbook 레시피 및 로컬 모드 데이터 도구 | bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) signin (환경 변수 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 | 개인화된 순서형 설치 계획(준비 → 설치 → 루트 + 사이트 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 | 환경 변수 보일러플레이트, 판매자 체크리스트, 권장 프로젝트 레이아웃, 헤드리스 에이전트 온보딩 가이드를 제공합니다. |
| 컨텍스트 / 문서 | 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, 등. | docs/에서 가져온 인라인 Markdown 지식을 제공하여 Copilot이 개념적 질문에 답할 수 있게 합니다. 일부 도구는 자동으로 "test payram라고 말하세요" 알림을 추가합니다. |
| 통합 – 결제 | generate_payment_sdk_snippet, generate_payment_http_snippet, generate_payment_status_snippet, generate_payment_route_snippet | 생성 + 상태 흐름에 대한 SDK, 원시 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용 핸들러, 팬아웃 라우터, 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 | 기존 앱용: 원장 스키마 + 누적 크레딧 웹훅 + 원자적 인보이스 정산으로, 초과/부족/지연/중복 암호화폐 결제가 결제 예외가 아닌 잔액 상태가 됩니다. payram-topup-wallet-integration 스킬과 함께 사용합니다. |
| 통합 – 프로젝트 평가 (로컬 모드) | assess_payram_project | package.json, requirements.txt, composer.json, go.mod, pom.xml, .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은 공개(키 없음)이며, 나머지는 .env의 JWT 토큰을 사용합니다. 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 설치
- "pay.example.com에 PayRam을 설정해 줘"라고 요청합니다(또는
setup-payram/setup-payram-agent프롬프트 사용). - 어시스턴트가
payram_setup_plan을 호출하고 단계를 진행하며 모든 사람 단계(루트 계정, 사이트 URL, 콜드 지갑, 메인넷 가스)에서 중지합니다. payram_doctor, 백업(payram_runbookbackup) 및 일일 점검(payram_ops_playbookdaily_check)으로 마무리합니다.
1. 기존 프로젝트 평가 및 개조
- Copilot에게 "이 프로젝트에 PayRam을 통합해 줄 수 있나요?"라고 요청하세요.
- 어시스턴트가
assess_payram_project(로컬 모드)을 실행하여 의존성 매니페스트와.env를 검토합니다. - 권장 단계를 따르세요 (
payram설치, Express/FastAPI/Spring 라우트 스니펫 요청, 웹훅 추가 등). - 자격 증명이 실제로 준비되면
test_payram_connection을 사용하여 백엔드가 자체 호스팅 서버에 도달할 수 있는지 확인하세요.
2. 새 샘플 스캐폴드 생성
- "PayRam Express 데모를 만들어 줘"라고 말하면
scaffold_payram_app이 결제, 지급, 웹훅 및 UI 콘솔이 포함된 Express 프로젝트를 빌드합니다. - 생성된 파일을 빈 저장소에 넣거나 기존 디렉터리와 비교하여 참조 배선을 확인하세요.
3. "PayRam 테스트" 준비 흐름 실행
- "test payram"이라고 말하세요. 어시스턴트가 자동으로:
prepare_payram_test을 호출하여 준비 체크리스트를 공유합니다.generate_env_template을 사용하여.env이 존재하는지 확인합니다 (없으면 생성).- 실제 자격 증명을 기다린 후
test_payram_connection을 호출합니다.
- 구조화된 JSON 결과를 검토하여 PayRam API에 연결할 수 있는지 확인하세요.
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 | tsx을 통해 핫 리로드로 MCP 서버 실행. |
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 키인지 확인하세요 (Authorization가 아닌API-Key헤더로 전송).- 데이터 도구가 자격 증명을 사용할 수 없다고 표시: 호스팅 서버는 판매자 자격 증명을 보유하지 않습니다. 일치하는
payram_ops_playbook작업을 사용하거나 로컬 모드에서 MCP를 실행하세요. - 결제 링크에
http://localhost표시: 공개 도메인에서 설정 → 사이트 URL을 저장해야 합니다 (payram_runbook작업set_site_url). - 문서 도구가 파일 누락을 표시: 로컬
docs/payram-docs-live/트리에 요청된 마크다운이 포함되어 있는지 확인하세요 (get_payram_doc_by_id은..이 있는 경로를 거부). - 서버가 시작되지 않음: Node 20+를 확인하고
yarn install을 실행하세요. 비루프백HOST및PAYRAM_*자격 증명이 설정된 로컬 모드에서 서버는MCP_SERVER_TOKEN이 설정될 때까지 시작을 거부합니다 (로컬 모드 참조).
그 외의 경우 src/utils/logger.ts에서 출력되는 구조화된 로그를 검사하고 (LOG_LEVEL=debug 설정) 재현 세부 정보와 함께 이슈/PR을 열어주세요.