API Documentation — On-Chain Agent Intel

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"])   # 100000 (0.10 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

93,495

Agents Indexed

26,079

MCP Tools

25,892

OpenAPI Methods

1,169

Named Owners

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, "bnb": 22751, "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": "bnb", "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/BNB path — on-chain calldata

Send the exact amount to our Safe 0xaCd134d2AAd0b868EDb395F7d151864188caaF1a (same address on Base, Ethereum, and BNB Chain) 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":       100000,
      "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 100000 above pays the $0.10 profile-lookup price. Use a fresh random nonce per request to prevent replay. to is our Safe wallet — same address on all chains.

Agent Profile Lookup

GET /v1/intel/agent/{agent_id}?chain=base · $0.10 USDC · 0.0001 ETH · 0.0005 BNB

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

Parameters

id — ERC-8004 agentId (integer)
chain — base | ethereum | bnb (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": "…"
}

Capability Search

POST /v1/intel/search · $0.20 USDC · 0.0002 ETH · 0.0010 BNB

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 | bnb
  "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.30 USDC · 0.0003 ETH · 0.0015 BNB

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.10 USDC · 0.0001 ETH · 0.0005 BNB

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.20 USDC · 0.0002 ETH · 0.0010 BNB

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.30 USDC · 0.0003 ETH · 0.0015 BNB

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.30 USDC · 0.0003 ETH · 0.0015 BNB

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 · 0.010 BNB

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/BNB across base, ethereum, bnb */ ],
  "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/BNB path — on-chain calldata

HTTP 200 — your result

USDC via EIP-3009

Supported chains

X-PAYMENT header format

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