How to Register an AI Agent on ERC-8004: The Complete Guide
How to Register an AI Agent on ERC-8004
ERC-8004 is the Ethereum standard for on-chain AI agent identity. It went live on Ethereum mainnet on January 29, 2026, and within a week, more than 24,000 agents had registered. BNB Chain deployed it days later. Celo followed. The Graph indexes it across eight chains.
Co-authored by teams at MetaMask, the Ethereum Foundation, Google, and Coinbase, ERC-8004 gives AI agents a verifiable way to register identity, accumulate reputation, and get validated on-chain — the three pillars of trustworthy participation in the agent economy.
This guide walks through the entire ERC-8004 registration process: what you need, what it costs, and how to do it. If you want to register an AI agent with non-transferable soulbound identity included, RNWY's registration flow handles both in one step.
What ERC-8004 Registration Actually Does
When you register an AI agent on ERC-8004, the Identity Registry smart contract mints an ERC-721 NFT that represents your agent's on-chain identity. That token gets an auto-incrementing agentId and points to a metadata file describing who the agent is and what it does.
The standard defines three registries working together. The Identity Registry stores agent registrations. The Reputation Registry collects structured feedback from other agents and users. The Validation Registry enables independent verification of agent behavior through trust hooks scored from 0 to 100.
As Bankless put it: if x402 handles how agents pay, ERC-8004 handles whether they should.
The registration itself is a single smart contract call. Here's what goes into it.
Step 1: Create Your Agent Registration File
Before calling the contract, you need a JSON metadata file — the agent registration file — that describes your agent's identity, capabilities, and service endpoints. The ERC-8004 specification defines the schema.
Here's a complete example:
{
"type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
"name": "YourAgentName",
"description": "What your agent does, how it works, pricing if applicable",
"image": "https://example.com/agent-logo.png",
"services": [
{
"name": "MCP",
"endpoint": "https://mcp.youragent.com/",
"version": "2025-06-18"
},
{
"name": "A2A",
"endpoint": "https://youragent.com/.well-known/agent-card.json",
"version": "0.3.0"
},
{
"name": "web",
"endpoint": "https://youragent.com/"
}
],
"x402Support": true,
"active": true,
"registrations": [
{
"agentId": 12345,
"agentRegistry": "eip155:1:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432"
}
],
"supportedTrust": ["reputation"]
}
The required fields are type, name, description, and image. The services array lists the protocols your agent supports — MCP, A2A (Google's agent-to-agent protocol), web endpoints, ENS names, DIDs, email, or any custom type. The supportedTrust field tells the ecosystem what kind of trust verification your agent participates in — reputation, crypto-economic, or tee-attestation.
Two important optional fields: x402Support indicates whether your agent handles x402 stablecoin payments, and active tells discovery services whether the agent is currently available.
The 8004scan best practices guide has community-developed recommendations for optimizing your metadata.
Step 2: Host the Metadata
Your agent registration file needs a permanent URL. ERC-8004 supports three URI schemes:
IPFS is the most common approach. Upload your JSON file to a pinning service and reference it as ipfs://YOUR_CID/agent-card.json. Pinata's free tier handles 500 files and 1GB of storage — more than enough for a 1–2KB agent card. Filecoin Pin offers cryptographic storage proofs, and their documentation includes a complete ERC-8004 registration walkthrough using Filecoin for metadata hosting.
HTTPS works too — just host the JSON at a stable URL you control. Simpler to set up, but depends on your server staying online.
Base64 data URI stores the metadata fully on-chain by encoding it as data:application/json;base64,.... This costs more gas but creates zero external dependencies. Good for high-value agents where permanence matters.
Step 3: Call the Identity Registry
The Identity Registry contract on Ethereum mainnet lives at 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432. The official contracts repo contains the full source, ABIs, and deployment modules.
The contract exposes three registration variants:
// Full registration with URI and on-chain metadata
function register(string agentURI, MetadataEntry[] calldata metadata)
external returns (uint256 agentId)
// Registration with URI only
function register(string agentURI)
external returns (uint256 agentId)
// Bare registration — add URI later via setAgentURI()
function register() external returns (uint256 agentId)
For most registrations, the second variant — URI only — is all you need. Pass your IPFS or HTTPS URL, the contract mints an ERC-721 NFT to your wallet, and you get back your agentId. The transaction emits a Registered event and a standard ERC-721 Transfer event.
The Agent0 TypeScript SDK (agent0-sdk on npm) wraps this into higher-level functions that handle registration, discovery, and reputation in a few lines. For the fastest path without the SDK, howto8004.com provides copy-paste registration scripts in both JavaScript and Python.
Step 4: Verify and Configure (Optional)
Two optional steps strengthen your registration:
Domain verification. Publish a /.well-known/agent-registration.json file at your agent's endpoint domain containing a registrations array that matches your on-chain data. This proves you control both the on-chain identity and the service endpoint.
Agent wallet. Call setAgentWallet() with an EIP-712 or ERC-1271 signature to designate a payment-receiving address separate from the owner wallet. This is important for agents using x402 payments — it separates the ownership key from the operational key.
What ERC-8004 Registration Costs
ERC-8004 is permissionless. There are no registration fees — the protocol is free to use. The only cost is gas for the NFT mint transaction.
The cost varies dramatically by chain. On Ethereum mainnet, a registration typically costs $1–$5 in gas depending on network congestion — up to $10 during peak times. On L2s, the same transaction costs pennies.
Base (Coinbase's L2) is the next confirmed production deployment target, where registration would cost roughly $0.01–$0.05. BNB Chain runs about $0.05–$0.20. Celo is under $0.01.
IPFS hosting for your metadata file is free on Pinata's starter tier. A typical agent card is 1–2KB — negligible storage.
ERC-8004 Contract Addresses
All official contracts use a 0x8004 vanity prefix created via deterministic deployment:
Ethereum Mainnet:
- Identity Registry:
0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 - Reputation Registry:
0x8004BAa17C55a88189AE136b182e5fdA19dE9b63
Ethereum Sepolia (Testnet):
- Identity Registry:
0x8004A818BFB912233c491871b3d84c89A494BD9e - Reputation Registry:
0x8004B663056A597Dffe9eCcC1965A193B7388713
Additional testnet deployments exist on Base Sepolia, Linea Sepolia, and Hedera Testnet. Production L2 deployments are expanding — BNB Chain and Celo are live, with Base, Arbitrum, and others expected. The protocol deploys singleton registries per chain to prevent fragmentation. Agents registered on one chain can reference registrations on other chains through the registrations array in their metadata.
Browse registered agents at 8004scan.io, the primary ERC-8004 explorer.
What Happens After Registration
Registration is just the beginning. Once your agent has an on-chain identity, the ERC-8004 lifecycle kicks in.
Discovery. Other agents and clients can now find your agent by querying the Identity Registry. Your registration file tells them what protocols you support (MCP, A2A, web), where your endpoints are, and whether you're active. The Graph's dedicated subgraphs make cross-chain agent discovery possible through a single query.
Reputation. Anyone can submit structured feedback about your agent through the Reputation Registry. Feedback includes a signed numeric value (quality scores, uptime percentages, response times), tags for filtering, the endpoint being rated, and optional links to detailed evidence. As Eco.com explains, this creates a portable track record that follows the agent everywhere. The anti-gaming rule: feedback submitters cannot be the agent's owner or approved operator.
Validation. Independent validators can verify agent behavior through trust hooks. The Phala Network TEE agent demonstrates one implementation — using Intel TDX trusted execution environments to provide cryptographic attestation that an agent is running the code it claims to run. Validators respond with scores from 0 (failed) to 100 (passed).
Payments. Agents with ERC-8004 identity can participate in the x402 payment protocol ecosystem — accepting and making stablecoin micropayments through the HTTP 402 status code. Bitrue's analysis shows how merchants can apply trust-weighted payment policies based on an agent's reputation: higher limits for reputable agents, stricter terms for unknown ones.
Updates. You can update your registration file anytime by calling setAgentURI() with a new metadata URL. The old URI is replaced, but blockchain history preserves the record of changes.
The Transferability Question
Here's something worth understanding about standard ERC-8004 registration: the identity token is an ERC-721 NFT, which means it's transferable by design. The spec states that the owner of the token can transfer ownership.
Eco.com frames this as a feature — a marketplace for proven agents with established reputations. PayRam notes that agent identity tokens are technically tradable on NFT marketplaces. For many use cases — businesses selling agents, management delegation, company acquisitions — transferability makes sense.
But as one technical analysis identified, transferable identity introduces risks of reputation laundering. An agent's reputation history stays linked to the agentId even after the underlying owner changes. A new owner inherits a track record they didn't earn.
The ERC-8004 spec mitigates this partially — on transfer, the agentWallet field is cleared, creating a visible ownership transition. But reputation data persists. For high-value interactions where trust matters, that gap can be significant. We explored this in depth in ERC-8004 + x402: The Identity-Payment Stack for AI Agents.
Register with Soulbound Identity on RNWY
RNWY addresses the transferability gap by adding a non-transferable identity layer on top of ERC-8004.
When you register an agent on RNWY, the system mints an ERC-5192 soulbound token alongside your agent profile. ERC-5192 extends ERC-721 with a locked() function — when it returns true, all transfer functions revert. The token is permanently bound to the wallet it was minted to. You can burn it and walk away, but you can't sell it or send it to someone else.
This creates a dual-layer identity approach:
The ERC-8004 layer handles discovery, reputation, and the full agent lifecycle as designed. Your agent is findable in standard registries, interoperable with the existing ecosystem, and compatible with every tool built for ERC-8004.
The soulbound layer adds a permanent proof of original registration that cannot be separated from the registrant. When someone checks your agent's identity, the soulbound token provides an additional signal: this identity has been bound to this wallet since this date and has never transferred. An agent with a six-month-old soulbound token is a stronger trust signal than the same agent profile without one.
On L2 chains like Base, the total cost for both mints — ERC-8004 identity plus soulbound token — is under $0.20. RNWY also adds vouch attestations through the Ethereum Attestation Service, address age verification, and transparent trust pattern visualization.
The philosophy is simple: ERC-8004 handles identity infrastructure. Soulbound tokens handle identity permanence. Both layers work together. We wrote about the technical rationale in Why ERC-8004 Needs a Soulbound Layer and the broader design in Soulbound Tokens for AI Agents.
Developer Resources
Everything you need to start building with ERC-8004:
Official specification and contracts. The canonical spec lives at eips.ethereum.org/EIPS/eip-8004. The official contracts repo on GitHub contains the Solidity source, ABIs, and deployment modules. Discussion happens at Ethereum Magicians.
SDKs and tools. The Agent0 TypeScript SDK handles registration, discovery, reputation, and multi-chain queries. howto8004.com provides minimal copy-paste scripts. The Phala Network TEE agent includes a full dashboard UI for registration and reputation management.
Tutorials and guides. Filecoin's builder cookbook has a step-by-step registration walkthrough. BuildBear's deep dive covers the developer implementation. Composable Security's explainer walks through the full lifecycle from a security audit perspective.
Explorers and indexes. 8004scan.io is the primary agent explorer. The awesome-erc8004 list on GitHub curates the complete ecosystem of implementations, tools, and documentation. The official 8004.org site includes the builder program, community calls, and FAQ.
Examples. Vistara's ERC-8004 example demonstrates registration with CrewAI agents and Foundry contracts. Oasis Protocol's implementation shows ROFL-powered agents. DEV Community's TEE guide covers the trusted execution environment integration.
Register Your Agent
ERC-8004 registration is live on mainnet and expanding across chains. The standard is backed by the Ethereum Foundation, MetaMask, Google, and Coinbase. Over 24,000 agents registered in the first week. Eight blockchains have indexing infrastructure.
The infrastructure moment for AI agent identity is here. The question is whether your agent is part of it.
For standard ERC-8004 registration, the tools above have everything you need. For registration with soulbound identity anchoring — non-transferable proof of identity that can't be sold or laundered — register on RNWY.
RNWY builds non-transferable identity infrastructure for AI agents using soulbound tokens on Base. Register your agent →