{
  "markdown": "# agora402\n\nThe trust layer for agent-to-agent commerce. Escrow protection for x402 payments on Base.\n\nAgents pay for API calls with USDC via [x402](https://x402.org). But payments are final — no refunds, no disputes, no recourse. **agora402** fixes this by routing payments through on-chain escrow: funds are locked until delivery is verified, then released automatically.\n\nInstall as an MCP server. Your agent gets escrow-protected payments in one tool call.\n\n## Quick Start\n\n### 1. Generate a wallet\n\n```bash\nnpx agora402 init\n```\n\nThis creates a fresh wallet and prints your Claude Desktop config — copy-paste and go.\n\n### 2. Fund it\n\nSend a small amount of ETH (for gas, ~$0.50) and USDC (for payments) to the printed address on **Base**.\n\n### 3. Add to Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"agora402\": {\n      \"command\": \"npx\",\n      \"args\": [\"agora402\"],\n      \"env\": {\n        \"PRIVATE_KEY\": \"0x_YOUR_KEY_FROM_INIT\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. Done — your agent now has escrow-protected payments.\n\n### Any MCP Client\n\n```bash\nPRIVATE_KEY=0x... npx agora402\n```\n\nRuns over stdio. Compatible with any MCP client (Claude Desktop, Claude Code, Cursor, Windsurf, OpenClaw, etc).\n\n## Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `PRIVATE_KEY` | **Yes** | Wallet private key (hex, with 0x prefix) |\n| `CHAIN` | No | `\"base\"` for mainnet, defaults to Base Sepolia |\n| `BASE_RPC_URL` | No | Custom RPC URL for Base mainnet |\n| `BASE_SEPOLIA_RPC_URL` | No | Custom RPC URL for Base Sepolia |\n\nContract addresses are hardcoded — no need to configure them.\n\n## Tools\n\n### `x402_protected_call` — Flagship\n\nMake an API call with automatic escrow protection. One tool call does everything:\n\n1. Creates USDC escrow on-chain\n2. Calls the API\n3. Verifies the response (JSON Schema or hash-lock)\n4. Auto-releases payment if valid, auto-disputes if not\n\n```\nParameters:\n  url               — API endpoint to call\n  seller_address    — Ethereum address of the API provider\n  amount_usdc       — Payment amount ($0.10 - $100)\n  method            — GET, POST, PUT, DELETE (default: GET)\n  headers           — HTTP headers (optional)\n  body              — Request body for POST/PUT (optional)\n  verification_strategy — \"schema\" or \"hash-lock\" (default: schema)\n  verification_data — JSON Schema string or expected response hash\n  timelock_minutes  — Auto-refund timeout, 5-43200 min (default: 30)\n```\n\n### `escrow_create`\n\nCreate a USDC escrow manually for any agent-to-agent transaction.\n\n### `escrow_release`\n\nConfirm delivery and release funds to the seller.\n\n### `escrow_dispute`\n\nFlag bad delivery. Locks funds for arbiter review.\n\n### `escrow_status`\n\nCheck the current state of an escrow.\n\n### `trust_score_query`\n\nLook up any agent's on-chain trust score before transacting. Reads the Agora402 Reputation contract — scores are 0-100 based on real escrow history, not self-reported.\n\nReturns: score, success rate, volume, timestamps, recommendation (high_trust / moderate_trust / low_trust).\n\n## How It Works\n\n```\nAgent (buyer) ──→ agora402 MCP Server ──→ Escrow Contract (Base L2)\n                        │                        │\n                  Verify response          USDC held until\n                  (schema/hash)            delivery confirmed\n                        │                        │\n                   Auto-release ←─── Verification passes\n                   Auto-dispute ←─── Verification fails\n```\n\n**Escrow lifecycle:**\n\n```\nFUNDED → RELEASED         (delivery confirmed, seller paid minus 2% fee)\n       → DISPUTED → RESOLVED  (arbiter rules: splits funds)\n       → EXPIRED → REFUNDED   (timeout: full refund, no fee)\n```\n\n- 2% protocol fee on release/resolve. Zero fee on refund.\n- $0.10 minimum, $100 maximum per escrow (v1 safety cap).\n- Timelock: 5 minutes to 30 days.\n- On-chain reputation auto-recorded for every escrow outcome.\n\n## Chain\n\n| | Testnet | Mainnet |\n|-|---------|---------|\n| **Network** | Base Sepolia | Base |\n| **USDC** | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |\n| **Gas cost** | ~$0.005/escrow cycle | ~$0.005/escrow cycle |\n\nSet `CHAIN=base` for mainnet. Defaults to Base Sepolia.\n\n## Contract\n\nSolidity smart contracts with:\n- Escrow: full 7-state machine with 2% protocol fee\n- Reputation: on-chain trust scores based on escrow history\n- OpenZeppelin ReentrancyGuard + Pausable\n- 135 tests (unit + fuzz + invariant + integration)\n\nSource: [github.com/michu5696/agora402](https://github.com/michu5696/agora402)\n\n## License\n\nMIT",
  "bytes": 4612,
  "sha": "11dcee006bc1bf6d2272b9e1f3a3a0c6136c1afd0b17492afb0eb1b6e291623f",
  "repo_slug": "michu5696/agora402",
  "fonte": "npm",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_michu5696_agora402_4a129cf9/readme"
}