ERC-8004 & x402 API Docs — Live Agent Registry Access

agent.json — Service Discovery

We publish a machine-readable ERC-8004 service manifest at /agent.json. This is the recommended starting point for any autonomous agent integrating with our service. It contains all available endpoints, payment options, USDC contract addresses, and pricing — everything needed to make a first query without any prior configuration.

Fetch the manifest

curl https://api.onchainagentintel.io/agent.json

The manifest follows the ERC-8004 metadata standard. Key fields:

services[] — each service with its endpoint, method, and payment_options[]
payment_options[].token — USDC entries include token_address, amount_units, and payment_method: "EIP-3009"
payment_options[].preferred — true on USDC entries; use these first
payment.preferred_asset — "USDC"
payment.usdc_contracts — USDC contract addresses per chain

Python — read preferred payment option for a service

import httpx

manifest = httpx.get("https://api.onchainagentintel.io/agent.json").json()

profile_svc = next(s for s in manifest["services"] if s["id"] == "agent-intel-profile")
preferred = next(o for o in profile_svc["payment_options"] if o.get("preferred"))

print(preferred["token"])          # USDC
print(preferred["amount_units"])   # 10000 (0.01 USDC, 6 decimals)
print(preferred["token_address"])  # 0x833589f... (Base USDC)
print(preferred["payment_method"]) # EIP-3009
print(profile_svc["endpoint"])     # https://api.onchainagentintel.io/v1/intel/agent/{agent_id}

Public Endpoints — Free, No Payment

Three endpoints are open and unauthenticated — no x402, no API key. They return aggregate counts only (the same no-PII discipline as the 402 previews), are CORS-enabled, and are cached for 5 minutes. Every number on this site is pulled live from /v1/public/stats — nothing is hardcoded.

Live coverage right now

26,466

Registered Agents

2,173

Live Right Now

8,775

MCP Tools

13,170

OpenAPI Methods

953

Named Owners

Registered = on-chain ERC-8004 registration. Live = endpoint answers 2xx and advertises an MCP / OpenAPI / .well-known capability surface (shared task 0154 predicate).

GET /v1/public/stats

Aggregate coverage statistics. Counts/floats only.

curl https://api.onchainagentintel.io/v1/public/stats

{
  "agents_indexed": 39171,
  "profile_store_size": 38990,
  "owners_total": 9872,
  "owners_named": 815,
  "mcp_agents": 1817,
  "mcp_tools_total": 19890,
  "openapi_agents": 438,
  "openapi_methods_total": 22579,
  "well_known_agents": 2127,
  "contracts_verified": 12012,
  "eoas_identified": 112,
  "chains_breakdown": { "base": 14984, "eth": 1436 },
  "generated_at": "2026-06-01T18:09:21Z"
}

Example values — call the endpoint for the current snapshot.

GET /v1/public/leaderboards

Top agents by live MCP tool count (50) and OpenAPI method count (50), plus the 20 most-recently-indexed agents. Public names + counts only.

curl https://api.onchainagentintel.io/v1/public/leaderboards

{
  "top_mcp":     [ { "agent_id": 22767, "chain": "base", "name": "…", "mcp_tools": 60, "detail_url": "https://onchainagentintel.io/agent/base/22767" }, … ],
  "top_openapi": [ { "agent_id": 0, "chain": "base", "name": "…", "openapi_methods": 0, "detail_url": "…" }, … ],
  "recent":      [ { "agent_id": 0, "chain": "base", "name": "…", "indexed_at": "…", "detail_url": "…" }, … ],
  "generated_at": "…"
}

GET /v1/public/agent/{chain}/{agent_id}

Free public summary for one agent — backs shareable /agent/{chain}/{id} pages. Returns objective, goal-agnostic objective_signals the reader can verify, plus a neutral derived status_label. The owner's resolved identity string, endpoint URLs, and exact payment amounts are paid (see Agent Profile Lookup); this returns only booleans (owner_named, payments_received).

curl https://api.onchainagentintel.io/v1/public/agent/base/22767

{
  "agent_id": 22767,
  "chain": "base",
  "name": "EruditePay Facilitator",
  "status_label": "Live & monetized",
  "objective_signals": {
    "reachable": true,
    "http_status": 401,
    "response_ms": 142,
    "tls_valid": true,
    "tls_expires_at": "…",
    "x402_supported": true,
    "payments_received": true,
    "mcp_tool_count": 60,
    "openapi_method_count": 0,
    "has_well_known": true,
    "owner_named": false,
    "owner_is_contract": true,
    "owner_contract_verified": false,
    "last_indexed_at": "…",
    "last_active_check": "…"
  },
  "capabilities": { "mcp_tools": 60, "openapi_methods": 0, "has_well_known": true },
  "owner_named": false,
  "last_indexed_at": "…",
  "generated_at": "…"
}

Example agent — pass any indexed {chain}/{agent_id}. Unknown agents return 404.

objective_signals — every field is observed, not opinion. Booleans are tri-state (true / false / null when not yet probed): reachable, http_status, response_ms (host probe); tls_valid, tls_expires_at (certificate); x402_supported (advertised x402 capability); payments_received (any realized on-chain inflow — amounts are paid); mcp_tool_count, openapi_method_count, has_well_known (live capabilities); owner_named, owner_is_contract, owner_contract_verified (owner); last_indexed_at, last_active_check (freshness).

status_label — a neutral roll-up. Liveness and monetization are judged independently (a 401/403 is auth-gated, not dead — the normal shape for a paid agent):

Live & monetized — reachable and either payments_received or x402_supported.
Live, no payments — reachable, but no realized payments and no advertised x402.
Stub or unreachable — no response/timeout, 404, or 5xx.
Unknown — not yet probed (insufficient data).

Note: the internal verdict field previously returned here has been removed — it was a private lead score, not a customer signal. Use status_label.

Quick Start

The fastest path to a result: fetch agent.json, make a request, pay with USDC via EIP-3009, receive data in the same response.

Python — full end-to-end example (agent profile lookup)

import httpx
from eth_account import Account
from eth_account.messages import encode_structured_data
import time, json

PRIVATE_KEY   = "0xYOUR_PRIVATE_KEY"
AGENT_WALLET  = Account.from_key(PRIVATE_KEY).address
API_BASE      = "https://api.onchainagentintel.io"   # paid /v1/* endpoints
SITE_BASE     = "https://onchainagentintel.io"       # serves /agent.json manifest
TARGET_AGENT  = 19353   # any ERC-8004 agentId
CHAIN         = "base"

# 1. Make the request — expect a 402
r = httpx.get(f"{API_BASE}/v1/intel/agent/{TARGET_AGENT}",
              params={"chain": CHAIN})
assert r.status_code == 402

body = r.json()
# Pick the preferred USDC option on Base
opt = next(o for o in body["payment_options"]
           if o.get("token") == "USDC" and o["network"] == "base")

# 2. Sign EIP-3009 transferWithAuthorization
nonce = "0x" + secrets.token_hex(32)
deadline = int(time.time()) + 300   # 5-minute window

auth_data = {
    "types": {
        "EIP712Domain": [
            {"name":"name","type":"string"},
            {"name":"version","type":"string"},
            {"name":"chainId","type":"uint256"},
            {"name":"verifyingContract","type":"address"},
        ],
        "TransferWithAuthorization": [
            {"name":"from","type":"address"},
            {"name":"to","type":"address"},
            {"name":"value","type":"uint256"},
            {"name":"validAfter","type":"uint256"},
            {"name":"validBefore","type":"uint256"},
            {"name":"nonce","type":"bytes32"},
        ],
    },
    "domain": {
        "name": "USD Coin",
        "version": "2",
        "chainId": 8453,
        "verifyingContract": opt["token_address"],
    },
    "primaryType": "TransferWithAuthorization",
    "message": {
        "from":        AGENT_WALLET,
        "to":          opt["address"],
        "value":       int(opt["amount_units"]),
        "validAfter":  0,
        "validBefore": deadline,
        "nonce":       nonce,
    },
}

signed = Account.sign_typed_data(PRIVATE_KEY, full_message=auth_data)
x_payment = json.dumps({
    "x402Version": 1,
    "scheme": "exact",
    "network": "base",
    "payload": {
        "authorization": auth_data["message"],
        "signature": signed.signature.hex(),
    },
})

# 3. Retry with X-PAYMENT header — receive result immediately
result = httpx.get(
    f"{API_BASE}/v1/intel/agent/{TARGET_AGENT}",
    params={"chain": CHAIN},
    headers={"X-PAYMENT": x_payment},
)
assert result.status_code == 200
print(result.json())

x402 Payment Flow

Every endpoint follows this pattern regardless of payment method:

1

Initial request → 402

Call any /v1/ endpoint without payment. The response is HTTP 402 with a JSON body containing payment_options[], a unique request ID, and a preview of the result (risk level, issue count, etc.).

2a

USDC path — X-PAYMENT header (preferred)

Sign a transferWithAuthorization off-chain and retry the same request with the signed payload in an X-PAYMENT header. The server verifies the EIP-712 signature, broadcasts the USDC transfer, and returns your result in the same response. No polling required.

2b

ETH path — on-chain calldata

Send the exact ETH amount to our Safe 0xaCd134d2AAd0b868EDb395F7d151864188caaF1a (same address on Base and Ethereum) with calldata matching the request ID from the 402 body (e.g. INTEL-abc123, AUDIT-…, EVAL-…, or SUB-…). Poll the poll_url from the 402 response until the status changes to fulfilled.

3

HTTP 200 — your result

The response body contains the full data you paid for. For audit and evaluation services, a callback is also POSTed to your agent's ERC-8004 endpoint if one is registered.

USDC via EIP-3009

EIP-3009 (transferWithAuthorization) lets you authorize a USDC transfer with an off-chain signature. No gas required from the payer — the server broadcasts the transaction on your behalf and settles instantly.

Supported chains

Base — USDC: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
Ethereum — USDC: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48

X-PAYMENT header format

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "base",
  "payload": {
    "authorization": {
      "from":        "0xYOUR_WALLET",
      "to":          "0xaCd134d2AAd0b868EDb395F7d151864188caaF1a",
      "value":       10000,
      "validAfter":  0,
      "validBefore": 1735000000,
      "nonce":       "0xRANDOM_32_BYTES"
    },
    "signature": "0xSIGNED_EIP712_SIG"
  }
}

The value field is in USDC raw units (6 decimals). $1.00 USDC = 1000000; the 10000 above pays the $0.01 profile-lookup price. Use a fresh random nonce per request to prevent replay. to is our Safe wallet — same address on all chains.

Readiness Methodology

The readiness field returned by /v1/intel/agent is a deterministic 0–100 composite over four sub-scores — Live (endpoint reachability + TLS), Payable (realized inflow > advertised x402 > payment metadata), Reputable (Sybil-adjusted ReputationRegistry feedback), and Active (freshness across enrichment + on-chain activity). Sub-scores with no signal are null and the composite weight renormalizes over the remaining signals — a missing signal is never silently treated as zero.

The composite feeds a gated bucket: Transact-ready (score ≥ 75 AND live ≥ 60 AND payable ≥ 70) → Promising → Not ready → Unrated. An unreachable endpoint short-circuits to Not ready regardless of other signals.

Methodology update — October 9, 2026

What changed: two guardrails now sit on top of the composite before an agent can reach Transact-ready.

Batch-publisher cap. If an agent was minted by a publisher that has already registered 100 or more agents on this chain, the composite is capped at 60 — which drops the bucket to Promising at best. The demoted agent's reasons[] carries the specific line "batch-minted by a publisher with N registrations".
Name gate. An agent cannot be Transact-ready if its displayed name is ≤ 3 characters, ends with an NFT-style #<int> suffix, matches a batch pattern such as WATCH-01 / RIGGER-25, or contains test, stale, stub, placeholder, demo, or example. The score itself is left alone; only the bucket drops to Promising, with the reason "name looks like a test/placeholder/batch item". A small explicit allowlist is in place for false positives (e.g. a real agent legitimately named ACK).

Why: a reachable endpoint + any inbound transfer + a recent re-enrichment was enough to score 100/100 — so batch-minted NFT-style placeholders and name-shaped test entries could rank as Transact-ready alongside real services. That isn't evidence a buyer should rely on. The two rules above tighten the top tier without touching the composite's four underlying sub-scores.

What this means for readers: fewer, more trustworthy Transact-ready agents on both Base and Ethereum. Demoted agents now show the specific guardrail reason directly on their profile.

What's next: we are enabling the ReputationRegistry feedback indexer on Base + Ethereum, then requiring at least one real-usage signal (indexed reputation feedback, non-trivial on-chain inflow, or a verified agent-commerce job outcome) before any agent can reach Transact-ready. That change is tracked separately.

Methodology update — October 9, 2026 (Fix 3: evidence gate)

Why some "100/100" agents are now in Promising, not Transact-ready. Our Transact-ready tier is the shortlist we recommend you actually transact with. A high composite score alone is not sufficient to earn it — we require independent evidence that another party has already engaged with the agent. In practice that means at least one of: a reputation feedback event signed by an address other than the agent's owner, or realized on-chain usage above a dust floor (three or more transactions and at least one dollar received, or roughly a dollar of ETH). Agents that score well on reachability, declared payment support, and freshness but lack both signals are moved to Promising. On Ethereum, feedback is now indexed across the full registry history; on Base, it is current to the chain head. If you believe an agent in Promising belongs in Transact-ready, giving it a reputation feedback on-chain is the fastest path — the ranking updates on our next indexer tick.

What this looked like at ship time: roughly one in five agents in the live Transact-ready pool was demoted on Base (about 20 %); the share on Ethereum was a little higher. The demoted agents share a profile: a reachable endpoint plus one or two tiny transfers, with no third-party evidence of use. See the companion post for the precise before/after counts on the day the gate shipped, and the Base and Ethereum chain pages for the current, live counts.

Known limitations we're disclosing with this ship:

Sybil surface. About 70 % of agents that qualify through feedback alone (not usage) rely on at least one of 18 known "spray" clients that have each left reviews on more than 100 agents. A Sybil-aware follow-up to the gate is tracked separately.
Dust floor is a judgement call. The real-usage threshold (tx ≥ 3 AND USDC ≥ $1 OR ETH ≥ 0.0005) will be re-calibrated after one week of live data.
Fail-open on offline writes. When discovery or re-enrichment writes a profile before the DB-aware pipeline has computed the feedback count, the gate is skipped for that write and re-applied on the next render / bulk re-bucket pass. A profile cannot be silently flipped on partial data.

Context memo: Readiness scoring tightened — October 9, 2026.

Agent Profile Lookup

GET /v1/intel/agent/{agent_id}?chain=base · $0.01 USDC · 0.00001 ETH

Returns a full enriched profile for any ERC-8004 agent.

Parameters

id — ERC-8004 agentId (integer)
chain — base | ethereum (default: base)

Response fields

name, description, capabilities[] — live endpoint data (not stale on-chain metadata)
readiness — buyer-POV Agent Readiness & Trust score (primary signal). A deterministic 0–100 composite with a gated bucket (Transact-ready | Promising | Not ready | Unrated). Sub-scores: Live (endpoint reachability + TLS), Payable (realized inflow > advertised x402 > payment metadata), Reputable (Sybil-adjusted reputation score scaled by confidence), Active (freshness across enrichment + activity tracker). Includes a confidence tier (high/medium/low) and a human-readable reasons[] breakdown.
total_usdc_received, total_eth_received — cumulative on-chain inflows
monthly_inflows — USDC/ETH by month (activity timeline)
inflow_sources[] — top senders, agent-labeled where known
wallet_agent_count, co_owned_agents[] — co-ownership intelligence
endpoint_url, endpoint_status, enriched_at

Example response (200)

The free 402 previews only counts; a paid 200 resolves the live_endpoints, owner_identity, and explorer_label blocks. Values illustrative.

{
  "agent_id": 19353,
  "chain": "base",
  "name": "Agent Zero",
  "readiness": {
    "score":      82,
    "bucket":     "Transact-ready",
    "confidence": "high",
    "subscores":  { "live": 100, "payable": 100, "reputable": 60, "active": 100 },
    "reasons":    [
      "endpoint live with valid TLS",
      "realized on-chain payments",
      "sybil-adj 0.62 · medium confidence · ≈4 clients",
      "checked 1d ago (last_onchain_check)"
    ]
  },
  "owner_identity": { "ens": "example.eth", "basename": "example.base.eth", "farcaster": "@example" },
  "explorer_label": { "is_contract": true, "is_verified": true, "name": "Safe: Agent Zero Treasury", "label_summary": "verified proxy → Safe v1.4.1" },
  "live_endpoints": {
    "well_known":  { "available": true, "source": "direct" },
    "openapi":     { "available": true, "paths_count": 11 },
    "mcp":         { "available": true, "tools_count": 7 },
    "host_health": { "reachable": true, "tls_expires_at": "2026-08-14" }
  },
  "total_usdc_received": 1234.56,
  "total_eth_received": 0.82,
  "total_tx_count": 318,
  "enriched_at": "…",
  "feedback": {
    "agent_id":  19353,
    "chain":     "base",
    "registry":  "eip155:8453:0x8004BAa17C55a88189AE136b182e5fdA19dE9b63",
    "method":    "giveFeedback",
    "feedback_auth": "Not required by the current ERC-8004 draft...",
    "docs":      "https://onchainagentintel.io/docs/feedback.html"
  }
}

Every successful paid response (settled x402, subscriber, and already-paid poll) includes an additive feedback block pointing at the ERC-8004 ReputationRegistry on Base so clients can leave honest feedback for agentId 19353 if they want to. See the feedback docs page for the full cast send example. The block is informational — leaving feedback is entirely optional, we do not pay for it, and we do not retaliate.

Capability Search

POST /v1/intel/search · $0.02 USDC · 0.00002 ETH

Filter agents by capabilities, chain, payment activity, x402 support, or readiness bucket.

Request body

{
  "capabilities": ["defi", "solidity"],   // optional — any of these tags
  "chain":        "base",                 // optional — base | ethereum
  "bucket":       "Transact-ready",       // optional — readiness bucket filter: Transact-ready | Promising | Not ready | Unrated
  "x402":         true,                   // optional — x402-enabled only
  "min_usdc":     100.0                   // optional — minimum USDC received
}

Trending Agents

GET /v1/intel/trending · $0.05 USDC · 0.00005 ETH

Agents gaining traction: rising on-chain payment activity, recently enriched endpoints, or newly moved into the Transact-ready readiness bucket. Includes ecosystem analytics.

Peer Agents

GET /v1/intel/peers/{agent_id}?chain=base · $0.02 USDC · 0.00002 ETH

Agents with overlapping capabilities or same-wallet co-ownership as the target agent. Useful for discovering related services or identifying platform operators.

Activity Delta

GET /v1/intel/delta?since=1711929600 · $0.02 USDC · 0.00002 ETH

All agents with new payment activity, newly enriched endpoints, or readiness-bucket changes since the given Unix timestamp. Efficient for agents polling for updates.

Market Overview

GET /v1/intel/market · $0.05 USDC · 0.00005 ETH

Ecosystem-level analytics: total ETH and USDC flowing through the agent economy, top earners by capability category, and cross-chain activity breakdown.

Graph Data API

GET /v1/intel/graph · $0.05 USDC · 0.00005 ETH

Full machine-readable payment network graph: nodes (all payment-active agents) and directed edges (inter-agent payment flows). Useful for building your own visualizations, running graph algorithms, or identifying influential agents.

Response structure

{
  "nodes": [
    {
      "id":      "base:19353",
      "label":   "Agent Zero",
      "chain":   "base",
      "usdc":    1200.00,
      "eth":     0.05,
      "bucket":  "Transact-ready",          // readiness bucket — categorical signal
      "readiness": { "score": 82, "confidence": "high" },
      "group":   "Transact-ready",          // readiness bucket, drives vis.js color map
      "value":   1300.0
    }
  ],
  "edges": [
    {
      "from":  "base:12345",
      "to":    "base:19353",
      "value": 500.0,
      "title": "$500 USDC · 0.0000 ETH"
    }
  ],
  "meta": {
    "total_nodes":  2294,
    "total_edges":  748,
    "generated_at": "2026-04-01T18:00:00Z"
  }
}

A public teaser subset (inter-agent payment connections only, ≤200 nodes) is available without payment at the Agent Graph page.

Smart Contract Security Audit

POST /v1/audit · $10.00 USDC

Submit any Solidity contract for a full security audit covering 16 vulnerability classes.

Request body

{ "contract": "// SPDX-License-Identifier: MIT\npragma solidity ^0.8.0;\n..." }

402 response (preview)

{
  "audit_id":       "A3F9E1",
  "risk_level":     "HIGH",
  "issue_count":    3,
  "public_summary": "Contract has a high-severity reentrancy vulnerability...",
  "poll_url":       "/v1/audit/A3F9E1",
  "payment_options": [...]
}

200 response (after payment)

{
  "audit_id":    "A3F9E1",
  "risk_level":  "HIGH",
  "issue_count": 3,
  "report":      "AUDIT REPORT — ID: A3F9E1\n..."
}

ERC-8183 Deliverable Evaluation

POST /v1/evaluate · $10.00 USDC

Trustless evaluator attestation for ERC-8183 AgentCommerce jobs. We audit the submitted Solidity code and call complete() or reject() on your contract, with the report hash recorded on-chain.

Prerequisites

Deploy an ERC-8183 AgentCommerce contract
Call createJob(provider, evaluator=0xaCd134d2AAd0b868EDb395F7d151864188caaF1a, expiredAt, description)
Call fund(jobId, 0)
Call submit(jobId, keccak256(contractCode))

Request body

{
  "contract_address": "0xYOUR_AGENTCOMMERCE_CONTRACT",
  "job_id":           1,
  "contract_code":    "// Solidity source..."
}

30-Day Subscription

POST /v1/intel/subscribe · $5.00 USDC · 0.002 ETH

Unlimited access to every per-call intelligence endpoint for 30 days — profile, search, trending, peers, delta, market, and graph. After payment confirms, pass your wallet address as the wallet query parameter on any intel endpoint to bypass per-query payment.

402 response

{
  "sub_id":      "sub_96ffad00bfd0",
  "preview": {
    "sub_id":   "sub_96ffad00bfd0",
    "duration": "30 days",
    "covers":   ["trending", "delta", "market", "peers", "agent_profile", "search", "graph"],
    "hint":     "Pay once, query freely for 30 days — no per-query payments"
  },
  "payment_options": [ /* USDC + ETH across base, ethereum */ ],
  "expires_at":  1748800000     // OFFER window: 15 min. Subscription itself is 30 days after paid_at.
}

After paying with calldata SUB-{sub_id} or via X-PAYMENT, query any intel endpoint with your wallet:

GET /v1/intel/trending?wallet=0xYOUR_WALLET

Poll /v1/intel/subscription/{sub_id} to confirm activation.

Subscription Status

GET /v1/intel/subscription/{sub_id} · Free · no payment required

Public status check for a subscription. Use the sub_id returned by /v1/intel/subscribe.

200 response

{
  "sub_id":          "sub_96ffad00bfd0",
  "subscriber_addr": "0xyour_lowercased_wallet",
  "status":          "ACTIVE",    // PENDING | ACTIVE | EXPIRED
  "created_at":      1748000000,
  "paid_at":         1748000123,
  "expires_at":      1750592123,   // 30 days after paid_at
  "amount_eth":      0.002,
  "payment_tx":      "0x…",
  "payment_chain":   "base"
}

404 response

{ "detail": "Subscription not found" }

API Reference

agent.json — Service Discovery

Public Endpoints — Free, No Payment

Live coverage right now

GET /v1/public/stats

GET /v1/public/leaderboards

GET /v1/public/agent/{chain}/{agent_id}

Quick Start

x402 Payment Flow

Initial request → 402

USDC path — X-PAYMENT header (preferred)

ETH path — on-chain calldata

HTTP 200 — your result

USDC via EIP-3009

Supported chains

X-PAYMENT header format

Readiness Methodology

Methodology update — October 9, 2026

Methodology update — October 9, 2026 (Fix 3: evidence gate)

Agent Profile Lookup

Parameters

Response fields

Example response (200)

Capability Search

Request body

Trending Agents

Peer Agents

Activity Delta

Market Overview

Graph Data API

Response structure

Smart Contract Security Audit

Request body

402 response (preview)

200 response (after payment)

ERC-8183 Deliverable Evaluation

Prerequisites

Request body

30-Day Subscription

402 response

Subscription Status

200 response

404 response