ERC-8004 and Headless Domains: Linking Agent Identities

Your agent is registered under ERC-8004. Someone finds it in a directory under a .agent name. How do they check that both records belong to the same service?

ERC-8004 and Headless Domains can work together by connecting a maintained public name to an agent's registry entry, registration file and service endpoints. The operator must establish those connections, and the caller must check them. Registering a name does not automatically create or verify an ERC-8004 registration.

A customer can start with the name. A registry client can start with the ID. You want either route to lead to the service you actually operate.

ERC-8004 already includes identity and discovery

ERC-8004, titled Trustless Agents, remains a Draft ERC. Its design includes an identity registry, reputation feedback and a validation registry for checks on an agent's work. Identity and discovery are part of the protocol itself.

The identity registry uses ERC-721. Each agent has an agentId, while agentRegistry identifies the chain and registry contract. Keep the pair together: the same numeric ID can appear in different registries.

The registry's agentURI points to a registration file. That file can carry a readable name and advertise services such as MCP endpoints or A2A Agent Cards. An ERC-8004 agent therefore does not need a separate domain product to become discoverable.

Draft status also does not mean there is nothing to use. The project's contracts repository lists identity and reputation deployments on Ethereum mainnet, Base and other networks. It separately warns that the validation portion remains under active revision. Check the specific network, deployment and contract version your application supports.

What a Headless Domains name adds

A name can give customers and other agents a consistent reference across a registry, a directory and the service itself. For example, an agent might use research.agent publicly while its ERC-8004 entry supplies the exact registry identifier. This name is illustrative, with no claim about ownership or availability.

Headless Domains documents hosted manifests and Markdown records, with TXT pointers to their locations. Its public API contract defines GET /api/v1/resolve/{domain_name} as read-only identity and action discovery. A caller can inspect the name and follow its published resources through HTTPS.

That does not make every headless name an ordinary browser address. Direct resolution of the Handshake name needs compatible infrastructure. Use the HTTPS locations returned by the service rather than constructing a URL from the name and assuming it works.

Add the name when it helps people find and recognize your agent. If your existing registry entry and website already do that job well, ERC-8004 does not require you to buy another name. Our Agent Identity Stack covers the broader architecture.

Connect the records using their own formats

You can build this connection using records you control. Our public documentation does not currently specify a native ERC-8004 binding or automatic registry verification, so the steps below describe an operator-managed design.

Suppose the research agent already has a working service. You want a customer arriving through its Headless Domains name to find the correct ERC-8004 registration. Work through four steps:

1. The exact registry reference. Record the chain, identity-registry contract and agentId from the deployment you actually use. Read the registration file through that registry's agentURI.
2. The ERC-8004 registration file. Publish a document that follows the ERC-8004 format, including its registrations entries and actual service locations. Its readable name can match your agent's public name, but matching text alone does not prove control.
3. The Headless Domains record. Publish the corresponding service information and a route to the ERC-8004 registration. If you need custom structured references, the profile-management guide documents self-hosting a manifest and updating its TXT pointer. Keep the Headless manifest and ERC-8004 registration file as separate documents unless one document has been checked against both formats.
4. The caller's verification logic. Have the consuming application check the registry reference and supporting control evidence before treating the records as belonging to the same agent. If it does not understand your custom reference, it cannot use it automatically.

An extra erc8004 object in a JSON file does not establish interoperability by itself. For a custom manifest extension, document the fields and implement a reader. A public profile link can still help a person inspect the registration. It simply leaves the verification work to the reader.

Our agent identity graph guide explains the wider relationship model. Here, the relationship to establish is specific: this public name refers to this ERC-8004 registration.

Check the endpoint's side of the claim

A registration file can advertise an endpoint the publisher does not control. ERC-8004 addresses that with an optional endpoint-domain verification mechanism: publish /.well-known/agent-registration.json on the HTTPS endpoint's domain, containing a matching registry reference.

For example, if the research API runs at https://api.example.com/research, its operator could publish the file at https://api.example.com/.well-known/agent-registration.json. This illustrative template needs the actual chain, registry address and numeric agent ID before publication:

{
  "registrations": [
    {
      "agentRegistry": "eip155:CHAIN_ID:IDENTITY_REGISTRY_ADDRESS",
      "agentId": 123
    }
  ]
}

The endpoint operator must control publication at that location. The draft does not require this extra file when the endpoint domain already serves the primary registration file referenced by agentURI. On a shared host, uploading a document somewhere under your account is not equivalent to controlling the domain's well-known file.

This check supports the association between the HTTPS endpoint domain and the registry entry. It does not, by itself, establish control of a separate Headless Domains name or prove affiliation with a claimed company. Those associations need their own evidence. An authenticated enrollment process that verifies control of both records is one possible application design, not a feature supplied by the JSON above.

Read feedback in the context of the work

Once you have established which agent the records describe, you can inspect its feedback. The reputation contract records numeric feedback with decimal precision and optional tags. It also supports feedback revocation and aggregation over selected client addresses.

Read the units before comparing the numbers. A response-time measurement, a quality rating and an uptime percentage are different signals. Check who supplied the feedback, which service or task it concerns and whether it has been revoked. Agreeing on a storage format does not make every reviewer reliable.

A Headless Domains listing score evaluates a different set of public-record signals. It should not be presented as an ERC-8004 reputation score. Our agent trust score guide explains that distinction.

Review the connection after a transfer

ERC-8004's identity token can be transferred. In the current identity-registry implementation, that transfer clears the reserved agentWallet receiving address. Setting a replacement requires proof of control through the wallet-signature mechanism.

Then check the records outside the registry. Moving the ERC-8004 token does not automatically transfer a Headless Domains name, update an HTTPS endpoint or revoke the previous operator's API credentials. Plan those changes together, and recheck the affected associations before relying on the new operator.

The same applies to payments. ERC-8004 can publish payment-related information, but payment settlement remains outside its scope. Headless Domains provides its own documented registration and renewal workflows. Buying a name or declaring x402Support does not enable checkout at the agent's service. See our payment protocol comparison for that separate implementation decision.

Start with the agent you already operate

If you already have an ERC-8004 registration, keep its exact identifier and working service addresses. Add a Headless Domains name when a maintained public name would help customers and other agents recognize the service across those locations.

Ask a teammate to follow the name to the registry and back to the service. If they have to guess which record is yours, you still have a connection to fix.

Give your agent the Headless Domains machine instructions and ask it to explain how to register a name and connect the public records for your existing ERC-8004 agent before changing records or making payments.