Documentation · How-to

How do I look up an ERC-8004 agent by ID, wallet or name?

Every ERC-8004 agent is a numeric agentId registered on one chain, so the reliable lookup key is the pair chain + agentId. Start there, read the on-chain record, then use the free agent-detail page, public API or MCP tool for a readable summary. Wallet and name lookups work too, but they only produce candidates that you confirm by chain and agentId. Current ecosystem figures are on the stats page.

By agentId

An agentId is only unique within a chain, so always note which chain it came from. Our indexed chains are Base and Ethereum. With both values in hand:

  1. Open https://onchainagentintel.io/agent/{chain}/{agentId} (chain is base or ethereum) for a readable page, or
  2. call the JSON endpoint in the free section, or
  3. read the registry directly, as below, if you do not want to rely on any third-party index.

Read the registry on-chain

The IdentityRegistry is at 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 on each supported chain (see ERC-8004 explained). In a block explorer’s “Read contract” tab, or with any RPC client, call:

  • ownerOf(agentId) — the address that owns the identity.
  • tokenURI(agentId) — where the agent’s registration document lives (an HTTPS, IPFS or data URI).

Fetch that URI to see the declared name, description and service endpoints. The chain is the source of truth for ownership and the URI; everything inside the document is whatever the owner chose to publish.

By owner or wallet

The registry maps agentId to owner, not the other way round, so a wallet lookup is a search rather than a single call. Two routes: use your block explorer’s token-holder view for the registry contract, or filter the registry’s Transfer events for that address and then confirm each ID with ownerOf, since ownership can have moved.

Two different wallets can be involved: the owner of the identity, and any payment wallet the agent declares in its registration for receiving funds. They are not required to match, so check which one you were given.

By name

Names are free text in the registration document: not unique, not verified, and easy to imitate. The free public leaderboards and the leaderboard page list public names for the agents they cover, and agent-detail pages show a name when one is published. There is no free general name search; treat any name match as a candidate and confirm the chain and agentId before relying on it. A capability-based search exists as a paid endpoint — see agent.json.

Free pages, API and MCP

GET https://api.onchainagentintel.io/v1/public/agent/{chain}/{agent_id}

The public agent-detail endpoint returns a neutral summary for one indexed agent without payment or authentication. The same data is behind the human page at /agent/{chain}/{agentId}. The full list of free and paid routes is in agent.json and the OpenAPI document.

The free MCP server at https://api.onchainagentintel.io/mcp exposes the same summary as the get_agent_summary(chain, agent_id) tool, plus get_leaderboards() for browsing. See MCP explained for how to connect a client.

What the fields mean

  • Chain and agentId — the identity key. Same number on another chain is a different agent.
  • Owner — the on-chain address holding the identity right now.
  • tokenURI / registration — the owner-published document; self-declared.
  • Reachability, TLS validity — whether our last probe got an HTTP response from a declared host over a valid certificate.
  • x402 support — whether the registration advertises it; see reachable and payable for testing it.
  • Owner wallet received payments — whether our indexer has seen an incoming transfer to the wallet that owns the agent. That wallet can own many agents.

Each value reflects our most recent probe, not the present moment; see last_indexed_at in the response.

What a lookup doesn’t prove

A lookup shows that an identity exists and what it declares. It does not show that the endpoints work now, that the owner is who the card says, that the name is not an imitation, or that the agent’s work is good. Registrations are self-declared and anyone can post reputation feedback, so read those signals with care; our reputation note explains why. Before sending money, continue with verifying an agent before paying.

FAQ

How do I look up an ERC-8004 agent by agentId?

Pick the chain (base or ethereum) and open onchainagentintel.io/agent/{chain}/{agentId}, or call GET api.onchainagentintel.io/v1/public/agent/{chain}/{agent_id}. For the authoritative record, call ownerOf(agentId) and tokenURI(agentId) on the IdentityRegistry on that chain.

Can I find an ERC-8004 agent by wallet address?

Partly. The IdentityRegistry is an ERC-721-style registry, so ownerOf(agentId) tells you the owner of a known ID. Going from a wallet to its agents means reading the registry’s Transfer events or your block explorer’s token-holder view for that wallet. An agent may also declare a separate payment wallet in its registration, which can differ from the owner.

Can I search for an ERC-8004 agent by name?

Names are self-declared in each agent’s registration document and are not unique. The free leaderboards list public names for the agents they rank, and the agent-detail page shows the name when one is published. There is no free general name search; use the name only to find candidates, then confirm by chain and agentId.

Does finding an agent mean it is real or trustworthy?

No. A lookup shows that an identity exists and what it declares. It does not show that the declared endpoints work, that the owner is who the card claims, or that the agent’s work is good.

Is the lookup free?

Yes for the on-chain reads (you pay only for RPC access you already have), the agent-detail page, the public agent-detail endpoint and the free MCP tools. Deeper paid intel endpoints exist and are listed in agent.json.