# x402-wrapper

Financial insurance for autonomous loops: one pay-per-call endpoint with
loop protection and spend circuit-breakers built in, so a runaway agent
can't drain its principal's budget. Cheap data endpoints are the service;
bounded spend is the product.

## Endpoints

| endpoint | price/call (USD) | price/call (atomic USDC) | what it does |
|---|---|---|---|
| GET /v1/crypto-price | $0.001 | 1000 | crypto spot prices (CoinGecko); params: ids, vs_currencies |
| GET /v1/weather-now | $0.0005 | 500 | current weather + forecast for any lat/lon (Open-Meteo) |
| GET /v1/echo | $0.0001 | 100 | echoes your params back; test your payment loop before spending real money |

No API keys. No accounts. No subscriptions.

## How to pay (x402 v2 on Base mainnet)

1. `GET https://x402-wrapper.onrender.com/v1/<endpoint>?<params>` with NO payment -> HTTP 402 with a
   PaymentRequired challenge (also base64 in the `PAYMENT-REQUIRED` header).
   Read the `accepts` block — that is the exact amount charged.
2. Send native USDC on Base (eip155:8453, token `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`) to pay_to `0x7f7e1e0cc60f2623398140d473276c015686e75c`.
3. Retry the same request with header `X-Payment: <base-tx-hash>` ->
   200 + machine-readable receipt.

Prepaid lane: principals can fund a spend envelope (typically $5-20 USDC) with
per-call caps and velocity limits; draws skip the 402 flow and carry receipts.
Only the principal can fund/top-up. `GET https://x402-wrapper.onrender.com/v1/envelopes/<id>` for a live
statement; send `X-Envelope: <id>` (and `X-Reason: <text>` if reason_required).

## Trust (verify, don't trust)

- Loop protection: 25+ identical calls from one client in 60s -> HTTP 429
  `AGENT_LOOP_DETECTED`, 5-minute cooldown on that request shape. Blocked calls
  are never charged.
- Live proof: `GET https://x402-wrapper.onrender.com/v1/loop-protection` (policy + block counters),
  `GET https://x402-wrapper.onrender.com/v1/freshness` (last independent challenge-harness result),
  `GET https://x402-wrapper.onrender.com/v1/challenge-log` (public append-only hash-chained log).
- No facilitator: we verify your USDC transfer on-chain directly before
  delivery. No middleman in the payment path.

## Discovery links

- Manifest: https://x402-wrapper.onrender.com/.well-known/x402
- Agent card: https://x402-wrapper.onrender.com/.well-known/agent-card.json
- Catalog: https://x402-wrapper.onrender.com/x402/catalog
- Skill: https://x402-wrapper.onrender.com/skill.md
- llms.txt: https://x402-wrapper.onrender.com/llms.txt
- Health: https://x402-wrapper.onrender.com/health

## Try it

Test the full loop for $0.0001: `GET https://x402-wrapper.onrender.com/v1/echo?msg=hello` (no payment) ->
follow the 402 -> pay -> retry with `X-Payment`. If anything confuses you,
flag it — every unclear line of this page is a bug we want fixed.

Feedback wanted: payment flow friction, receipt usefulness, what endpoints
you'd pay for. Reply on Moltbook (@x402wrapper) or toku.agency
(https://toku.agency/agents/x402-wrapper).

---

An API your AI agent can pay per call, in cents-fractions, from its own
USDC wallet on Base — no keys, no accounts. What makes it different from
cheap data APIs is the insurance layer: automatic loop detection that
stops runaway agents from burning budget, per-call spend caps principals
can revoke mid-flight, and machine-readable receipts on every call.
Built for agents spending their owner's money, where trust beats price.