{"openapi":"3.1.0","info":{"title":"x402 Payment Facilitator API","description":"\nUltravioleta DAO x402 Payment Facilitator - Gasless micropayments for the agentic economy.\n\n## Overview\n\nThe x402 facilitator enables gasless micropayments across multiple blockchain networks using the HTTP 402 Payment Required protocol. It acts as a settlement intermediary, verifying EIP-3009/EIP-712 payment authorizations and submitting them on-chain.\n\n## Supported Networks\n\n### EVM Chains (Mainnet)\nEthereum, Base, Polygon, Optimism, Avalanche, Arbitrum, Celo, HyperEVM, Unichain, Monad, Scroll, BSC, SKALE\n\n### EVM Chains (Testnet)\nEthereum Sepolia, Base Sepolia, Polygon Amoy, Optimism Sepolia, Avalanche Fuji, Arbitrum Sepolia, Celo Sepolia, HyperEVM Testnet, Unichain Sepolia, SKALE Sepolia, Monad Testnet\n\n### SVM Chains (Solana Virtual Machine)\n- **Solana**: Mainnet and Devnet\n- **Fogo**: Mainnet and Testnet\n\n### Other Non-EVM Chains\n- **NEAR Protocol**: Mainnet and Testnet\n- **Stellar/Soroban**: Mainnet and Testnet\n- **Algorand**: Mainnet and Testnet\n- **Sui**: Mainnet and Testnet\n\n## Core Endpoints\n\n- `POST /verify` - Verify payment authorization structure and signatures\n- `POST /settle` - Submit verified payment to blockchain for settlement\n- `GET /supported` - List all supported networks and payment schemes\n\n## ERC-8004 Reputation (Trustless Agents)\n\nThe facilitator supports [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) for AI agent identity and reputation across **18 networks** (10 mainnets + 8 testnets), spanning both EVM and Solana.\n\n**EVM networks:** `ethereum`, `base`, `polygon`, `arbitrum`, `optimism`, `celo`, `bsc`, `monad`, `avalanche`, `ethereum-sepolia`, `base-sepolia`, `polygon-amoy`, `arbitrum-sepolia`, `optimism-sepolia`, `celo-sepolia`, `avalanche-fuji`\n\n**Solana networks:** `solana`, `solana-devnet` (via [QuantuLabs 8004-solana](https://github.com/QuantuLabs/8004-solana) + [ATOM Engine](https://github.com/QuantuLabs/8004-atom))\n\n**Note:** For EVM networks, `agentId` is a numeric uint256 (e.g., `42`). For Solana, `agentId` is a base58 Pubkey (e.g., `7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHkv`). Solana reputation responses include bonus `atomStats` with trust tiers, quality scores, and anti-Sybil metrics.\n\n### Endpoints:\n- `POST /register` - Register a new agent on-chain (gasless, EVM only)\n- `POST /feedback` - Submit on-chain reputation feedback (EVM only)\n- `POST /feedback/revoke` - Revoke previously submitted feedback (EVM only)\n- `POST /feedback/response` - Append agent response to feedback (EVM only)\n- `GET /reputation/:network/:agentId` - Query agent reputation summary (EVM + Solana)\n- `GET /identity/:network/:agentId` - Get agent identity from registry (EVM + Solana)\n- `GET /identity/:network/:agentId/metadata/:key` - Read specific agent metadata (EVM + Solana)\n- `GET /identity/:network/total-supply` - Get total registered agents on a network (EVM + Solana)\n\n## Bazaar Discovery\n\nDecentralized resource discovery for x402-enabled services:\n\n- `GET /discovery/resources` - List all registered resources\n- `POST /discovery/register` - Register a new resource\n\n## Protocol Documentation\n\n- [x402 Protocol](https://x402.org)\n- [EIP-3009 (transferWithAuthorization)](https://eips.ethereum.org/EIPS/eip-3009)\n- [ERC-8004 (Trustless Agents)](https://eips.ethereum.org/EIPS/eip-8004)\n- [Ultravioleta DAO](https://ultravioletadao.xyz)\n","contact":{"name":"Ultravioleta DAO","url":"https://ultravioletadao.xyz"},"license":{"name":"Apache-2.0","url":"https://www.apache.org/licenses/LICENSE-2.0"},"version":"1.43.4"},"servers":[{"url":"https://facilitator.ultravioletadao.xyz","description":"Production"},{"url":"http://localhost:8080","description":"Local Development"}],"paths":{"/accepts":{"post":{"tags":["Core"],"summary":"Negotiate payment requirements (Faremeter middleware)","description":"\nNegotiation endpoint used by `@faremeter/middleware` and compatible x402 clients.\n\nReceives merchant payment requirements, matches them against the facilitator's\nsupported capabilities, and returns enriched requirements with facilitator-specific\ndata (feePayer, tokens, escrow contracts, etc.).\n\n**How it works:**\n1. Middleware sends the merchant's desired payment requirements\n2. Facilitator filters to only those it can handle (matching scheme + network)\n3. Facilitator enriches each match with `extra` data (feePayer, tokens, features)\n4. Middleware uses the enriched requirements in the 402 response to clients\n\n**Supports both v1 and v2 network formats** (auto-detected):\n- v1: `\"network\": \"base\"` (string enum)\n- v2: `\"network\": \"eip155:8453\"` (CAIP-2 format)\n\n**Request body:**\n```json\n{\n  \"x402Version\": 1,\n  \"accepts\": [\n    {\n      \"scheme\": \"exact\",\n      \"network\": \"solana\",\n      \"maxAmountRequired\": \"10000\",\n      \"asset\": \"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\",\n      \"payTo\": \"SomePublicKey...\",\n      \"description\": \"Access to premium API\",\n      \"maxTimeoutSeconds\": 90,\n      \"resource\": \"https://api.example.com/data\"\n    }\n  ],\n  \"error\": \"\"\n}\n```\n\n**Response (enriched):**\n```json\n{\n  \"x402Version\": 1,\n  \"accepts\": [\n    {\n      \"scheme\": \"exact\",\n      \"network\": \"solana\",\n      \"maxAmountRequired\": \"10000\",\n      \"asset\": \"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\",\n      \"payTo\": \"SomePublicKey...\",\n      \"description\": \"Access to premium API\",\n      \"maxTimeoutSeconds\": 90,\n      \"resource\": \"https://api.example.com/data\",\n      \"extra\": {\n        \"feePayer\": \"F742C4VfFLQ9zRQyithoj5229ZgtX2WqKCSFKgH2EThq\",\n        \"tokens\": [\n          { \"token\": \"usdc\", \"address\": \"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\", \"decimals\": 6 }\n        ]\n      }\n    }\n  ],\n  \"error\": \"\"\n}\n```\n\n**Note:** Requirements for unsupported scheme+network combinations are silently dropped from the response.\n","operationId":"path_accepts_post","requestBody":{"description":"Merchant payment requirements to negotiate","content":{"application/json":{"schema":{"type":"object"}}},"required":true},"responses":{"200":{"description":"Enriched payment requirements","content":{"application/json":{"schema":{"type":"object"},"example":{"x402Version":1,"accepts":[{"scheme":"exact","network":"base","maxAmountRequired":"1000000","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x...","extra":{"tokens":[{"token":"usdc","address":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","decimals":6}]}}],"error":""}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object"},"example":{"x402Version":1,"accepts":[],"error":"Missing or invalid 'accepts' array"}}}}}}},"/blacklist":{"get":{"tags":["Compliance"],"summary":"Get OFAC sanctioned addresses","description":"\nReturns the list of OFAC sanctioned blockchain addresses. Payments involving these addresses are blocked.\n\n**Response:**\n```json\n{\n  \"addresses\": [\"0x...\", \"0x...\"],\n  \"lastUpdated\": \"2026-01-15T00:00:00Z\",\n  \"source\": \"OFAC SDN List\"\n}\n```\n","operationId":"path_blacklist","responses":{"200":{"description":"Sanctioned addresses list","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/discovery/register":{"post":{"tags":["Bazaar"],"summary":"Register a resource","description":"\nRegisters a new resource in the discovery registry.\n\n**Request body:**\n```json\n{\n  \"url\": \"https://example.com/api\",\n  \"type\": \"service\",\n  \"description\": \"Example AI service\",\n  \"paymentRequirements\": [\n    {\n      \"scheme\": \"exact\",\n      \"network\": \"base\",\n      \"maxAmountRequired\": \"1000000\",\n      \"payTo\": \"0x...\",\n      \"asset\": \"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\"\n    }\n  ],\n  \"metadata\": {\n    \"category\": \"ai-agent\",\n    \"provider\": \"Example Inc\",\n    \"tags\": [\"ai\", \"nlp\"]\n  }\n}\n```\n","operationId":"path_bazaar_register","requestBody":{"description":"Resource registration request","content":{"application/json":{"schema":{"type":"object"}}},"required":true},"responses":{"201":{"description":"Resource registered","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/discovery/resources":{"get":{"tags":["Bazaar"],"summary":"List registered resources","description":"\nLists all resources registered in the discovery registry.\n\n**Query parameters:**\n- `type` (optional): Filter by resource type (e.g., \"facilitator\", \"agent\", \"service\")\n- `category` (optional): Filter by category\n- `tag` (optional): Filter by tag\n\n**Response:**\n```json\n{\n  \"resources\": [\n    {\n      \"id\": \"uuid-here\",\n      \"url\": \"https://example.com/api\",\n      \"type\": \"service\",\n      \"description\": \"Example AI service\",\n      \"paymentRequirements\": [...],\n      \"metadata\": {\n        \"category\": \"ai-agent\",\n        \"provider\": \"Example Inc\",\n        \"tags\": [\"ai\", \"nlp\"]\n      }\n    }\n  ]\n}\n```\n","operationId":"path_bazaar_list","parameters":[{"name":"type","in":"query","description":"Filter by resource type","required":false,"schema":{"type":"string"}},{"name":"category","in":"query","description":"Filter by category","required":false,"schema":{"type":"string"}},{"name":"tag","in":"query","description":"Filter by tag","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of resources","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/escrow/state":{"post":{"tags":["Escrow"],"summary":"Query escrow payment state","description":"\nQueries the on-chain state of an escrow payment from the AuthCaptureEscrow contract.\nThis is a read-only view call (no gas consumed).\n\nReturns the capturable amount, refundable amount, and whether payment has been fully collected.\n\n**Request body:**\n```json\n{\n  \"paymentInfo\": {\n    \"operator\": \"0x...\",\n    \"receiver\": \"0x...\",\n    \"token\": \"0x...\",\n    \"maxAmount\": \"1000000\",\n    \"preApprovalExpiry\": 281474976710655,\n    \"authorizationExpiry\": 281474976710655,\n    \"refundExpiry\": 281474976710655,\n    \"minFeeBps\": 0,\n    \"maxFeeBps\": 100,\n    \"feeReceiver\": \"0x...\",\n    \"salt\": \"0x...\"\n  },\n  \"payer\": \"0x...\",\n  \"network\": \"eip155:8453\",\n  \"extra\": {\n    \"escrowAddress\": \"0x...\",\n    \"operatorAddress\": \"0x...\",\n    \"tokenCollector\": \"0x...\"\n  }\n}\n```\n\n**Response:**\n```json\n{\n  \"hasCollectedPayment\": false,\n  \"capturableAmount\": \"1000000\",\n  \"refundableAmount\": \"0\",\n  \"paymentInfoHash\": \"0x...\",\n  \"network\": \"eip155:8453\"\n}\n```\n","operationId":"path_escrow_state","requestBody":{"description":"Escrow state query","content":{"application/json":{"schema":{"type":"object"}}},"required":true},"responses":{"200":{"description":"Escrow state","content":{"application/json":{"schema":{"type":"object"},"example":{"hasCollectedPayment":false,"capturableAmount":"1000000","refundableAmount":"0","paymentInfoHash":"0xabcdef...","network":"eip155:8453"}}}},"400":{"description":"Query failed","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/feedback":{"get":{"tags":["ERC-8004"],"summary":"Get feedback submission schema","description":"Returns the JSON schema for ERC-8004 feedback submission requests, including all supported networks and related endpoints.","operationId":"path_feedback_get","responses":{"200":{"description":"Feedback schema with supported networks","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"tags":["ERC-8004"],"summary":"Submit reputation feedback","description":"\nSubmits on-chain reputation feedback for an AI agent via the ERC-8004 Reputation Registry (EVM) or Agent Registry with ATOM Engine CPI (Solana).\n\n**Supported networks:** 18 networks (EVM + Solana).\n\n**agentId format:** Numeric (42) for EVM, base58 Pubkey string for Solana. Both JSON numbers and strings are accepted.\n\n**EVM request:**\n```json\n{\n  \"x402Version\": 1,\n  \"network\": \"base\",\n  \"feedback\": {\n    \"agentId\": 42,\n    \"value\": 87,\n    \"valueDecimals\": 0,\n    \"tag1\": \"starred\",\n    \"tag2\": \"quality\",\n    \"endpoint\": \"https://agent.example/api\",\n    \"feedbackUri\": \"ipfs://Qm...\"\n  }\n}\n```\n\n**Solana request:**\n```json\n{\n  \"x402Version\": 1,\n  \"network\": \"solana\",\n  \"feedback\": {\n    \"agentId\": \"7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHkv\",\n    \"value\": 87,\n    \"valueDecimals\": 0,\n    \"tag1\": \"quality\",\n    \"tag2\": \"api\",\n    \"endpoint\": \"https://agent.example/api\",\n    \"feedbackUri\": \"ipfs://Qm...\"\n  }\n}\n```\n\nSolana feedback triggers ATOM Engine CPI for trust scoring (trust tiers, HyperLogLog diversity, EMA quality).\n","operationId":"path_feedback_post","requestBody":{"description":"ERC-8004 feedback request","content":{"application/json":{"schema":{"type":"object"}}},"required":true},"responses":{"200":{"description":"Feedback submission result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Feedback submission failed","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/feedback/response":{"post":{"tags":["ERC-8004"],"summary":"Append response to feedback","description":"\nAppends an agent's response to existing feedback.\n\n**EVM request:**\n```json\n{\n  \"x402Version\": 1,\n  \"network\": \"base\",\n  \"agentId\": 42,\n  \"clientAddress\": \"0x...\",\n  \"feedbackIndex\": 1,\n  \"responseUri\": \"ipfs://Qm...\",\n  \"responseHash\": \"0x...\"\n}\n```\n\n**Solana request** (requires `sealHash` for SEAL v1 integrity, `clientAddress` as Solana Pubkey):\n```json\n{\n  \"x402Version\": 1,\n  \"network\": \"solana\",\n  \"agentId\": \"7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHkv\",\n  \"clientAddress\": \"Bz5K7...\",\n  \"feedbackIndex\": 1,\n  \"responseUri\": \"ipfs://Qm...\",\n  \"responseHash\": \"0x...\",\n  \"sealHash\": \"0xabc123...\"\n}\n```\n","operationId":"path_feedback_response","requestBody":{"description":"Append response request","content":{"application/json":{"schema":{"type":"object"}}},"required":true},"responses":{"200":{"description":"Response appended","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Failed to append response","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/feedback/revoke":{"post":{"tags":["ERC-8004"],"summary":"Revoke feedback","description":"\nRevokes previously submitted reputation feedback.\n\n**EVM request:**\n```json\n{\n  \"x402Version\": 1,\n  \"network\": \"base\",\n  \"agentId\": 42,\n  \"feedbackIndex\": 1\n}\n```\n\n**Solana request** (requires `sealHash` for SEAL v1 integrity):\n```json\n{\n  \"x402Version\": 1,\n  \"network\": \"solana\",\n  \"agentId\": \"7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHkv\",\n  \"feedbackIndex\": 1,\n  \"sealHash\": \"0xabc123...\"\n}\n```\n","operationId":"path_feedback_revoke","requestBody":{"description":"Revoke feedback request","content":{"application/json":{"schema":{"type":"object"}}},"required":true},"responses":{"200":{"description":"Revocation result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Revocation failed","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/health":{"get":{"tags":["Health"],"summary":"Health check","description":"Returns the health status of the facilitator service.","operationId":"path_health","responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object"},"example":{"status":"healthy"}}}}}}},"/identity/{network}/total-supply":{"get":{"tags":["ERC-8004"],"summary":"Get total registered agents","description":"\nReturns the total number of registered agents on a specific network.\n\n**EVM networks** return the ERC-721 totalSupply from the AgentRegistry contract.\n**Solana networks** return the `baseIndex` from the RegistryConfig PDA (total minted agents).\n\n**EVM Response:**\n```json\n{\n  \"network\": \"base\",\n  \"totalSupply\": 156\n}\n```\n\n**Solana Response:**\n```json\n{\n  \"network\": \"solana\",\n  \"totalSupply\": 42\n}\n```\n","operationId":"path_identity_total_supply","parameters":[{"name":"network","in":"path","description":"Network name (e.g., ethereum, base, solana)","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Total supply","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or unsupported network","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/identity/{network}/{agent_id}":{"get":{"tags":["ERC-8004"],"summary":"Get agent identity","description":"\nRetrieves agent identity information from the ERC-8004 Identity Registry.\n\n**EVM networks:** ethereum, base, polygon, arbitrum, optimism, celo, bsc, monad, avalanche + testnets\n\n**Solana networks:** solana, solana-devnet (reads AgentAccount PDA from 8004-solana program)\n\n**EVM Response:**\n```json\n{\n  \"agentId\": 42,\n  \"owner\": \"0x...\",\n  \"agentUri\": \"ipfs://Qm...\",\n  \"agentWallet\": \"0x...\",\n  \"network\": \"base\"\n}\n```\n\n**Solana Response:**\n```json\n{\n  \"agentId\": \"7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHkv\",\n  \"owner\": \"5FHwkrdxPMsgAJBDkWmcoLiN9m1K95VCGw7qr4eXfjsP\",\n  \"agentUri\": \"https://example.com/agent.json\",\n  \"nftName\": \"My AI Agent\",\n  \"feedbackCount\": 47,\n  \"network\": \"solana\"\n}\n```\n","operationId":"path_identity","parameters":[{"name":"network","in":"path","description":"Network name (e.g., ethereum, base, solana, solana-devnet)","required":true,"schema":{"type":"string"}},{"name":"agent_id","in":"path","description":"Agent ID: numeric for EVM (e.g., 42), base58 Pubkey for Solana","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Agent identity","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid network or agent","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/identity/{network}/{agent_id}/metadata/{key}":{"get":{"tags":["ERC-8004"],"summary":"Read agent metadata","description":"\nReads a specific metadata key from an agent's Identity Registry entry.\n\nSupports both EVM and Solana networks. On Solana, metadata is stored in MetadataEntryPda accounts derived from the agent's NFT address and metadata key hash.\n\n**Response:**\n```json\n{\n  \"agentId\": 42,\n  \"key\": \"description\",\n  \"value\": \"0x48656c6c6f\",\n  \"valueUtf8\": \"Hello\",\n  \"network\": \"base\"\n}\n```\n","operationId":"path_identity_metadata","parameters":[{"name":"network","in":"path","description":"Network name (e.g., ethereum, base, solana)","required":true,"schema":{"type":"string"}},{"name":"agent_id","in":"path","description":"Agent ID: numeric for EVM, base58 Pubkey for Solana","required":true,"schema":{"type":"string"}},{"name":"key","in":"path","description":"Metadata key (e.g., description, website, version)","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Metadata value","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid network or agent","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Agent or metadata key not found","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/register":{"get":{"tags":["ERC-8004"],"summary":"Get agent registration schema","description":"Returns the JSON schema for ERC-8004 agent registration requests, including supported networks and body format.","operationId":"path_register_get","responses":{"200":{"description":"Registration schema","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"tags":["ERC-8004"],"summary":"Register a new agent","description":"\nRegisters a new ERC-8004 agent on-chain. The facilitator pays all gas fees.\n\n**Supported networks:** 18 networks (EVM + Solana). EVM chains use ERC-721 NFTs, Solana uses Metaplex Core NFTs.\n\n**EVM request:**\n```json\n{\n  \"x402Version\": 1,\n  \"network\": \"base\",\n  \"agentUri\": \"ipfs://Qm.../agent.json\",\n  \"metadata\": [{\"key\": \"description\", \"value\": \"0x...\"}],\n  \"recipient\": \"0x...\"\n}\n```\n\n**Solana request:**\n```json\n{\n  \"x402Version\": 1,\n  \"network\": \"solana\",\n  \"agentUri\": \"ipfs://Qm.../agent.json\",\n  \"metadata\": [{\"key\": \"x402Support\", \"value\": \"true\"}]\n}\n```\n\n**EVM response:** `agentId` is a numeric string (ERC-721 tokenId).\n**Solana response:** `agentId` is a base58 Pubkey (Metaplex Core NFT mint address).\n\n```json\n{\n  \"success\": true,\n  \"agentId\": \"7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHkv\",\n  \"transaction\": \"5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d6...\",\n  \"owner\": \"facilitator-pubkey...\",\n  \"network\": \"solana\"\n}\n```\n","operationId":"path_register_post","requestBody":{"description":"Agent registration request","content":{"application/json":{"schema":{"type":"object"}}},"required":true},"responses":{"200":{"description":"Registration result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Registration failed","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/reputation/{network}/{agent_id}":{"get":{"tags":["ERC-8004"],"summary":"Get agent reputation","description":"\nQueries the reputation summary for an AI agent from the ERC-8004 Reputation Registry.\n\n**EVM networks:** ethereum, base, polygon, arbitrum, optimism, celo, bsc, monad, avalanche + testnets\n\n**Solana networks:** solana, solana-devnet (reads from ATOM Engine for enriched reputation data)\n\n**Client address filtering (EVM only):** The `clientAddresses` query parameter accepts comma-separated Ethereum addresses to filter reputation data by specific clients. If omitted, the endpoint auto-discovers all clients who have given feedback via the on-chain `getClients()` function.\n\n**Examples:**\n- `/reputation/base/42` - EVM agent (all clients, auto-discovered)\n- `/reputation/solana/7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHkv` - Solana agent (with ATOM stats)\n- `/reputation/base/42?includeFeedback=true&tag1=quality` - with feedback entries filtered by tag\n\n**EVM Response:**\n```json\n{\n  \"agentId\": 42,\n  \"summary\": { \"count\": 15, \"summaryValue\": 87, \"summaryValueDecimals\": 0 },\n  \"feedback\": [...],\n  \"atomStats\": null,\n  \"network\": \"base\"\n}\n```\n\n**Solana Response (includes ATOM Engine bonus data):**\n```json\n{\n  \"agentId\": \"7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHkv\",\n  \"summary\": { \"count\": 47, \"summaryValue\": 78, \"summaryValueDecimals\": 0 },\n  \"atomStats\": {\n    \"trustTier\": 3, \"trustTierName\": \"Trusted\",\n    \"qualityScore\": 78, \"confidence\": 85, \"riskScore\": 12,\n    \"diversityRatio\": 67, \"positiveCount\": 42, \"negativeCount\": 5\n  },\n  \"network\": \"solana\"\n}\n```\n","operationId":"path_reputation","parameters":[{"name":"network","in":"path","description":"Network name (e.g., ethereum, base, solana, solana-devnet)","required":true,"schema":{"type":"string"}},{"name":"agent_id","in":"path","description":"Agent ID: numeric for EVM (e.g., 42), base58 Pubkey for Solana","required":true,"schema":{"type":"string"}},{"name":"include_feedback","in":"query","description":"Include individual feedback entries","required":false,"schema":{"type":"boolean"}},{"name":"client_addresses","in":"query","description":"Comma-separated client addresses to filter by. If omitted, auto-discovers all clients via getClients()","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Reputation data","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid network or agent","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/settle":{"get":{"tags":["Core"],"summary":"Get settlement schema","description":"Returns the JSON schema for payment settlement requests.","operationId":"path_settle_get","responses":{"200":{"description":"Settlement schema","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"tags":["Core"],"summary":"Settle payment on-chain","description":"\nSubmits a verified payment authorization to the blockchain for settlement.\n\n**Process:**\n1. Verifies the payment (same as /verify)\n2. Calls `transferWithAuthorization` on the token contract\n3. Returns transaction hash on success\n\n**Upto Settlement (scheme: \"upto\"):**\n\nWhen `scheme: \"upto\"`, the client provides a Permit2-signed authorization for a maximum amount.\nThe server settles for the actual usage amount (<= authorized max). If actual amount is 0, no\non-chain transaction is submitted.\n\nUses `x402UptoPermit2Proxy.settle(permit, amount, owner, witness, signature)` via Uniswap Permit2.\n\n**Escrow / Commerce Lifecycle (scheme: \"escrow\" or \"commerce\"):**\n\nBoth `\"escrow\"` and `\"commerce\"` schemes are supported and functionally identical.\nThe `\"commerce\"` alias was introduced by x402r for marketplace integrations (e.g., Execution Market).\nThe `action` field controls the operation:\n\n| Action | Description | Signature Required |\n|--------|-------------|-------------------|\n| `authorize` (default) | Lock funds in escrow | Yes (ERC-3009) |\n| `release` | Send escrowed funds to receiver | No |\n| `refundInEscrow` | Return escrowed funds to payer | No |\n\nEscrow contracts deployed on 11 networks. See `/supported` for networks with active PaymentOperator deployments.\n\n**Escrow release/refund payload** (no signature needed):\n```json\n{\n  \"scheme\": \"escrow\",\n  \"action\": \"release\",\n  \"payload\": {\n    \"paymentInfo\": { \"operator\": \"0x...\", \"receiver\": \"0x...\", ... },\n    \"payer\": \"0x...\",\n    \"amount\": \"1000000\"\n  },\n  \"paymentRequirements\": {\n    \"network\": \"eip155:8453\",\n    \"extra\": { \"escrowAddress\": \"0x...\", \"operatorAddress\": \"0x...\", \"tokenCollector\": \"0x...\" }\n  }\n}\n```\n\n**Response on success:**\n```json\n{\n  \"success\": true,\n  \"transaction\": \"0x...\",\n  \"network\": \"base\",\n  \"payer\": \"0x...\"\n}\n```\n\n**Response on failure:**\n```json\n{\n  \"success\": false,\n  \"errorReason\": \"insufficient_balance\",\n  \"payer\": \"0x...\",\n  \"network\": \"base\"\n}\n```\n","operationId":"path_settle_post","requestBody":{"description":"x402 settle request","content":{"application/json":{"schema":{"type":"object"}}},"required":true},"responses":{"200":{"description":"Settlement result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Settlement failed","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/supported":{"get":{"tags":["Discovery"],"summary":"List supported payment kinds","description":"\nReturns all supported payment kinds (network + scheme + version combinations).\n\n**Schemes:**\n- `exact` - Direct EIP-3009 payment settlement (v1 and v2 formats)\n- `upto` - Permit2-based variable amount settlement (v2 only, CAIP-2 networks). Client authorizes a max amount; server settles actual usage (<= max). Ideal for usage-based pricing (LLM tokens, bandwidth, metered APIs).\n- `escrow` - x402r PaymentOperator escrow (v2 only, CAIP-2 networks)\n- `fhe_transfer` - FHE encrypted transfer via Zama (v1 and v2)\n\n**Upto networks:** All EVM networks that support the `exact` scheme also support `upto` via the x402UptoPermit2Proxy contract (Permit2-based, CREATE2 address `0x4020633461b2895a48930Ff97eE8fCdE8E520002`).\n\n**Escrow networks (9 total):** Base, Ethereum, Polygon, Arbitrum, Celo, Monad, Avalanche, Base Sepolia, Ethereum Sepolia.\nOnly networks with a deployed PaymentOperator appear in the response.\n\n**Response includes both v1 and v2 formats:**\n- v1: `\"network\": \"base\"` (string enum)\n- v2: `\"network\": \"eip155:8453\"` (CAIP-2 format)\n","operationId":"path_supported","responses":{"200":{"description":"Supported payment kinds","content":{"application/json":{"schema":{"type":"object"},"example":{"kinds":[{"x402Version":1,"scheme":"exact","network":"base"},{"x402Version":2,"scheme":"exact","network":"eip155:8453"},{"x402Version":2,"scheme":"upto","network":"eip155:8453"},{"x402Version":2,"scheme":"escrow","network":"eip155:8453","extra":{"escrowAddress":"0xb9488351E48b23D798f24e8174514F28B741Eb4f","operatorAddress":"0x...","tokenCollector":"0x48ADf6E37F9b31dC2AAD0462C5862B5422C736B8"}}]}}}}}}},"/verify":{"get":{"tags":["Core"],"summary":"Get verification schema","description":"Returns the JSON schema for payment verification requests.","operationId":"path_verify_get","responses":{"200":{"description":"Verification schema","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"tags":["Core"],"summary":"Verify payment authorization","description":"\nVerifies an x402 payment authorization without settling it on-chain.\n\n**Checks performed:**\n- Payload structure validation\n- EIP-712 signature verification\n- Nonce validity\n- Amount matching\n- Timestamp validity (validAfter/validBefore)\n- Token and network support\n\n**Request body:**\n```json\n{\n  \"x402Version\": 1,\n  \"paymentPayload\": {\n    \"signature\": \"0x...\",\n    \"payload\": {\n      \"scheme\": \"exact\",\n      \"network\": \"base\",\n      \"asset\": \"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\",\n      \"from\": \"0x...\",\n      \"to\": \"0x...\",\n      \"amount\": \"1000000\",\n      \"validAfter\": 1700000000,\n      \"validBefore\": 1700100000,\n      \"nonce\": \"0x...\"\n    }\n  },\n  \"paymentRequirements\": {\n    \"scheme\": \"exact\",\n    \"network\": \"base\",\n    \"maxAmountRequired\": \"1000000\",\n    \"payTo\": \"0x...\",\n    \"asset\": \"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\"\n  }\n}\n```\n","operationId":"path_verify_post","requestBody":{"description":"x402 verify request","content":{"application/json":{"schema":{"type":"object"}}},"required":true},"responses":{"200":{"description":"Verification result","content":{"application/json":{"schema":{"type":"object"},"example":{"isValid":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object"},"example":{"error":"Invalid signature"}}}}}}},"/version":{"get":{"tags":["Discovery"],"summary":"Get facilitator version","description":"Returns the current version of the facilitator. The version always matches the Cargo.toml package version.","operationId":"path_version","responses":{"200":{"description":"Version info","content":{"application/json":{"schema":{"type":"object"},"example":{"version":"(current Cargo.toml version)"}}}}}}}},"components":{},"tags":[{"name":"Core","description":"Core x402 payment verification and settlement (exact, upto, escrow schemes)"},{"name":"Escrow","description":"Gasless escrow lifecycle (authorize, release, refund, state query)"},{"name":"Discovery","description":"Network and scheme discovery"},{"name":"ERC-8004","description":"AI Agent reputation and identity (ERC-8004 Trustless Agents) - 18 networks (EVM + Solana)"},{"name":"Bazaar","description":"Decentralized resource discovery registry"},{"name":"Compliance","description":"OFAC compliance and sanctions screening"},{"name":"Health","description":"Service health and status"}]}