# X402 Helper API

> Universal API for AI agents - news, weather, finance, coding, translations, analytics, etc. Paid via USDC micropayments on Base, Solana, BSC, Arbitrum, and SEI.

## MCP Server
- [MCP Endpoint](https://x402helper.xyz/mcp): Streamable HTTP MCP server. Tools:
  - `search_endpoints` - find paid APIs by task (free).
  - `call_endpoint` - execute a found route with x402 payment.
  - `day_summary` - free morning brief: weather + indices + crypto + top news in one call.
  - `get_my_history` - `get_my_history` - free read-only history of your own successful paid calls. Pass the `buyerID` you received as `meta.yourID` in any successful paid call (e.g. https://x402helper.xyz/test-billing)..
  Connect any MCP-compatible agent.

## API & Documentation
- [OpenAPI Specification](https://x402helper.xyz/openapi.json): Full API contract - endpoints, parameters, schemas.
- [X402 Payment Manifest](https://x402helper.xyz/.well-known/x402.json): Pricing, accepted networks, and payTo addresses.

## Discovery

- [Route Discovery](https://x402helper.xyz/discovery): Free route discovery for agents. Use when an endpoint returns 503 ROUTE_BLOCKED, or when you have a task but aren't sure which endpoint is the right one - don't guess, ask discovery.

  - Endpoint: `POST https://x402helper.xyz/discovery`
  - Content-Type: `application/json`
  - Body (any of):
    - `{ "prompt": "<natural-language task>" }` - the service decomposes your task into queries itself (LLM planner, may be charged a small discovery fee).
    - `{ "queries": ["<precise query 1>", "<precise query 2>"] }` - you already decomposed the task; **zero discovery fee**.
    - Optional: `{ "maxRoutesPerQuery": 1..5 }` (default 3), `{ "budget": { "maxTotalPrice": 0.05, "currency": "USDC" } }`.
  - Response (HTTP 200):
    {
      "status": "ok",
      "mode": "discovery",
      "queries": [{ "id": "q1", "text": "..." }],
      "budget": { "maxTotalPrice": 0.05, "currency": "USDC" },
      "plan": [
        {
          "step": 1,
          "queryId": "q1",
          "query": "...",
          "routes": [
            {
              "routeIndex": 1,
              "routeId": "routeId",
              "route": { "method": "GET", "url": "https://x402helper.xyz/<routeId>/<path>", "price": 0.001, "description": "...", "score": 0.12 },
              "parameters": [],
              "requestBody": null,
              "args": null,
              "status": "recommended"
            }
          ]
        }
      ],
      "estimate": { "total": 0.0012, "currency": "USDC", "planTotal": 0.003, "minPlanCost": 0.001, "overBudget": false },
      "meta": { "plannerSource": "client", "routesConsidered": 12, "routesRecommended": 3 }
    } 

    Empty result: plan: [] with mode: "discovery" and meta.note: "no_routes_found" - this is a valid 200, not an error. Try rephrasing the task or use queries[].

    estimate.planTotal = sum of all recommended routes. estimate.minPlanCost = cheapest route per step (minimum to solve the task). If estimate.overBudget: true, the cheapest plan exceeds your budget.maxTotalPrice.

    Then: pick one route per step from plan[].routes[].route.url, fill parameters/requestBody, and call it with x402 payment as usual.

- [Agent Manifest](https://x402helper.xyz/.well-known/agent.json): Agent identity, operator info, capability links, and the machine-readable discovery contract (`capabilities.discovery`).


## Buyer Identity & Call History

- Every successful paid response includes `meta.yourID` - an 8-char lowercase hex ID derived from your wallet address. Store it; it is the only key you need to retrieve your own history.
- [Get My History](https://x402helper.xyz/getmyhistory): free read-only access to your own successful paid calls.

  - Endpoint: `GET https://x402helper.xyz/getmyhistory?buyerID=<8-hex>`
  - Free. Rate limit: 15 requests / 10 min per IP.
  - Response (HTTP 200, always - `found: false` is not an error):
    {
      "status": "ok",
      "buyerID": "50203f4e",
      "found": true,
      "successfulCalls": 2,
      "firstSeenAt": "2026-10-30T14:08:31.982Z",
      "lastSeenAt": "2026-10-30T14:10:15.968Z",
      "routes": {
        "r1": {
          "calls": 1,
          "firstCallAt": "...",
          "lastCallAt": "...",
          "events": [
            { "ts": "...", "endpoint": "/test-billing", "network": "eip155:8453", "amount": "0.001", "facilitator": "coinbase", "params": null }
          ]
        }
      },
      "meta": { "timestamp": "...", "yourID": "50203f4e", "contacts": "info@allai.pw" }
    }
    Equivalent MCP tool: get_my_history({ buyerID }).
    Only successful paid calls are recorded; free probes and discovery-only calls are not.

## Optional
- [Website](https://x402helper.xyz): Human-readable landing page with live tests and network details.