The card behind the token

An ERC-8004 identity is an ERC-721 token with an agentURI. That URI resolves to JSON called the agent registration file in the ERC-8004 specification. People often call it an agent card.

The token proves who controls the pointer. The card tells software what it found and where the agent can be reached. An indexer fetches it for search. A wallet uses it for display. A routing model reads it before choosing a service. A marketplace can screen inactive listings.

Here’s a Base mainnet example: 

{
  "type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
  "name": "QuoteScout",
  "description": "Returns current product quotes through an x402-paid HTTP endpoint.",
  "image": "https://example.com/agents/quote-scout.png",
  "services": [
    {
      "name": "web",
      "endpoint": "https://example.com/agents/quote-scout"
    },
    {
      "name": "MCP",
      "endpoint": "https://example.com/mcp",
      "version": "2025-06-18"
    }
  ],
  "x402Support": true,
  "active": true,
  "registrations": [
    {
      "agentId": 127,
      "agentRegistry": "eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432"
    }
  ],
  "supportedTrust": ["reputation", "crypto-economic"]
}

type, name, description, and image

type identifies the schema version. Parsers can reject an unknown shape instead of guessing. Copy the registration-v1 URL exactly.

name is the short display label shown by explorers and wallets. Keep it stable. Changing it won’t change the on-chain agentId, but users may think they’re looking at a different agent.

description is routing material. State the output and expected payment. “Helpful research agent” gives a model little to match against a task. “Returns a cited Base token-risk report for $0.02 USDC” gives it usable criteria.

image is an absolute URI for the avatar or logo. NFT viewers may fetch it without cookies, browser headers, or a logged-in session. Use a public HTTPS or IPFS URL with the right content type. Signed CDN URLs expire. Hotlink protection breaks previews.

services is the routing table

Each object in services has name and endpoint. The name tells a client how to interpret the destination. The endpoint tells it where to connect.

Names aren’t limited to one protocol. The spec shows web, A2A, MCP, OASF, ENS, DID, and email. A router can select MCP for a tool call or open an A2A card for capability discovery.

version is recommended for versioned services. It lets clients skip an incompatible endpoint before attempting a session. For OASF entries, optional skills and domains add machine-readable classifications.

Don’t put a landing page where an MCP transport is promised. The URL may return 200, yet the route is still broken.

x402Support and active

x402Support: true is a discovery hint that the agent accepts x402 payments. It isn’t a quote. A caller still learns the asset, network, amount, and payment recipient from the HTTP 402 response.

active lets catalogs suppress an agent that has been paused without deleting its identity. Set it to false before planned downtime. And don’t leave it true after every service URL has gone dark.

registrations and supportedTrust

registrations binds the JSON back to on-chain identities. Every entry needs both fields. agentId is the ERC-721 token ID. agentRegistry uses namespace:chainId:contract, so Base mainnet begins with eip155:8453:. One card can list registrations on more than one chain.

Verifiers compare those values with the token they started from. The same pair can also appear at https://{service-domain}/.well-known/agent-registration.json to prove control of a service domain. If they don’t match, the endpoint shouldn’t inherit the agent’s identity.

supportedTrust declares which trust methods consumers can inspect. It’s optional. An absent or empty array means the card is for discovery only. A declared method isn’t proof by itself, so routing software still checks the related registry records or attestations.

Stable URLs beat clever URLs

An HTTPS agentURI can keep one address while its JSON changes. An IPFS URI pins one version, so a changed card needs a new CID and an on-chain setAgentURI call. Pick the update model you can maintain.

Test the card from a clean client. Fetch the agentURI, parse the JSON, request every advertised service, and retrieve the image without authentication. Then repeat from outside your own network. A perfect on-chain registration can’t rescue a card hidden behind a dead hostname.