# x402 Oracle — Full Technical Reference > 402 is the answer. The Oracle is how you ask. ## Architecture Overview x402 Oracle is a seller-only autonomous oracle providing on-chain state verification, smart contract consultation, and MCP auditing. Requests without payment receive HTTP 402 Payment Required challenges containing Base USDC payment parameters. Clients sign payment authorizations via EIP-712 and attach the PAYMENT-SIGNATURE header to complete the consultation. ## Machine Discovery Endpoints - Catalog: https://x402orcle.vercel.app/.well-known/x402 - Agent Card: https://x402orcle.vercel.app/.well-known/agent-card.json - MCP: https://x402orcle.vercel.app/.well-known/mcp.json - Funding: https://x402orcle.vercel.app/.well-known/funding.json - OpenAPI: https://x402orcle.vercel.app/openapi.json - LLMs Minimal: https://x402orcle.vercel.app/llms.txt - Agents: https://x402orcle.vercel.app/agents.txt - MCP RPC Endpoint: https://x402orcle.vercel.app/mcp ## Payment Parameters - Facilitator: https://api.cdp.coinbase.com/platform/v2/x402 - Network: eip155:8453 (Base Mainnet / eip155:8453) - Asset: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (USDC on Base) - PayTo: 0x0d25A44f74868eCE53B305C97139CF4B62963410 - Challenge Header: PAYMENT-REQUIRED (Base64 JSON) - Authorization Header: PAYMENT-SIGNATURE - Receipt Header: PAYMENT-RESPONSE ## Tool Catalog & Schemas ### Oracle Health (`oracle_health`) - Tier: free - Price: Free - HTTP: GET /api/health - Description: Free liveness + seller posture (payTo configured, no spend key, network, demo/live). - Input Example: `{}` - Output Example: `{"ok":true,"service":"x402 Oracle","wallet_configured":false,"pay_to_configured":true,"network":"eip155:8453"}` ### Oracle Pricing (`oracle_pricing`) - Tier: free - Price: Free - HTTP: GET /api/pricing - Description: Free menu of paid consults, A2A tasks, and connect how-to. No keys requested. - Input Example: `{}` - Output Example: `{"tools":[],"maxPriceUsd":25,"network":"eip155:8453"}` ### Oracle Ask (`oracle_ask`) - Tier: paid - Price: $0.1 USDC - HTTP: POST /api/consult/oracle_ask - Description: Paid x402/MCP/A2A/Bazaar consult. JSON wisdom envelope: verdict, wisdom, developer build notes, risk, citations, receipt. - Input Example: `{"question":"Why is my Bazaar listing unranked after 402s with no settlement?","audience":"agent"}` - Output Example: `{"verdict":"no_rank_without_settle","wisdom":"Cataloging is settlement-triggered.","risk":"burning USDC on frozen catalog copy","citations":["https://docs.cdp.coinbase.com/x402/seller/get-discovered"]}` ### Diagnose 402 (`oracle_diagnose_402`) - Tier: paid - Price: $0.5 USDC - HTTP: POST /api/consult/oracle_diagnose_402 - Description: Post-mortem a 402 handshake: PAYMENT-REQUIRED shape, bazaar extension, network, asset, resource.url. - Input Example: `{"challenge_b64_or_json":"eyJ4NDAyVmVyc2lvbiI6Mn0=","resource_url":"https://example.com/paid"}` - Output Example: `{"verdict":"missing_bazaar_extension","wisdom":"A live 402 must be standard base64 JSON with accepts[] (scheme exact, network eip155:8453, Base USDC) and extensions.bazaar.info.input.method."}` ### Review MCP (`oracle_review_mcp`) - Tier: paid - Price: $3 USDC - HTTP: POST /api/consult/oracle_review_mcp - Description: Review an MCP paid-tool server for createPaymentWrapper, free health tool, discovery extension, burner isolation. - Input Example: `{"mcp_url":"https://example.com/mcp","notes":"streamable-http, two paid tools"}` - Output Example: `{"verdict":"needs_free_health_tool","wisdom":"A Bazaar-ready paid MCP server must expose createPaymentWrapper (or equivalent), x402ResourceServer on eip155:8453, declareDiscoveryExtension with toolName, a free health tool, paid consults, and streamable-http at /mcp."}` ### Bazaar Rewrite (`oracle_bazaar_rewrite`) - Tier: paid - Price: $1.5 USDC - HTTP: POST /api/consult/oracle_bazaar_rewrite - Description: Rewrite serviceName (≤32), description (≤500), tags (≤5) for buyer-query rank. Warns on first-index freeze. - Input Example: `{"current_description":"API for data","buyer_phrases":["x402 mcp oracle","paid mcp bazaar"]}` - Output Example: `{"serviceName":"x402 MCP Oracle","description":"Paid MCP consults for x402, Bazaar ranking, A2A tasks, burner isolation.","tags":["x402","mcp","bazaar"]}` ### Oracle Task (`complete_oracle_task`) - Tier: paid - Price: $10 USDC - HTTP: POST /api/consult/complete_oracle_task - Description: Outcome A2A task: typed diffs, operator handoff notes, and revenue/risk for a concrete x402 shipping goal. - Input Example: `{"goal":"List oracle_ask on CDP Bazaar after first mainnet settle","constraints":"seller-only host, no EVM_PRIVATE_KEY"}` - Output Example: `{"verdict":"ship_seed_settle","wisdom":"Outcome task: deploy HTTPS → GET 402 crawler on every paid POST → CDP validate → one seed settle from a local burner with USDC on Base → confirm discovery/search."}` ## Wisdom Envelope Format Paid consultation endpoints return a structured Wisdom Envelope object: ```json { "verdict": "APPROVE | WARN | REJECT", "wisdom": "In-depth analysis and guidance", "implementation_prompt": "Developer build notes (plain text, for human review)", "risk": "LOW | MEDIUM | HIGH", "citations": [ "https://docs.cdp.coinbase.com/x402" ], "receipt": { "settled": true, "proofId": "0x...", "blockHeight": 51208621, "signer": "0x0d25a44f74868ece53b305c97139cf4b62963410" } } ```