# 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: 0xAB745e5F576667037696e78ba7dA28E193E4423D
- 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. Wisdom envelope: verdict, implementation_prompt, 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.","implementation_prompt":"…","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":"…"}`

### 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":"…"}`

### 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":"…","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 prompt + 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":"…"}`


## 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": "Executable prompt for code generation",
  "risk": "LOW | MEDIUM | HIGH",
  "citations": [
    "https://docs.cdp.coinbase.com/x402"
  ],
  "receipt": {
    "settled": true,
    "proofId": "0x...",
    "blockHeight": 51208621,
    "signer": "0xAB745e5F576667037696e78ba7dA28E193E4423D"
  }
}
```