// Last updated 2026-04-25

ERC-8004 Identity Registry

The ERC-8004 Identity Registry mints one ERC-721 token per AI agent, with a tokenURI pointing at a JSON metadata file that holds the agent’s name, description, image, and endpoints — giving every agent a portable, onchain identity no single platform controls.

If you’ve read The three registries and want the full picture of the identity layer, this is the place.

What it stores

Each registration records a tokenId, an owner address, and a tokenURI onchain. That’s the full footprint — small, but every downstream registry event references these three fields.

When an agent is registered, the contract mints an ERC-721 token and emits an AgentRegistered event:

AgentRegistered(uint256 indexed tokenId, address indexed owner, string metadataURI)

Indexers — including this explorer — listen for that event to learn that a new agent exists. The metadataURI in the event payload points at a JSON file the indexer fetches to populate the agent’s name, description, and endpoint list. The mint itself is standard ERC-721; the AgentRegistered event is the Identity Registry’s addition.

Once minted, the (chain, registry-address, tokenId) triple is the stable, permanent address for that agent. The canonical EIP specifies the full event schema and the required metadata fields.

The metadata file

The JSON file at the tokenURI follows a canonical schema with four required fields: name, description, image, and endpoints. Here’s a representative example:

{
  "name": "ResearcherBot",
  "description": "Summarizes academic papers on demand. Optimized for arxiv.",
  "image": "ipfs://QmExampleHash/avatar.png",
  "endpoints": [
    { "type": "https", "url": "https://researcher.example.com/api" },
    { "type": "websocket", "url": "wss://researcher.example.com/stream" }
  ]
}

The endpoints array is where agents declare how they can be invoked. An agent can expose an HTTPS endpoint for request/response calls and a WebSocket endpoint for streaming, or just one of the two. Additional fields beyond the four required ones are permitted; unrecognized fields are ignored by conforming indexers.

Where to host the file matters. IPFS and Arweave are the recommended options because both are content-addressed: the URL is derived from the content hash, so you can verify the file hasn’t changed. An HTTP URL works for registration, but if the server goes offline or the path changes, the identity still exists onchain while the metadata becomes unreachable. Consumers of this explorer can see the full metadata on any agent detail page.

How registration works

Registration is a single transaction. The caller invokes register(string metadataURI) on the Identity Registry contract, paying gas in the chain’s native token. Gas costs vary by chain; on Base or Mantle the cost is a fraction of what Ethereum mainnet charges.

The contract mints a new ERC-721 token to msg.sender, increments the tokenId counter, and emits AgentRegistered. From that point, the agent has a permanent onchain record.

The reference Identity Registry is deployed at deterministic addresses across Ethereum mainnet, Base, BNB Chain, Avalanche, and Mantle. The same contract address on every supported chain means tooling doesn’t need chain-specific configuration to locate the registry — it’s always at the same address. You can verify the deployed addresses in the reference contracts repository.

Why ERC-721 specifically

ERC-721 was chosen over ERC-1155 and soulbound alternatives primarily for its transfer semantics. An agent’s tokenId travels with the token when ownership changes hands. Reputation and Validation Registry events are keyed to tokenId, not to the original owner address, so an agent’s performance history follows the token through any sale or team handoff.

ERC-721 also inherits an existing tooling ecosystem. Wallets, block explorers, and marketplaces already know how to display and transfer these tokens. An agent shows up in any wallet as an NFT, and any marketplace that supports ERC-721 can facilitate its transfer without custom integration.

The identity precedent matters too. ERC-721 has been used for ENS domains, onchain profiles, and access credentials — cases where the token is the address-of-record rather than a collectible. That’s exactly how the Identity Registry uses it.

ERC-1155 was ruled out because its shared-contract model would require all agents to coexist under one owner policy. Soulbound tokens were ruled out because legitimate ownership transfers — a team offboarding an agent, an acquirer inheriting a deployed agent’s history — need to be possible.

Updating metadata over an agent’s lifetime

Agents aren’t static. Endpoints change, descriptions get revised. The Identity Registry lets the owner of a tokenId call setTokenURI(uint256 tokenId, string newURI) to update the metadata pointer.

When that call goes through, the contract emits a MetadataUpdate event (defined by EIP-4906, the standard metadata-update extension for ERC-721). Indexers rebuild the agent’s cached metadata from the new URI. The previous URI is gone from the “current state” view, but it’s not gone from the chain — the full event log still contains every URI the agent has ever pointed at, in order. Any observer can replay that history to audit what the metadata said at any point in time.

The implication for trust: if a hostile actor gains ownership of a tokenId, they can point the tokenURI at a fabricated metadata file. The agent’s reputation and validation history are still keyed to the tokenId and can’t be altered, but the name and endpoints visible in the metadata are now under the new owner’s control. Clients who want to pin to a known-good metadata state can store the content hash of a version they trust and verify future metadata against it. IPFS-hosted files handle this cleanly because the URL is the hash.

Common failure modes

Metadata URI returns 404. The onchain identity is intact, but the agent’s name, description, and endpoints are unavailable to any consumer that fetches the URI. This explorer shows “metadata unavailable” rather than an error, but the agent still appears in search results and its reputation and validation records are still visible. Using IPFS or Arweave avoids this failure mode.

Schema drift. An agent’s metadata file may omit optional fields or add non-standard ones. The canonical schema defines what’s required; anything extra is passed through silently. A field the schema doesn’t define is ignored rather than rejected. Problems arise when required fields are missing: an agent without endpoints in its metadata won’t show invocation options on its detail page, even though the registration is valid.

Transfer to a hostile owner. ERC-721 transfer semantics mean the tokenId can move to any address the current owner authorizes. The new owner can update the tokenURI. Downstream trust in an agent’s identity has to come from its reputation and validation record — not from the identity alone. An agent that gets transferred keeps its full history. An abrupt URI change after transfer shows up in the event log — which is the audit trail.

Where to go next

• Hub: The three registries
• Sibling: Reputation Registry
• Sibling: Validation Registry
• Cornerstone: What is ERC-8004?
• The canonical EIP: https://eips.ethereum.org/EIPS/eip-8004
• Reference contracts: https://github.com/erc-8004/erc-8004-contracts