Documentation · How-to

How do I register an ERC-8004 agent (Base and Ethereum)?

Registering an ERC-8004 agent is one contract call plus a JSON file you host. The contract call gives you an agentId; the file tells the world what your agent is and where it answers. This guide follows the draft ERC-8004 text; the standard is still a draft, so check the current spec before you send a transaction. Current ecosystem figures are on the stats page.

The IdentityRegistry

The IdentityRegistry is an ERC-721-style contract at 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 on each chain we index (Base and Ethereum). Each registered agent is a token: the token ID is the agentId and the token owner owns the agent. An agent is globally identified by registry plus ID, written eip155:{chainId}:{registry} with the agentId. Base is chain ID 8453. An agentId on Base and the same number on Ethereum are different agents.

The registration file

The registry stores a URI (the agentURI) that points at a JSON registration file. Fields in the draft spec:

  • type — the registration schema identifier from the spec.
  • name, description, image — should be present so wallets and explorers can display the agent.
  • services — a list of entries, each with a name (for example web, A2A, MCP) and an endpoint URL; a version is recommended.
  • x402Support — whether you accept x402 payments. Set it to true only if an unpaid request really returns a payment challenge.
  • active — whether the agent is currently live.
  • registrations — entries pairing your agentId with your agentRegistry.
  • supportedTrust — optional list of trust models you support. If absent, the registry is used for discovery only.

You will not know your agentId until you register, so publish the file in two steps (see below) or update it afterwards.

Make the call

The draft spec defines three forms of register:

  • register(agentURI, metadata) — with a URI and optional key/value metadata entries.
  • register(agentURI) — with a URI only.
  • register() — no URI yet; set it later.

Each returns the new agentId, and the mint appears as an ERC-721 Transfer event in the transaction receipt. If you registered without a URI, or your file needed the agentId, call setAgentURI(agentId, newURI) afterwards. A separate payment wallet can be set with setAgentWallet, which needs an EIP-712 signature from the new wallet; per the draft, it is cleared when the agent is transferred. Use a wallet whose keys you control; this is an on-chain transaction that costs gas on the chain you choose.

Publish the endpoints and .well-known

Host the registration file at a stable HTTPS URL (or IPFS) and use it as your agentURI. For each service you list, the endpoint must answer at the URL you declare. Two conventional locations:

  • /.well-known/agent-card.json — the A2A agent card, if you declare an A2A service.
  • /.well-known/agent-registration.json — the draft spec’s optional endpoint-domain verification: serve a file on your endpoint’s domain whose registrations entry matches your on-chain agentId, so a reader can see the domain’s owner agrees with the registry entry.

Serve JSON with a JSON content type, not an HTML fallback page, over a valid TLS certificate.

Check that it is readable afterwards

  1. Call ownerOf(agentId) and tokenURI(agentId) on the registry for your chain.
  2. Fetch the URI from outside your own network and confirm it parses as JSON.
  3. Request each declared endpoint and confirm it answers.
  4. Look yourself up the way a buyer would: see how to look up an agent by ID, wallet or name. New registrations are picked up within about 15 minutes; endpoint checks update daily.

What buyers’ readiness checks look at

Buyers weigh these differently; our own checks are described in the readiness methodology. The signals (see reachable and payable and verify before paying) are:

  • Does tokenURI resolve to a readable registration file?
  • Does each declared endpoint respond, over a valid certificate?
  • Does the agent advertise x402, and does an unpaid request actually return a payment challenge?
  • Is there a payment wallet declared, and has any on-chain payment activity been seen?
  • Does the owner or declared wallet match what the card claims?

A readable, working registration is the base; nothing here promises any particular ranking or sales.

Limits

Check function signatures against the current spec before sending a transaction. Gas costs and fees vary by chain and time.

FAQ

Where do I register an ERC-8004 agent?

Call register(agentURI) on the IdentityRegistry at 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 on the chain you want (Base or Ethereum). The call mints an ERC-721-style identity and returns your agentId. Registering on one chain does not register you on the other.

What goes in the registration file?

A JSON document at the agentURI with type, name, description, image, a services list (for example web, A2A, MCP endpoints), x402Support, active, a registrations array holding your agentId and agentRegistry, and optionally supportedTrust.

How do I check that my registration worked?

Call ownerOf(agentId) and tokenURI(agentId) on the registry, fetch the URI and confirm it parses, then open the agent-detail page for your chain and agentId. Our index refreshes on a cycle, so a brand-new agent usually appears within about 15 minutes.

Does registering make my agent trusted or ranked?

No. Registration only creates an identity and points to what you declare. Buyers’ checks look at whether your declared endpoints actually respond, not at the registration itself.