PayRam Crypto Card Payment Gateway

PayRam MCP Sunucusu — Yapay Zeka Ajanları için Kendi Kendine Barındırılan Kripto Ödemeler

Kendi kendine barındırılan kripto ve stablecoin ödemeleri: hesap kilidi yok, fon dondurma yok, müşteri verileri asla paylaşılmaz. Yapay zeka ajanınız MCP üzerinden planlayabilir, kurabilir ve işletebilir. Barındırılan uç nokta: https://mcp.payram.com/mcp · Web Sitesi · Dokümanlar · Ajan · OpenClaw

Bir MCP (Model Context Protocol) sunucusu — MCP uyumlu herhangi bir yapay zeka ajanının — OpenClaw, Hermes, Claude, Cursor, GitHub Copilot ve diğerlerinin — kendi kendine barındırılan bir PayRam kripto ödeme yığınını dağıtmasını, entegre etmesini ve işletmesini sağlar.

Buradan başlayın: dört araç kataloğa öncülük eder:

Araç	Ne yapar
payram_setup_plan	Her insan devir tesliminin işaretlendiği kişiselleştirilmiş bir kurulum planı
payram_doctor	Bir PayRam sunucusunun URL ile kimlik bilgisi gerektirmeyen herkese açık kontrolü
payram_troubleshoot	Bir sorunu tanımlayın veya bir hata yapıştırın: bilinen nedenler, nasıl doğrulanacağı, çözüm ve sonraki araç
payram_runbook	Yönetici görevleri: Site URL'si, alan adı, SSL, güvenlik duvarı, yükseltme, yedekleme, zincirler, Smart Bridge, Shopify/WooCommerce
payram_ops_playbook	Ajanın kendi kimlik bilgileriyle kendisinin çalıştırdığı 2. gün API tarifleri

Bunların çevresinde kod tabanı değerlendirmesi, başlangıç uygulaması iskeletleri, çok dilli kod parçacıkları ve satır içi dokümanlar bulunur.

Barındırılan sunucu (mcp.payram.com) asla tüccar kimlik bilgilerini tutmaz. 2. gün işlemleri payram_ops_playbook üzerinden çalışır: ajan PayRam API'nizi doğrudan çağırır ve kimlik bilgileri makinesinden asla çıkmaz. Canlı veri araçları (ödeme araması, ödeme bağlantıları, düğüm senkronizasyonu, çalışan yeniden başlatma) ve assess_payram_project yalnızca MCP'yi yerel modda kendiniz çalıştırdığınızda mevcuttur.

Ajanlar ve tarayıcılar için: sunucu kartı · beceri dizini · llms.txt · site haritası. Sunucu ayrıca / üzerinde Accept: text/markdown ajan tarafından okunabilir bir özetle yanıtlar.

---

PayRam nedir? · PayRam 是什么？

PayRam, tamamen sahip olduğunuz, kendi kendine barındırılan, çok zincirli bir kripto ödeme ağ geçididir — çalıştırmak için kayıt ve KYC/KYB gerekmez. Bir yapay zeka ajanı (veya bir geliştirici), PayRam, bir banka veya herhangi bir ödeme işlemcisinde hesap açmadan bir mağaza kurabilir ve ödeme kabul etmeye başlayabilir. Kendi VPS'inizde dağıtın, API anahtarlarını yerel olarak oluşturun, canlıya geçin.

Fark yaratan özellikler:

• Kimse sizi kilitleyemez — kilitlenecek hesap ve dondurulacak fon yoktur. Müşteri verileri asla paylaşılmaz ve hiçbir şey raporlanmaz veya izlenmez. Nedeni basit: PayRam sizin sunucunuzda çalışır ve fonlar kendi cüzdanınıza ulaşır.
• İzinsiz kurulum — kayıt yok, KYC yok, KYB yok. Kimse sizi onaylamaz; kimse sizi kapatamaz. Mağazaları otonom olarak kuran ajanlar ve Batılı bir işlemciye kaydolmanın bir seçenek olmadığı Çin gibi pazarlar için idealdir.
• Karttan kriptoya ödeme — kriptosu olmayan alışveriş yapanlar bir kredi/banka kartıyla ödeyebilir ve siz kripto alırsınız, doğrudan kendi sakladığınız cüzdanınıza aktarılır. Payments sayfasından açtığınız yerleşik bir kanaldır; kart sağlayıcısı alışveriş yapan kişi üzerinde kendi kontrollerini yapar.
• Çok zincirli — BTC, ETH, USDT, USDC ve TRX'i Bitcoin, Ethereum, Base, Polygon ve Tron üzerinde yerel olarak kabul edin; otomatik depozito algılama, zincir üstü onay, soğuk depolamaya aktarma ve imzalı webhook'lar ile. Smart Bridge rayları ayrıca Solana, Bitcoin, Tron (USDT) ve BNB Chain üzerinde ödeme alır ve bunları Base üzerinde USDC olarak kapatır.
• Sunucuda depozito anahtarı yok — akıllı sözleşmeler depozitoları soğuk cüzdanınıza aktarır, böylece ele geçirilmiş bir sunucu bunları yönlendiremez. Sunucunun sıcak cüzdanı gas ücretlerini öder ve ödemeleri imzalar, bu yüzden bakiyesini küçük tutun.

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

---

Yapay zeka ajanları PayRam'i nasıl kullanır · AI 智能体如何使用 PayRam

PayRam ajan öncelikli altyapıdır. Entegrasyon MCP üzerinden olduğu için MCP uyumlu herhangi bir çalışma zamanıyla çalışır — OpenClaw, Hermes, Claude Desktop, Cursor, GitHub Copilot, n8n, LangChain ve daha fazlası. Tipik bir ajan akışı:

1. Bağlan — ajanın MCP yapılandırmasına https://mcp.payram.com/mcp ekleyin (yalnızca bağlanmak için API anahtarı gerekmez).
2. Planla — payram_setup_plan çağırın. Sıralı adımları, her birini kimin çalıştırdığını ve ajanın insan için nerede durması gerektiğini (soğuk cüzdan, ana ağ gas ücreti, yalnızca kök ayarları) döndürür.
3. Kur — VPS'te, etkileşimli bir terminalde bir kez bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet (veya --mainnet; yükleyici varsayılanı ana ağdır, bu yüzden her zaman bayrağı iletin) çalıştırın. Asla bash içine yönlendirmeyin.
4. Devret — insan kök hesabı hemen sahiplenir ve Settings → Site URL değerini genel alan adından kaydeder; o zamana kadar ödeme bağlantıları http://localhost adresini gösterir.
5. Kontrol et — genel URL ile payram_doctor (kimlik bilgisi gerekmez).
6. Ödeme kabul et — kod parçacığı araçlarından çerçeveye özel entegrasyon kodunu ekleyin. Webhook'lar imzalıdır (X-Payram-Signature, proje API anahtarıyla ham gövdenin HMAC-SHA256'sı).
7. İşlet — payram_ops_playbook (daily_check, payment_options, node_sync, unswept_funds, create_payment_link, …) ajana kendi kimlik bilgileriyle çalıştıracağı tam API çağrılarını verir. payram_runbook yönetici değişikliklerini kapsar.

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

OpenClaw'a özel yol gösterici için (kayıt, Base Sepolia'da test ağı, WhatsApp/Telegram/Discord için sohbet ticareti desenleri) payram-openclaw-integration becerisine ve payram.com/openclaw adresine bakın.

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'a ağınızdan erişmek zorsa, bu depoyu başka bir Git sunucusuna yansıtabilirsiniz (git clone --mirror https://github.com/PayRam/payram-mcp.git). 如果你的网络难以访问 GitHub，可以把本仓库镜像到其他 Git 托管平台（git clone --mirror https://github.com/PayRam/payram-mcp.git）。

---

İçindekiler

• PayRam nedir?
• Yapay zeka ajanları PayRam'i nasıl kullanır
• Ajan Becerileri
• Proje Hedefleri
• Hızlı Başlangıç
• MCP istemcinizden bağlanın
• Yerel mod
• Kimlik bilgileri
• Araç Kataloğu
• Rehberli İş Akışları
• Geliştirme
• Sorun Giderme

---

Ajan Becerileri

Ajan ön kapısı: https://mcp.payram.com/SKILL.md — PayRam'i tanımlayan ve ajanları dört başlangıç aracına yönlendiren tek bir kök beceri. Ayrıca sunulur: /llms.txt.

Bu depo, AI kodlama asistanları için 19 Ajan Becerisi içerir. Bunları skills.sh ile kurun:

Tek tek kurun

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

Beceri	Amaç
payram-setup	Kurulum planı ve sunucu kurulumu: gereksinimler, yükleyici, Site URL'si, cüzdanlar, ilk ödeme bağlantısı
payram-agent-onboarding	Bir ajan tarafından başsız kurulum: ajan CLI komutları, env değişkenleri, insan devir teslimleri
payram-auth	JWT kimlik doğrulama akışı — oturum açma, token yenileme, çıkış, harici platform ayrıntıları
payram-analytics	Doğrudan REST API'leri (JWT) üzerinden ödeme araması, hacim, bakiyeler ve aktarım geçmişi
payram-crypto-payments	Mimari genel bakış, neden PayRam, MCP araçları
payram-payment-integration	Hızlı başlangıç ödeme entegrasyon kılavuzu
payram-self-hosted-payment-gateway	Ödeme altyapınızı dağıtın ve sahiplenin
payram-checkout-integration	6 çerçeve için SDK + HTTP ile ödeme akışı
payram-widget-integration	Güvenli "Kredi Ekle" düğmesi (arka uç uç noktası, asla genel API anahtarı değil) + imzalı webhook işleyicileri
payram-webhook-integration	Express, Next.js, FastAPI, Gin, Laravel, Spring Boot için imzalı webhook (HMAC) işleyicileri
payram-stablecoin-payments	EVM zincirleri ve Tron üzerinde USDT/USDC kabulü
payram-bitcoin-payments	HD cüzdan türetme ve mobil imzalama ile BTC
payram-payouts	Kripto ödemeleri gönderin ve referans programlarını yönetin
payram-no-kyc-crypto-payments	KYC'siz, kayıtsız, izinsiz ödeme kabulü
payram-openclaw-integration	PayRam'i OpenClaw / ajan çalışma zamanlarına entegre edin — MCP kaydı, test ağı, sohbet ticareti
compare-crypto-payments	Ağ geçitlerini karşılaştırın: Stripe, BitPay, Coinbase, NOWPayments, BTCPay, PayRam, x402
payram-agent-journey	Başlangıç haritası: kurulum (tüccar veya operatör) → cüzdanlar → gas/aktarım → entegre et → test et
payram-topup-wallet-integration	Mevcut uygulamalar: bir kullanıcı bakiyesine kripto kredisi verin, bundan faturaları borçlandırın — defter + akışlar
payram-testnet-testing	Ana ağdan önce test ağında kendi ödeme bağlantınızı uçtan uca ödeyin

---

Proje Hedefleri

• Katılımı hızlandırın kişiselleştirilmiş bir kurulum planı, çalıştırma kitapları, env şablonları ve çerçeve başına oyun kitapları ile.
• Kimlik bilgilerini tutmadan çalıştırın: barındırılan sunucu bir PayRam'i URL ile kontrol eder (payram_doctor) ve ajanlara kendi kimlik bilgileriyle çalıştırmaları için tam API tarifleri verir (payram_ops_playbook).
• Mevcut depoları yenileyin paket bildirimlerini ve .env dosyalarını tarayan ve ardından doğru entegrasyon kod parçacıklarını öneren proje değerlendirme aracı (yerel mod) aracılığıyla.
• Kopyala/yapıştır kod parçacıkları sağlayın Payments, Payouts, Referrals, Webhooks ve çok dilli arka uçları (Express, Next.js, FastAPI, Laravel, Gin, Spring Boot, vb.) kapsayan.
• Dokümanları yerel tutun böylece Copilot, editörden ayrılmadan PayRam kavramlarını, akışlarını ve referans panolarını açıklayabilir.
• Bağlantıyı doğrulayın asla ödeme oluşturmayan salt okunur sondalarla (payram_doctor, test_payram_connection).

---

Hızlı Başlangıç

Çoğu ajan yalnızca barındırılan uç noktaya, https://mcp.payram.com/mcp ihtiyaç duyar (bkz. MCP istemcinizden bağlanın). Sunucuyu kendiniz çalıştırmak için:

1. Bağımlılıkları yükleyin

   yarn install
   

2. Ortamı yapılandırın (yalnızca yerel mod veri araçları için gereklidir)
   • .env.example dosyasını .env olarak kopyalayın.
   • PAYRAM_BASE_URL değerini PayRam URL'nize, panel ile aynı kaynağa ayarlayın (ör. https://pay.example.com).
   • PAYRAM_API_KEY değerini ve veri araçları için JWT değişkenlerini ayarlayın. Yerel mod bölümüne bakın.
3. Sunucuyu çalıştırın

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

4. MCP sunucusunu istemcinize ekleyin: MCP istemcinizden bağlanma bölümüne bakın. Yerel mod URL'si http://localhost:3333/mcp şeklindedir.
5. Sağlık kontrolü

   curl http://localhost:3333/healthz
   

İpucu: Copilot'a "test payram" dediğinizde, hazırlık kontrol listesini otomatik olarak çalıştırır, .env öğesinin mevcut olduğundan emin olur ve yalnızca bundan sonra gerçek kimlik bilgilerinizle test_payram_connection öğesini çağırır. Bu davranış Copilot otomasyon istemi tarafından tanımlanır—manuel istem gerekmez.

---

MCP istemcinizden bağlanma

Uç nokta: https://mcp.payram.com/mcp (Streamable HTTP, POST üzerinden JSON-RPC). SSE uç noktası yoktur ve /mcp/sse 410 döndürür. Kimlik doğrulama başlığı yoktur: barındırılan sunucu asla tüccar kimlik bilgilerini tutmaz, bu nedenle sizinkiler makinenizde kalır ve asla sohbete girmez.

İstemci	Nerede	Ayarlar
VS Code (Copilot Chat)	Ayarlar → Copilot: Model Context Protocol → HTTP sunucusu ekle	Ad payram, yukarıdaki URL, başlıklar boş
Cursor	Ayarlar → MCP Sunucuları → Ekle → HTTP	Ad payram, yukarıdaki URL
Claude Desktop / Code	Ayarlar → MCP Sunucuları → HTTP sunucusu ekle	Ad payram, yukarıdaki URL
Herhangi bir MCP istemcisi	Bir HTTP uç noktası kaydedin	Yukarıdaki URL, başlık yok

Doğrulama: araç listesi payram_setup_plan, payram_doctor, payram_troubleshoot, payram_runbook ve payram_ops_playbook ile başlamalı, ardından scaffold_payram_app ve generate_* snippet araçları gelmelidir. Ardından şunları deneyin: "pay.example.com üzerinde bir PayRam kurulumu planla", "https://pay.example.com kontrol et", "FastAPI ödeme oluşturma rotası üret", "bana bir Next.js webhook işleyicisi ver".

İstemler: setup-payram, setup-payram-agent, integrate-payment, troubleshoot-payment, daily-ops. Kaynaklar: payram://docs/setup-guide, payram://docs/api-reference ve payram://ops/playbook/{task} ile payram://runbooks/{task} şablonları.

Copilot otomasyon istemi

"test payram" komutunun hazırlık akışını otomatik olarak çalıştırması için bunu yeni bir çalışma alanına bir kez yapıştırı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.

---

Yerel mod

Canlı veri araçlarını almak için MCP'yi kendi PayRam'ınızın yanında çalıştırın:

• 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

• Mod: PAYRAM_MCP_MODE=local yerel modu seçer. Sunucu Vercel'de çalışmadığında da varsayılan moddur. PAYRAM_MCP_MODE=hosted asla kimlik bilgilerini okumaz.
• Bağlama: yerel mod varsayılan olarak 127.0.0.1 adresine bağlanır (bağlantı noktası PORT, varsayılan 3333).
• Döngü dışı bağlamalar: HOST değerini ayarlayın (ör. HOST=0.0.0.0), ardından:
  • MCP_ALLOWED_HOSTS değerini ayarlayın (Host başlığında kabul edilen virgülle ayrılmış ana bilgisayar adları).
  • MCP_SERVER_TOKEN değerini ayarlayın; istemciler daha sonra Authorization: Bearer <token> gönderir.
  • PAYRAM_* kimlik bilgileri ayarlanmışsa, sunucu MCP_SERVER_TOKEN olmadan döngü dışı bir HOST üzerinde başlamayı reddeder. Döngü adresini bir SSH tüneli ile tercih edin.
• Kimlik bilgileri: veri araçları PAYRAM_* değerini ortamdan (veya .env) okur:
  • PAYRAM_BASE_URL
  • PAYRAM_API_KEY (ödeme bağlantıları)
  • PAYRAM_ACCESS_TOKEN / PAYRAM_REFRESH_TOKEN (JWT, veri araçları)
  • PAYRAM_EXTERNAL_PLATFORM_ID (isteğe bağlı varsayılan proje)

Yerel bir sunucu için örnek istemci yapılandırması (yalnızca yerel mod):

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

---

Kimlik bilgileri: hangi anahtar ne için

PayRam'ın iki kimlik bilgisi vardır — aracılar bunları karıştırdığında takılır:

Kimlik bilgisi	Görünümü	Kullanım amacı	Bir aracının onu nasıl aldığı (panel gerekmez)
Tüccar API anahtarı (PAYRAM_API_KEY, başlık API-Key)	proje başına anahtar	POST /api/v1/payment (ödeme bağlantıları), tüccar ödemeleri, tüm tüccar sunucudan sunucuya çağrılar ve webhook'ları imzalar (X-Payram-Signature)	bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) ensure-api-key — proje anahtarını POST /api/v1/external-platform/{id}/api-key aracılığıyla yeniden kullanır veya üretir ve ~/.payraminfo/merchant-api-key.env konumuna kaydeder
JWT (Authorization: Bearer)	oturum açmadan erişim+yenileme belirteci	yönetici/kurulum API'leri (projeler, cüzdanlar, analitik) — payram_ops_playbook tarifleri ve yerel mod veri araçları	bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) signin (ortam PAYRAM_EMAIL/PAYRAM_PASSWORD); ~/.payraminfo/headless-tokens.env konumuna kaydedilir

Tek adımlı kurulum akışı (bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet) her ikisini de otomatik olarak üretir ve nerede saklandıklarını yazdırır. API, panel ile aynı kaynaktadır, 80/443 bağlantı noktasında (https://<your-domain>/api/v1/..., veya sunucuda http://localhost, asla :8080). API anahtarı ödemeler oluşturabilir, bu nedenle sunucu tarafında tutun ve asla tarayıcı koduna veya sohbete koymayın. Doğrudan API çağrıları için her ikisini de ayarlamak üzere payram_ops_playbook görevini connect kullanın.

---

Araç Kataloğu

Kategori	Araç	Amaç
Buradan başlayın – Kurulum	payram_setup_plan	Kişiselleştirilmiş, sıralı kurulum planı (hazırlık → kurulum → root + Site URL talep et → cüzdanlar + Smart Bridge → API anahtarı + ilk bağlantı → sağlamlaştır → entegre et) ajan ve insan adımları ile zorunlu durakları içerir.
Buradan başlayın – Tanılama	payram_doctor, payram_troubleshoot	payram_doctor: URL ile kimlik bilgisi gerektirmeyen, aşamalı genel kontrol (erişilebilirlik → sağlık → TLS → sürüm → çalışanlar) sıralanmış olası nedenler + kesin düzeltmelerle. İsteğe bağlı API anahtarı geçerlilik kontrolü hiçbir şey oluşturmaz. Herhangi bir şey başarısız olduğunda ÖNCE bunu çalıştırın. payram_troubleshoot: bir belirtiyi veya yapıştırılan hatayı bilinen nedenler ve düzeltmelerle eşleştirin.
Buradan başlayın – Yönetim	payram_runbook	İnsan onay kapılarıyla adım adım yönetim görevleri: 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.
Buradan başlayın – Operasyonlar	payram_ops_playbook	Ajanın kendisinin çalıştırdığı doğrudan API tarifleri: 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.
Bağlantı	test_payram_connection	Salt okunur erişilebilirlik/sağlık kontrolü artı isteğe bağlı API anahtarı doğrulaması. Asla ödeme oluşturmaz.
Kurulum	generate_env_template, generate_setup_checklist, suggest_file_structure, get_agent_setup_flow, onboard_agent_setup	Ortam şablonlarını, tüccar kontrol listelerini, önerilen proje düzenlerini ve başsız ajan katılım rehberini sağlar.
Bağlam / Dokümanlar	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, vb.	docs/ kaynaklı satır içi Markdown bilgisi sağlar, böylece Copilot kavramsal soruları yanıtlayabilir. Bazı araçlar otomatik olarak "test payram deyin" hatırlatmaları ekler.
Entegrasyon – Ödemeler	generate_payment_sdk_snippet, generate_payment_http_snippet, generate_payment_status_snippet, generate_payment_route_snippet	Oluşturma + durum akışları için SDK, ham HTTP veya Express/Next.js rota kodu üretir.
Entegrasyon – Ödemeler (Payouts)	generate_payout_sdk_snippet, generate_payout_recipient_flow_snippet, generate_payout_status_snippet	Doğrudan (OTP'siz) ödeme, 3 adımlı kayıtlı alıcı akışı (alıcı oluştur → OTP doğrula → öde) ve durum yoklaması.
Entegrasyon – Referanslar	generate_referral_sdk_snippet, generate_referral_validation_snippet, generate_referral_status_snippet, generate_referral_route_snippet	Referans kimlik doğrulama, bağlama, doğrulama, durum ve express/next rotalarını kapsar.
Entegrasyon – Webhook'lar	generate_webhook_handler, generate_webhook_event_router, generate_mock_webhook_event	Express/Next/FastAPI/Gin/Laravel/Spring Boot için işleyiciler, fan-out yönlendiriciler ve cURL/Python/Go/PHP/Java webhook test araçları üretir.
Entegrasyon – Çok Dilli Ödemeler	snippet_* ailesi (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 ve Spring Boot için önceden oluşturulmuş rota işleyicileri.
Entegrasyon – Cüzdan Yükleme	generate_topup_integration_snippet	MEVCUT uygulamalar için: defter şeması + kümülatif kredi webhook'u + atomik fatura kapatma, böylece fazla/eksik/geç/çift kripto ödemeleri ödeme istisnaları yerine bakiye durumları haline gelir. payram-topup-wallet-integration becerisiyle eşleşir.
Entegrasyon – Proje Değerlendirmesi (yerel mod)	assess_payram_project	package.json, requirements.txt, composer.json, go.mod, pom.xml, .env, vb. tarar. Algılanan çerçeveleri, ortam durumunu, PayRam bağımlılıklarını ve araç önerileriyle önceliklendirilmiş sonraki adımları raporlar.
İskelet Oluşturma	scaffold_payram_app	Ödemeler, ödemeler (payouts), webhook'lar ve bir tarayıcı konsolu ile tam başlangıç uygulamaları (Express, Next.js, FastAPI, Laravel, Gin, Spring Boot) üretir. Dağıtmadan önce ödeme uç noktalarını kendi yönetici kimlik doğrulamanızın arkasına koyun.
Canlı Veri (salt okunur, yerel mod)	list_platforms, search_payments, lookup_payment, get_payment_summary, get_daily_volume, get_unswept_balances, list_currencies, list_recipients	Canlı PayRam verilerini sorgular. list_currencies geneldir (anahtar gerekmez); geri kalanı .env içindeki JWT belirteçlerini kullanır. list_recipients, ödeme alıcı akışıyla eşleşir.
Canlı Operasyonlar (yerel mod)	create_payment_link (yazma), check_payment_readiness, check_node_sync, restart_payram_worker (yazma)	create_payment_link, API-Key aracılığıyla gerçek bir ödeme bağlantısı oluşturur. check_payment_readiness, ödemeleri kabul etmek için zincir başına eksiklikleri (eksik cüzdan / para birimi / dinleyici) raporlar. check_node_sync, dinleyici-çalışan + RPC düğüm sağlığını ve blok güncelliğini raporlar. Barındırılan sunucuda eşleşen payram_ops_playbook görevlerini kullanın.

Araç kayıtları src/tools/index.ts içinde yaşar; bireysel uygulamalar src/tools/** içinde, dil özel şablonları templates/ klasörleri altında bulunur.

---

Rehberli İş Akışları

0. PayRam Kurulumu

1. Sorun: "PayRam'ı pay.example.com üzerinde kur" (veya setup-payram / setup-payram-agent istemlerini kullanın).
2. Asistan payram_setup_plan çağırır ve aşamaları yürür, her insan adımında durur (root hesabı, Site URL, soğuk cüzdan, ana ağ gas ücreti).
3. payram_doctor, yedekler (payram_runbook backup) ve günlük kontrol (payram_ops_playbook daily_check) ile biter.

1. Mevcut Bir Projeyi Değerlendir ve Yeniden Donat

1. Copilot'a sor: "Bu projeye PayRam'i entegre edebilir misin?"
2. Asistan, assess_payram_project (yerel mod) çalıştırır, bağımlılık manifestlerini ve .env öğesini inceler.
3. Önerilen adımları izleyin (payram kurun, Express/FastAPI/Spring route parçacıkları isteyin, webhook'lar ekleyin, vb.).
4. Kimlik bilgileri gerçek olduğunda, arka uçun kendi kendine barındırılan sunucunuza ulaşabildiğinden emin olmak için test_payram_connection kullanın.

2. Yeni Bir Örnek Proje Oluşturun

1. "PayRam Express demo oluştur" → scaffold_payram_app, ödemeler, ödemeler, webhook'lar ve bir UI konsolu içeren bir Express projesi oluşturur.
2. Oluşturulan dosyaları boş bir depoya koyun veya referans bağlantıları için mevcut dizininizle karşılaştırın.

3. "Test PayRam" Hazırlık Akışını Çalıştırın

1. "test payram" deyin. Asistan otomatik olarak:
   • Hazırlık kontrol listesini paylaşmak için prepare_payram_test çağırır.
   • generate_env_template kullanarak .env öğesinin var olduğundan emin olur (yoksa oluşturur).
   • test_payram_connection çağırmadan önce gerçek kimlik bilgilerini bekler.
2. PayRam API'sine ulaşılabildiğini doğrulamak için yapılandırılmış JSON sonucunu inceleyin.

4. Ödemeleri, Ödemeleri, Yönlendirmeleri ve Webhook'ları Bağlayın

• Ödemeler: generate_payment_sdk_snippet (JS SDK) veya generate_payment_http_snippet (Python/Go/PHP/Java).
• Çok dilli rotalar: snippet_nextjs_payment_route, snippet_fastapi_payment_route, vb.
• Ödemeler: oluşturma için generate_payout_sdk_snippet + yoklama için generate_payout_status_snippet.
• Yönlendirmeler: generate_referral_route_snippet, generate_referral_validation_snippet.
• Webhook'lar: generate_webhook_handler artı fan-out için generate_webhook_event_router + her durumu test etmek için generate_mock_webhook_event.

---

Geliştirme

Komut	Açıklama
yarn dev	MCP sunucusunu tsx ile sıcak yeniden yükleme ile çalıştırın.
yarn build	TypeScript'i dist/ derleyin.
yarn lint / yarn format	Depo genelinde ESLint + Prettier.
yarn test	Vitest paketini çalıştırır (tests/).
make precommit-test	Sırayla format → lint → test → build çalıştırır.

Proje TypeScript önceliklidir (ESM). Prettier yapılandırması .prettierrc.json içinde; ESLint, eslint.config.mjs ile yapılandırılmıştır. Sorunsuz katkılar, Makefile → make commit içindeki commit yardımcısını takip eder.

---

Sorun Giderme

payram_doctor ile başlayın — erişilebilirlik → sağlık → TLS → sürüm → çalışanları inceleyen ve sıralanmış nedenleri kesin düzeltmelerle döndüren tek salt okunur çağrı. Daha derin kontroller için payram_ops_playbook (stuck_payment, node_sync, webhooks, logs) izleyin.

• Copilot doğru aracı çağırmıyor: Copilot otomasyon isteminin kurulu olduğunu ve MCP istemcinizin sunucuyu yüklediğini kontrol edin. Beklenen otomasyonu tetiklemek için "test payram" veya "projemi değerlendir" komutunu yeniden çalıştırın.
• test_payram_connection 401 ile başarısız oluyor: Anahtarın aktif bir proje API anahtarı olduğunu doğrulayın (Authorization değil, API-Key başlığı olarak gönderilir).
• Bir veri aracı kimlik bilgilerinin kullanılamadığını söylüyor: barındırılan sunucu asla tüccar kimlik bilgilerini tutmaz. Eşleşen payram_ops_playbook görevini kullanın veya MCP'yi yerel modda çalıştırın.
• Ödeme bağlantıları http://localhost gösteriyor: insan, genel alan adından Ayarlar → Site URL'sini kaydetmelidir (payram_runbook görevi set_site_url).
• Docs aracı bir dosyanın eksik olduğunu söylüyor: Yerel docs/payram-docs-live/ ağacınızın istenen markdown'u içerdiğini doğrulayın (get_payram_doc_by_id, .. içeren yolları reddeder).
• Sunucu başlamıyor: Node 20+ olduğundan emin olun ve yarn install çalıştırın. Yerel modda, döngüsel olmayan bir HOST ve PAYRAM_* kimlik bilgileri ayarlanmışsa, sunucu MCP_SERVER_TOKEN ayarlanana kadar başlamayı reddeder (bkz. Yerel mod).

Başka herhangi bir şey için, src/utils/logger.ts tarafından yayılan yapılandırılmış günlükleri inceleyin (LOG_LEVEL=debug ayarlayın) ve üreme ayrıntılarıyla bir sorun/PR açın.