Documentation

API Reference

All endpoints are x402-gated. No accounts or API keys required. Base URL: https://onchainagentintel.io

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://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://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"])   # 1000000 (1.00 USDC, 6 decimals)
print(preferred["token_address"])  # 0x833589f... (Base USDC)
print(preferred["payment_method"]) # EIP-3009

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
BASE_URL      = "https://onchainagentintel.io"
TARGET_AGENT  = 19353   # any ERC-8004 agentId
CHAIN         = "base"

# 1. Make the request — expect a 402
r = httpx.get(f"{BASE_URL}/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"{BASE_URL}/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 0xe9D45C3F847a7d2aE4efD7D6Da491f8a7E19b9F0 with calldata matching the request ID from the 402 body (e.g. INTEL-abc123). 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":          "0xe9D45C3F847a7d2aE4efD7D6Da491f8a7E19b9F0",
      "value":       1000000,
      "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. Use a fresh random nonce per request to prevent replay.

Agent Profile Lookup

GET /v1/intel/agent/{id}?chain=base · $1.00 USDC

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)
  • verdict — AI evaluation: reach out | monitor | no action
  • 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

Peer Agents

GET /v1/intel/peers/{id}?chain=base · $1.00 USDC

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 · $2.00 USDC

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

Market Overview

GET /v1/intel/market · $3.00 USDC

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 · $3.00 USDC

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,
      "group":   "reach out",
      "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

  1. Deploy an ERC-8183 AgentCommerce contract
  2. Call createJob(provider, evaluator=0xe9D45C3F847a7d2aE4efD7D6Da491f8a7E19b9F0, expiredAt, description)
  3. Call fund(jobId, 0)
  4. 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 · $10.00 USDC

Unlimited access to all six intelligence endpoints for 30 days. Pass your wallet address as the wallet query parameter on any intel endpoint to bypass per-query payment while subscribed. 

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