The agent-registration.json
Well-Known URI Specification

1. Abstract

This document defines the agent-registration.json Well-Known URI [RFC 8615]. It provides a standardized mechanism for autonomous AI agents to prove they control a specific internet domain and to link their on-chain identity to that domain.

As autonomous AI agents increasingly operate real-world API endpoints and transact with other agents programmatically, there is a need for a simple, verifiable way to answer: “Does this agent actually control the domain and endpoint it claims?”

2. Motivation

On-chain agent registries (such as those using the ERC-8004 standard) allow agents to mint a permanent identity on a blockchain. However, an on-chain identity alone does not prove that the agent controls any specific domain or API endpoint. A malicious actor could register an agent claiming to serve https://example.com/api without controlling that domain.

Domain verification solves three problems:

• a.Endpoint authenticity — Proves the registered agent genuinely operates the API endpoint it advertises.
• b.Sybil resistance — Makes it expensive to create large numbers of fake agents, since each requires control of a real domain.
• c.Cross-registry interoperability — Allows any registry or client to independently verify an agent's identity by fetching a single file, without needing direct integration with the originating registry.

3. File Location

The file MUST be hosted at the following path on the agent's domain:

https://{agent-domain}/.well-known/agent-registration.json

The file MUST be served over HTTPS. The server MUST respond with Content-Type: application/json. The response MUST NOT require authentication (the file is public by design).

4. File Format (JSON Schema)

The file is a JSON object with the following structure:

{
  "version": "1.0",
  "domain": "myweatheragent.com",
  "agentIdentities": [
    {
      "registry": "agentarena.site",
      "standard": "ERC-8004",
      "globalId": "eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432#247",
      "chainId": 8453,
      "verificationEndpoint": "https://agentarena.site/api/agent/8453/247",
      "registeredAt": "2026-01-15T00:00:00Z",
      "signature": "0x..."
    }
  ],
  "endpoints": [
    {
      "url": "https://myweatheragent.com/api/forecast",
      "protocol": "x402",
      "description": "7-day weather forecast API"
    }
  ],
  "updatedAt": "2026-03-07T00:00:00Z"
}

4.1 Top-Level Fields

4.2 Agent Identity Object

Each object in agentIdentities represents a registration on a specific registry:

4.3 Endpoint Object

Each object in endpoints describes an API endpoint on this domain:

5. Verification Flow

Any party (registry, client agent, auditor) can verify an agent's domain claim by following this procedure:

1. 1.Fetch the file — Send an HTTPS GET request to https://{domain}/.well-known/agent-registration.json. If the response is not 200 OK with valid JSON, verification fails.
2. 2.Validate the domain field — The domain field in the response MUST exactly match the domain used in the request URL. If it does not match, verification fails.
3. 3.Verify identity against registry — For each entry in agentIdentities, send an HTTPS GET request to the verificationEndpoint. Confirm that the registry returns a valid agent profile matching the globalId.
4. 4.Verify signature (if present) — If the identity object includes a signature, verify it against the agent's on-chain wallet address. The signature MUST be over a canonical representation of the domain claim (see Section 5.1).
5. 5.Cache the result — Verifiers SHOULD cache results with a TTL of no more than 24 hours and re-verify periodically to detect domain transfers or revocations.

5.1 Signature Format

When present, the signature field MUST be an EIP-712 typed data signature over the following structure:

{
  "types": {
    "DomainClaim": [
      { "name": "domain", "type": "string" },
      { "name": "globalId", "type": "string" },
      { "name": "registry", "type": "string" },
      { "name": "timestamp", "type": "uint256" }
    ]
  },
  "primaryType": "DomainClaim",
  "domain": {
    "name": "AgentRegistration",
    "version": "1"
  },
  "message": {
    "domain": "myweatheragent.com",
    "globalId": "eip155:8453:0x8004A169...#247",
    "registry": "agentarena.site",
    "timestamp": 1741305600
  }
}

The verifier recovers the signer address from the signature and compares it to the agent's wallet address as recorded in the registry. If they match, the signature is valid, providing cryptographic proof that the wallet owner authorized the domain claim.

6. Distinction from agent-card.json

The existing agent-card.json Well-Known URI describes an agent's capabilities — what it can do, what formats it supports, and how to authenticate. In contrast, agent-registration.json proves identity — that the agent controls this domain and that its on-chain identity is legitimate. The two serve non-overlapping purposes and an agent MAY host both.

7. Cross-Registry Interoperability

The agentIdentities array supports multiple entries, enabling an agent registered on multiple registries to prove all identities from a single file. This allows any registry to independently verify agents from other registries without direct integration.

{
  "version": "1.0",
  "domain": "myagent.com",
  "agentIdentities": [
    {
      "registry": "agentarena.site",
      "standard": "ERC-8004",
      "globalId": "eip155:8453:0x8004A169...#247",
      "verificationEndpoint": "https://agentarena.site/api/agent/8453/247"
    },
    {
      "registry": "autonolas.network",
      "standard": "OLAS-service",
      "globalId": "service-123",
      "verificationEndpoint": "https://autonolas.network/api/service/123"
    }
  ],
  "updatedAt": "2026-03-07T00:00:00Z"
}

Verifiers SHOULD verify each identity entry independently. An agent is considered “cross-registry verified” only if all entries pass verification.

8. Security Considerations

• 8.1.HTTPS Required — The file MUST be served over HTTPS to prevent man-in-the-middle attacks. Verifiers MUST reject plain HTTP responses.
• 8.2.No Secrets — The file MUST NOT contain private keys, API keys, or any other secret material. It is public and cacheable.
• 8.3.Domain Transfer — If a domain changes ownership, the new owner could serve a different agent-registration.json. Verifiers SHOULD re-verify periodically (recommended: every 24 hours) and registries SHOULD revoke the domain_verified status if verification fails.
• 8.4.Signature Replay — The EIP-712 signature includes a timestamp. Verifiers SHOULD reject signatures older than 90 days and require the agent to re-sign.
• 8.5.Registry Trust — This specification does not define which registries are trustworthy. Verifiers MUST make their own trust decisions about which registry values they accept. A malicious actor could create a fake registry that always confirms identities.
• 8.6.Rate Limiting — Registries serving verification endpoints SHOULD implement rate limiting to prevent abuse by automated verifiers.

9. IANA Considerations

This document requests registration of the following Well-Known URI [RFC 8615]:

10. References

• [RFC 8615] Nottingham, M., “Well-Known Uniform Resource Identifiers (URIs)”, RFC 8615, May 2019. https://www.rfc-editor.org/rfc/rfc8615
• [ERC-8004] “Trustless Agent Standard”, Ethereum Improvement Proposal.
• [EIP-712] Steiner, R. et al., “Typed structured data hashing and signing”, EIP-712. https://eips.ethereum.org/EIPS/eip-712
• [A2A] Google / Linux Foundation, “Agent-to-Agent Protocol Specification”. https://a2a-protocol.org
• [EIP-155] Buterin, V., “Simple replay attack protection”, EIP-155. https://eips.ethereum.org/EIPS/eip-155

Appendix A: Minimal Example

The simplest valid agent-registration.json file, with a single identity and no endpoints or signature:

{
  "version": "1.0",
  "domain": "myagent.com",
  "agentIdentities": [
    {
      "registry": "agentarena.site",
      "standard": "ERC-8004",
      "globalId": "eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432#247",
      "verificationEndpoint": "https://agentarena.site/api/agent/8453/247"
    }
  ],
  "updatedAt": "2026-03-07T00:00:00Z"
}