# Kustodia — The Trust Layer for Autonomous Commerce

> Kustodia is a programmatic escrow custody platform for AI agents and humans. We provide fiat (SPEI/ACH/Wire), Web3 (Arbitrum, Base, Polygon, Injective), **QR Payments** (P2P escrow via shareable links), and **confidential (FHE-encrypted)** escrow services accessible via MCP, x402, Google AP2, and REST API.
> Try without signup: https://kustodia.app/sandbox

## Quick Start for AI Agents

### Protocol Endpoints

- **MCP SSE Server**: `https://api.kustodia.app/api/v1/mcp/sse` (requires API key)
- **x402 Pay-Per-Call**: `https://api.kustodia.app/api/v1/mcp/x402` (pay USDC per call, no key)
- **REST API**: `https://api.kustodia.app/api/v1/` (requires API key)
- **Sandbox (no auth)**: `https://api.kustodia.app/api/v1/sandbox/escrow`
- **Google AP2 Discovery**: `https://api.kustodia.app/api/v1/ap2/.well-known/ap2`

### Claude MCP Config (copy-paste)

```json
{
  "mcpServers": {
    "kustodia": {
      "url": "https://api.kustodia.app/api/v1/mcp/sse",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

### Platform Compatibility
- Claude MCP ✅
- OpenAI / ChatGPT MCP ✅
- Coinbase CDP / AgentKit / x402 ✅
- Alchemy Agents ✅
- Google AP2 (ADK) ✅
- LangChain / LangGraph ✅
- Visa Trusted Agent (Coming Soon)

## 37 MCP Tools

### Fiat Escrow (7 tools)
- `create_escrow` — Create fiat escrow (MXN via SPEI or USD via Wire). Returns payment ID and deposit instructions.
- `check_status` — Check Payment status by ID.
- `list_payments` — List all payments with filtering.
- `release_funds` — Release funds to seller via SPEI or Wire.
- `cancel_payment` — Cancel a pending payment before deposit.
- `raise_dispute` — Dispute a payment in custody.
- `request_refund` — Request refund via SPEI.

### Web3 Escrow (7 tools)
- `create_web3_escrow` — Create on-chain escrow (USDC/USDT/PYUSD/MXNB on Arbitrum/Base/Polygon).
- `fund_web3_escrow` — Approve + fund escrow from wallet.
- `release_web3_escrow` — Release funds on-chain to payee.
- `dispute_web3_escrow` — Dispute on-chain escrow.
- `check_web3_status` — Check on-chain escrow status.
- `get_web3_escrow` — Get escrow details from smart contract.
- `list_web3_escrows` — List on-chain escrows by wallet or chain.

### Recurring Payments (7 tools)
- `create_recurring_escrow` — Create subscription (weekly/biweekly/monthly/quarterly) with escrow per cycle.
- `pause_recurring` — Pause active subscription.
- `resume_recurring` — Resume paused subscription.
- `cancel_recurring` — Cancel subscription permanently.
- `approve_cycle` — Approve pending billing cycle.
- `list_recurring` — List subscriptions with status filtering.
- `get_recurring_status` — Get subscription details with cycle history.

### Gasless / Session Keys (2 tools)
- `create_session_key` — Create scoped ZeroDev session key (ERC-4337). Agent can fund escrows without holding ETH.
- `fund_with_session_key` — Fund escrow gaslessly via session key. Kustodia pays gas.

### Agent Trading & Wallets (4 tools)
- `register_agent_wallet` — Register AI agent wallet for discovery.
- `fund_agent_wallet` — Fund agent wallet via SPEI (MXN) or Wire (USD) → USDC/MXNB. Three paths: SPEI on-ramp, Wire on-ramp, or direct crypto transfer.
- `list_trade_offers` — List open escrows and trade offers.
- `accept_trade` — Accept trade offer and get next steps.

### Delivery Oracle (2 tools)
- `attach_delivery_tracking` — Link carrier tracking ID to escrow for auto-release on delivery. Supports: 99minutos, Estafeta, DHL, FedEx, Lalamove, Skydropx.
- `check_delivery_status` — Query carrier API for real-time delivery status. Returns: pending, collected, in_transit, out_for_delivery, delivered, returned, failed.

### FHE Confidential Escrow (2 tools)
- `create_confidential_escrow` — Create on-chain escrow with FHE-encrypted amount (Fhenix coFHE on Arbitrum). Only payer and payee can decrypt.
- `view_confidential_balance` — Decrypt and view confidential escrow amount. Requires ACL permission.

### Trust & Discovery (3 tools)
- `get_trust_score` — Get trust score for any wallet based on transaction history, dispute rate, and escrow completion.
- `get_escrow_evidence` — Retrieve uploaded evidence files for a specific escrow.
- `create_solana_blink` — Create a shareable QR payment link (Solana escrow via Phantom wallet).

### Utility (3 tools)
- `check_balance` — Check token balance for any wallet on any chain.
- `get_fx_rate` — Get real-time MXN/USD exchange rate.
- `upload_evidence` — Upload evidence files (photos, docs) to escrow.

## 5 Payment Rails
- **SPEI** — Mexico instant bank transfers (MXN). Live ✅
- **ACH / Wire** — US bank transfers (USD). Live ✅
- **Stablecoins (EVM)** — USDC, USDT, PYUSD, MXNB on Arbitrum, Base, Polygon, Injective. Live ✅
- **QR Payments** — P2P USDC escrow via shareable QR links (Phantom wallet). Mainnet + Devnet. Live ✅
- **Pix** — Brazil instant transfers (BRL). Coming soon 🔨

## Use Cases
- Vehicle purchases (VIN verification + escrow)
- Real estate deposits
- Marketplace transactions (with delivery oracle auto-release)
- E-commerce COD replacement (carrier-triggered escrow release)
- Cross-border USD→MXN B2B payments
- AI agent-to-agent trading
- AI agent wallet funding (SPEI/Wire → USDC)
- Crowdfunding with milestone-based release
- Recurring subscriptions with escrow per cycle
- Confidential escrows with FHE-encrypted amounts (Fhenix on Arbitrum)
- **QR Payments** — P2P escrow via shareable links (WhatsApp, Twitter, Telegram). Seller creates → Buyer pays via Phantom → Funds locked → Release on confirmation

## Supported Chains (10)
- Arbitrum One (42161) ✅
- Base (8453) ✅
- Polygon (137) ✅
- Injective Mainnet (1776) ✅
- **Solana Mainnet** (901) ✅
- Solana Devnet (900) ✅
- Arbitrum Sepolia (421614) ✅
- Base Sepolia (84532) ✅
- Polygon Amoy (80002) ✅
- Injective Testnet (1777) ✅

## Authentication
- **MCP/REST**: API key from https://kustodia.app/dashboard/developers
- **x402**: No auth — pay USDC per call
- **AP2**: Verifiable Credentials
- **Sandbox**: No auth — https://api.kustodia.app/api/v1/sandbox/escrow

## Links
- Website: https://kustodia.app
- Sandbox: https://kustodia.app/sandbox
- API Docs: https://kustodia.app/docs
- AI Agents: https://kustodia.app/ai-agents
- Blog: https://kustodia.app/blog
- npm SDK: https://www.npmjs.com/package/@kustodia_app/node
- Node SDK Docs: https://kustodia.app/docs/node-sdk
- Solutions: https://kustodia.app/soluciones
- Privacy (FHE): https://kustodia.app/soluciones/privacidad
- GitHub: https://github.com/rodrigojille/kustodia_api