PayBridge MCP

PayBridge doesn't move money. It moves intelligent information so money moves as efficiently as possible.

PayBridge is an AI-native payment broker. It gives AI agents the intelligence to find the optimal multi-hop payment path across 39 connectors and 20+ countries — then hands control back to the operator to execute with their own credentials.

No custody. No funds. No keys stored. You bring your own API credentials and PayBridge brings the routing intelligence.

---

The problem it solves

Building an AI agent that needs to send a payment is harder than it sounds. There are dozens of payment platforms, each with their own fee structures, settlement windows, compliance requirements, and geographic restrictions. A payment from a Japanese bank to a MercadoPago account in Mexico might optimally route through Wise, then SPEI — or it might go through Payoneer directly. A sender in Uruguay wanting to reach a recipient in Argentina has a free instant path through PREX that most systems don't know about.

PayBridge knows. It models the entire payment graph as a directed weighted network, runs Dijkstra on it, and returns the optimal path in 1–4ms.

---

Four tools

payment_initiate — Compliance check

Run a compliance check before anything else moves. Validates against OFAC, EU, UK, and UN sanctions lists, flags BCRA Comunicación A 8417 (Argentina, April 2026), screens crypto wallet addresses via Chainalysis, enforces KYC thresholds ($3K basic / $10K enhanced / $50K human review), and blocks hard-jurisdiction transfers (IR, KP, CU, SY). Every decision is HMAC-SHA256 signed and written to your audit log.

{
  "amount": 5000,
  "currency": "USD",
  "sender": { "country": "JP", "name": "Tanaka Hiroshi" },
  "recipient": { "country": "AR", "name": "Carlos Russell" }
}

Returns: APPROVED / REVIEW / BLOCKED with reason, KYC requirement, regulatory notes, and signed audit entry.

---

get_best_execution_path — Multi-hop routing

Finds the lowest-cost path across the payment graph. Models 705 nodes and 1,964 edges. Handles currency conversion, stablecoin transfers (USDT/USDC/PYUSD), local bank intake, CVU/PIX/SEPA/FPS/SPEI rails, and direct platform bridges. Returns up to 5 ranked paths with fees, settlement times, and hop-by-hop breakdown.

Example: Japan bank → PayPal Argentina

Path: local_bank_JP → Wise (JPY→USD, $1.52) → Nubi → PayPal AR
Fee: $1.52 | Settlement: same day

Example: Payoneer GBP → MercadoPago Mexico

Path: Payoneer (GBP→MXN, $3.50) → SPEI → MP MX CLABE
Fee: $3.50 | Settlement: same day

Supports optimize: cost | speed | balanced and target_platform for directed routing.

---

simulate_payment — Rate-locked quote

Two modes:

sender_pays (default): You specify what the sender sends, PayBridge calculates what arrives after fees.

recipient_receives: You specify the exact amount the recipient must get, PayBridge calculates what the sender needs to send — using reverse fee compounding, not naive addition.

{
  "mode": "recipient_receives",
  "amount": 100,
  "from_currency": "GBP",
  "to_currency": "MXN"
}

Returns a 30-minute rate-locked quote with simulation_id, exact amounts in both currencies, fee breakdown, FX rate with spread disclosure, and step-by-step preview. The simulation_id is passed to the next tool to guarantee the quoted rate is honored at execution.

---

get_execution_instructions — Zero-custody API payload

Takes the simulation_id and returns an executable API payload for each hop — populated with the correct endpoint, method, and parameters for the operator's own credentials. The operator executes. PayBridge never touches the funds.

{
  "zero_custody_notice": "PayBridge does not execute. Use your own credentials.",
  "steps": [
    {
      "platform": "Wise",
      "credential_env_var": "WISE_API_KEY",
      "api_call": {
        "method": "POST",
        "endpoint": "https://api.wise.com/v1/transfers",
        "payload": { "sourceCurrency": "JPY", "targetAmount": 100.00, ... }
      }
    }
  ]
}

---

Coverage

39 connectors across 20+ countries. 380 corridors tested. 77% path coverage.

Region	Connectors
Argentina	MercadoPago, Lemon, Belo, Cocos, BBVA AR, Nubi, MODO, Ualá, Brubank, Naranja X
LATAM	MercadoPago MX, Nubank, Nequi, Daviplata, Yape, Plin, Bitso, Global66, dLocal, Airtm
Central America	SINPE Móvil (CR), Yappy (PA), Tigo Money (HN/NI/BO/PY), PagoExpress (PY), Khipu (CL), Strike
Cono Sur	PREX (AR↔UY↔PE↔CL — instant cross-border, free)
Global	Wise, PayPal, Revolut, Binance, Payoneer, GrabrFi
EU / UK / Canada	Bizum (ES), Wero (DE/FR/BE/NL), Satispay (IT), N26 (EU), Monzo (UK), Interac (CA)

Notable corridors supported: Japan → LATAM, Nigeria → LATAM, UK → Argentina, EU → Cono Sur, intra-LATAM P2P.

---

Compliance coverage

• Sanctions: OFAC / EU / UK / UN — name screening via ComplyAdvantage (or stub fallback)
• Crypto: Chainalysis wallet address screening
• KYC thresholds: Configurable per-transfer
• BCRA: Comunicación A 8417 (April 2026) flagged for AR operators
• Capital controls: AR, BR, MX, CO, NG flagged with regulatory notes
• Regulatory requirements: JP (FSA), EU (PSD2), GB (FCA), CA (FINTRAC), MX (CNBV), US (FinCEN MSB)
• Audit log: Every decision HMAC-SHA256 signed → Supabase or local JSONL

---

Architecture

Compliance Gateway (fail-closed)
        ↓ APPROVED
PathBridge Engine (graphology + Dijkstra)
    705 nodes · 1,964 edges · 1–4ms per query
    In-memory singleton — built once at startup
        ↓
Execution Layer
    Returns API payload
    Operator executes with own keys
    PayBridge never touches funds

---

Operator model

PayBridge implements a strict zero-custody, operator-responsibility model:

• You register as operator with your own credentials
• You are responsible for regulatory compliance in your jurisdictions
• PayBridge surfaces requirements — you fulfill them
• API keys stay in your environment (MCPize secrets)
• Audit log goes to your Supabase instance

---

Required secrets

Secret	Required	Purpose
AUDIT_HMAC_SECRET	✅ Yes	Signs every audit log entry
AUDIT_WEBHOOK_URL	Recommended	Supabase persistent audit log
COMPLY_ADVANTAGE_API_KEY	Optional	Live sanctions screening
CHAINALYSIS_API_KEY	Optional	Live crypto wallet screening
MERCADOPAGO_ACCESS_TOKEN	Optional	Live fee quotes (falls back to static table)
PAYPAL_CLIENT_ID/SECRET	Optional	Live fee quotes (falls back to static table)

Generate AUDIT_HMAC_SECRET:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"