Documentation · Quickstart

x402 Agent-Wallet Quickstart

x402 is the standard that lets software pay for an API call inside the same HTTP request. Any x402-compatible client can pay our endpoints, which return data about ERC-8004 agents (the draft Ethereum standard for on-chain agent identity), in three steps: call, sign, retry. USDC (a dollar stablecoin) on Base or Ethereum. No account. No API key.

Full reference: /docs · Live offer manifest: /.well-known/x402.json · OpenAPI 3.1: /v1/public/openapi.json

The 3-step flow — 402, sign, retry

Every /v1/intel/* endpoint on api.onchainagentintel.io speaks standard x402 (v1 challenges; payments are accepted in v1 or v2 headers). Point any x402-compatible client at the URL and the client takes care of the sign-and-retry handshake.

  • Step 1 — client calls the endpoint with no payment. Server returns HTTP 402 with a JSON body carrying payment_options[]: networks, assets, maxAmountRequired, and the payTo address.
  • Step 2 — client signs an EIP-3009 transferWithAuthorization against the chosen USDC contract. No gas is spent at this step; the signature is off-chain.
  • Step 3 — client retries the same request with the signed authorization in a PAYMENT-SIGNATURE (x402 v2) or X-PAYMENT (v1) header. Server verifies the EIP-712 signature, broadcasts the USDC transfer, and returns HTTP 200 with the paid data in the same response.

No polling and no webhook: the paid data comes back on the retry.

Free 402 demo — see the challenge shape without spending

Step 1 is free. A plain curl against our cheapest paid endpoint returns the 402 challenge body — all the discovery fields your client needs, no payment required.

curl — free 402 demo (no spend)
curl -sS -i 'https://api.onchainagentintel.io/v1/intel/agent/19353?chain=base'

Response (shape, abbreviated):

HTTP/1.1 402 Payment Required
Content-Type: application/json
PAYMENT-REQUIRED: <base64 x402 v2 PaymentRequired: CAIP-2 network, amount>

{
  "x402Version": 1,
  "error": "Payment Required",
  "accepts": [
    {
      "scheme":            "exact",
      "network":           "base",
      "maxAmountRequired": "10000",
      "payTo":             "0xaCd134d2AAd0b868EDb395F7d151864188caaF1a",
      "asset":             "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "resource":          "https://api.onchainagentintel.io/v1/intel/agent/19353",
      "extra": { "name": "USD Coin", "version": "2", "decimals": 6 }
    },
    { "scheme": "exact", "network": "ethereum", "maxAmountRequired": "10000", "payTo": "0xaCd134d2…", "asset": "0xA0b86991…", "extra": {"name":"USD Coin","version":"2","decimals":6} }
  ],
  "payment_options": [ /* same list in our native shape with USDC + ETH per chain */ ],
  "preview": { "agent_id": 19353, "chain": "base", "name": "Agent Zero" }
}

That is all a correctly-implemented x402 client needs. The maxAmountRequired is in USDC raw units (6 decimals) — 10000 is $0.01. The payTo is our Safe on Base and Ethereum (same address on both chains).

Standard x402 clients should be able to pay

Our server follows the standard x402 HTTP flow with no provider-specific extensions. A client that can call fetch, handle a 402, sign EIP-3009 and set the PAYMENT-SIGNATURE (x402 v2) or X-PAYMENT (v1) header should be able to pay. That includes:

  • x402-fetch / x402-axios — drop-in wrappers around fetch and axios. The helper intercepts the 402, signs with your wallet, and retries transparently. Point them at any /v1/intel/* URL on our API host.
  • Coinbase Developer Platform agent wallet — CDP ships an agent-wallet SDK with x402 payment support built in. We are not currently listed in Coinbase's x402 Bazaar; our offer manifest at /.well-known/x402.json is the machine-readable listing.
  • x402-compatible agent frameworks — any framework that treats x402 as a first-class HTTP response (402 → sign → retry) should handle our endpoints without a custom adapter. We have not tested every client, so start with a small first payment.
  • Your own signer — if you prefer to hand-roll EIP-712, the full EIP-3009 struct and the exact PAYMENT-SIGNATURE (x402 v2) or X-PAYMENT (v1) JSON envelope are documented in USDC via EIP-3009. The hand-rolled Python example in /docs#quickstart is end-to-end and runnable.

There is no white-list or allow-list on our side. The server answers the 402 handshake the same way for every caller.

MCP clients — six free tools

An MCP client can see what we offer before deciding to pay. We publish a free MCP (Model Context Protocol) server at https://api.onchainagentintel.io/mcp with six read-only tools: get_coverage_stats, get_leaderboards, get_agent_summary, get_network_teaser, list_payable_x402_endpoints, and the credit-score-style agent_trust_teaser (name + readiness bucket + 1-line verdict headline only; the full trust verdict, readiness score, risk flags, and money-flow breakdown are null-redacted with a live x402 unlock pointer). Each response carries an unlock-block that links back to the paid /v1/intel/* endpoints for anything the free tier does not cover.

Any MCP client that proxies 402 challenges to its wallet layer (or that calls out to an x402 HTTP client under the hood) can pay for the paid endpoints inline. The flow is the same as any other x402 call — 402, sign, retry.

Our MCP server is also published to the official MCP registry. A client with registry discovery can reach it without a hard-coded URL.

Read our prices without a 402

Our offer manifest lists every paid endpoint, so a client can read prices before it makes any request. Directories such as Coinbase's x402 Bazaar catalog paid endpoints for buyers to browse; this manifest is the machine-readable description of ours. It lives at:

curl — live offer manifest (free)
curl https://onchainagentintel.io/.well-known/x402.json

It carries every paid endpoint with its full accepts[] block — network, asset, maxAmountRequired, payTo, timeout, and the resource URL. A client can discover and price every call without hitting a 402 first.

The manifest is the authoritative source for prices. Anything quoted on this page is a snapshot — call the manifest for the live number.

Skip per-call payments — $5 for 30 days

For agents that will make more than a handful of /v1/intel/* calls, a 30-day pass pays once and bypasses the per-call 402. Same x402 flow — the subscription endpoint also returns 402 the first time, you pay $5 USDC, and subsequent intel calls that carry a signed proof of wallet ownership (X-Pass-Wallet, X-Pass-Timestamp, X-Pass-Signature) return 200 directly. A bare ?wallet= is not accepted as proof.

curl — buy a 30-day pass
curl -sS -i -X POST https://api.onchainagentintel.io/v1/intel/subscribe

Full pass contract and the subscription-status polling endpoint are in /docs#subscription, with the signing message and Python and JavaScript examples.

Endpoints and prices (snapshot — manifest is authoritative)

Snapshot of what you can pay for right now. The live price lives in /.well-known/x402.json; if a number here drifts, the manifest wins.

  • Agent profile — GET /v1/intel/agent/{agent_id}?chain=base · $0.01 USDC per call
  • Capability search — POST /v1/intel/search · $0.02 USDC per call
  • Peers — GET /v1/intel/peers/{agent_id}?chain=base · $0.02 USDC per call
  • Activity delta — GET /v1/intel/delta?since=… · $0.02 USDC per call
  • Trending — GET /v1/intel/trending · $0.05 USDC per call
  • Market overview — GET /v1/intel/market · $0.05 USDC per call
  • Payment graph — GET /v1/intel/graph · $0.05 USDC per call
  • 30-day pass — POST /v1/intel/subscribe · $5.00 USDC flat (unlimited intel calls for 30 days)
  • Smart-contract audit — POST /v1/audit · $10.00 USDC per report

All amounts are USDC. Base and Ethereum are both accepted on every intel endpoint. The payTo is our Safe at 0xaCd134d2AAd0b868EDb395F7d151864188caaF1a — same address on both chains.

FAQ

Do I need an account or API key?

No. Every /v1/intel/* endpoint is x402-gated. Pay USDC per call or buy a 30-day pass; there is no sign-up and no API key to manage.

Which x402 client libraries work?

Any client that implements the standard x402 HTTP flow should be able to: x402-fetch, x402-axios, the Coinbase Developer Platform agent wallet, and MCP clients that proxy 402 payments. The server answers in the standard shape — HTTP 402 with payment_options[], then HTTP 200 after a valid PAYMENT-SIGNATURE (x402 v2) or X-PAYMENT (v1) header.

Which chains and assets do you accept?

USDC on Base and Ethereum. Base is cheaper for agent micropayments; Ethereum is useful when the agent's treasury is already on L1. See /.well-known/x402.json for the authoritative per-endpoint list.

Can I discover endpoints without hitting a 402 first?

Yes. /.well-known/x402.json carries every paid endpoint with its accepts[] block, so a client can read prices before making any request.

How do I avoid paying per call?

POST /v1/intel/subscribe pays $5 USDC once for 30 days of unlimited /v1/intel/* access. Pass your wallet as the wallet query parameter on subsequent calls to bypass per-query payment.

What is the Safe at 0xaCd134d2…?

It is our payment settlement wallet on Base and Ethereum (same address on both chains). Every x402 payment and every ETH calldata call settles there. It is a Gnosis Safe multisig, not an EOA.