# Table of Contents - [Agent Metadata Profile (AgentURI) | ERC-8004](#agent-metadata-profile-agenturi-erc-8004) --- # Agent Metadata Profile (AgentURI) | ERC-8004 [Skip to content](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#VPContent) On this page Agent Metadata Profile (AgentURI) ================================= Data ProfileVersion1.2UpdatedJan 27, 2026Community Guidelines Are you an LLM? You can read better optimized documentation at /docs/01-agent-metadata-standard.md for this page in Markdown format > **⚠️ Field Name Migration Notice (Jan 2026)** > > The official EIP-8004 specification has changed the field name from `endpoints` to `services`. > For backward compatibility, parsers SHOULD support both field names: > > * **`services`** - New official field name (EIP-8004 Jan 2026+) > * **`endpoints`** - Legacy field name (still widely used) > > **Migration Path**: New implementations SHOULD use `services`. Existing agents using `endpoints` > will continue to work. Parsers will emit a `WA031` warning recommending migration. > > See [Field Name Migration](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#field-name-migration-endpoints-to-services) > for details. Description [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#description) ----------------------------------------------------------------------------------------------------- Recommended offchain data profile for ERC-8004 agent registration This document provides implementation-agnostic guidance for structuring agent metadata referenced by the `agentURI` field in ERC-8004 Identity Registry contracts. Document Purpose [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#document-purpose) --------------------------------------------------------------------------------------------------------------- This profile document offers **practical, non-normative recommendations** for agent metadata formats, based on analysis of real-world ERC-8004 deployments and community feedback. **Key Characteristics**: * ✅ **Implementation-agnostic**: Applicable to any ERC-8004 registry or explorer * ✅ **Evidence-based**: Informed by analysis of [legacy testnet deployments](https://best-practices.8004scan.io/docs/reference/sources.html) * ✅ **Flexible**: Supports custom extensions while promoting interoperability * ✅ **Non-normative**: Guidelines and best practices, not requirements Relationship to EIP-8004 [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#relationship-to-eip-8004) ------------------------------------------------------------------------------------------------------------------------------- > **Important**: This is **not** part of the official [EIP-8004](https://eips.ethereum.org/EIPS/eip-8004) > specification. **Official EIP-8004** defines: * Smart contract interfaces for Identity Registry * The `agentURI` field that references metadata * Onchain behavior requirements **This profile** suggests: * Offchain JSON structure and field patterns * Protocol endpoint formats (MCP, A2A, OASF) * Best practices from production deployments The official EIP-8004 specification **does not mandate** specific offchain formats. These are community-developed guidelines to improve interoperability. Terminology [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#terminology) ----------------------------------------------------------------------------------------------------- This document follows conventions defined in [Conventions](https://best-practices.8004scan.io/docs/00-CONVENTIONS.html) . Intended Audience [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#intended-audience) ----------------------------------------------------------------------------------------------------------------- * Agent developers registering new agents * Registry implementers building indexers and explorers * Tool builders creating SDKs Table of Contents [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#table-of-contents) ----------------------------------------------------------------------------------------------------------------- 1. [Overview](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#overview) 2. [AgentURI Metadata Format](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#agenturi-metadata-format) 3. [Recommended Fields](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#recommended-fields) 4. [Endpoint Types](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#endpoint-types) 5. [Optional Fields](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#optional-fields) 6. [URI Format Standards](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#uri-format-standards) 7. [Data URI Compression Extension (Optional)](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#data-uri-compression-extension-optional) ⭐ 8. [Onchain Metadata](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#onchain-metadata) 9. [Validation Levels](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#validation-levels) 10. [Real-World Examples](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#real-world-examples) 11. [Updating Agent Metadata](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#updating-agent-metadata) 12. [Field Name Migration: `endpoints` → `services`](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#field-name-migration-endpoints-to-services) 🆕 Overview [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#overview) ----------------------------------------------------------------------------------------------- ### What is AgentURI Metadata? [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#what-is-agenturi-metadata) The **AgentURI** (also called Agent Metadata or Registration File) is the offchain data that describes an AI agent registered on ERC-8004 registries. It resolves from the `agentURI` field in the onchain NFT to a JSON object containing the agent's identity, capabilities, and communication endpoints. **Key Functions**: * 📋 **Agent Profile**: Name, description, and avatar for explorers and NFT marketplaces * 🔌 **Connectivity**: Endpoints for MCP, A2A, OASF protocols * 💰 **Payments**: Agent wallet addresses for x402 protocol * 🔗 **Verification**: Bidirectional link to onchain registry * 🏷️ **Trust Models**: Supported validation and reputation patterns > **Non-normative**: These functions represent common use cases observed in production deployments. Implementations MAY use agent metadata for other purposes. ### Architecture [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#architecture) text ┌─────────────────────────────────────────────────────────────┐ │ ERC-8004 Registry │ │ AgentNFT #123 │ │ ├─ owner: 0xABCD... │ │ ├─ agentURI: ipfs://bafkrei... ────────┐ │ │ └─ metadata[]: key-value pairs │ │ └───────────────────────────────────────────│─────────────────┘ │ ▼ ┌─────────────────────────┐ │ AgentURI Metadata │ │ (Offchain JSON) │ └─────────────────────────┘ │ ┌───────────────────────┼───────────────────────┐ ▼ ▼ ▼ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Agent Profile│ │ Endpoints │ │ Registrations│ │ │ │ │ │ │ │ - name │ │ - MCP │ │ - agentId │ │ - description│ │ - A2A │ │ - registry │ │ - image │ │ - OASF │ │ │ │ - active │ │ - agentWallet│ │ │ └──────────────┘ └──────────────┘ └──────────────┘ 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 AgentURI Metadata Format [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#agenturi-metadata-format) ------------------------------------------------------------------------------------------------------------------------------- ### Complete Schema [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#complete-schema) jsonc { // ============ SHOULD FIELDS (per official spec) ============ "type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1", "name": "myAgentName", "description": "A natural language description of the Agent", "image": "https://example.com/agentimage.png", // Services - fully customizable (per official spec) // NOTE: EIP-8004 uses "services" (Jan 2026+). Legacy "endpoints" is also supported. "services": [\ {\ "name": "web",\ "endpoint": "https://web.agentxyz.com/"\ },\ {\ "name": "A2A",\ "endpoint": "https://agent.example/.well-known/agent-card.json",\ "version": "0.3.0"\ },\ {\ "name": "MCP",\ "endpoint": "https://mcp.agent.eth/",\ "capabilities": [], // OPTIONAL, as per MCP spec\ "version": "2025-06-18"\ },\ {\ "name": "OASF",\ "endpoint": "ipfs://{cid}",\ "version": "0.8",\ "skills": [], // OPTIONAL\ "domains": [] // OPTIONAL\ },\ {\ "name": "ENS",\ "endpoint": "vitalik.eth",\ "version": "v1"\ },\ {\ "name": "email",\ "endpoint": "mail@myagent.com"\ }\ ], // ============ OPTIONAL FIELDS (MAY) ============ "x402Support": false, "active": true, "registrations": [\ {\ "agentId": 22,\ "agentRegistry": "eip155:1:0x742..." // {namespace}:{chainId}:{identityRegistry}\ }\ ], "supportedTrust": ["reputation", "crypto-economic", "tee-attestation"] } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 Recommended Fields [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#recommended-fields) ------------------------------------------------------------------------------------------------------------------- The following fields are **recommended** for maximum interoperability. Implementations MAY omit these fields or add custom extensions, but including them improves compatibility with explorers and tools. ### type (Recommended) [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#type-recommended) **Type**: `string` **Constraints**: For this profile, SHOULD be `"https://eips.ethereum.org/EIPS/eip-8004#registration-v1"` **Purpose**: Identifies this metadata as following the ERC-8004 agent registration profile. **Note**: The EIP-8004 specification does not mandate this field. This is a profile identifier to help parsers recognize the format. Other profile identifiers MAY exist for alternative metadata formats. **Example**: json { "type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1" } 1 2 3 **Validation**: * ⚠️ Missing: `missing_required_type` warning (reduces interoperability) * ⚠️ Non-standard value: `invalid_type_field` warning ### name (Recommended) [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#name-recommended) **Type**: `string` **Constraints**: Recommended length: 3–200 characters **Purpose**: Agent name displayed in explorers, NFT marketplaces, and user interfaces. **Guidelines**: * SHOULD be unique and descriptive * Avoid generic names like "Agent #123" (use meaningful identifiers) * For ERC-721 compatibility, this field is highly recommended **Examples**: json { "name": "DataAnalyst Pro" } 1 2 3 **Validation**: * ⚠️ Missing: `missing_required_name` warning * ⚠️ Empty string: validation warning > **Note**: While the official EIP-8004 lists `name` as SHOULD (not MUST), this profile treats it as practically required for visibility in explorers and NFT marketplaces. The field is derived from ERC-721 token metadata standards. ### description (Recommended) [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#description-recommended) **Type**: `string` **Purpose**: Natural language description of what the agent does, how it works, pricing, and interaction methods. **Guidelines**: * Explain agent capabilities clearly * Include interaction methods (e.g., "Call via MCP endpoint") * Mention pricing if applicable (e.g., "Free tier available") * Recommended length: 50-500 characters **Examples**: json { "description": "A specialized AI agent that performs advanced data analysis on blockchain transactions, providing insights and anomaly detection. Supports both free and premium tiers via x402 protocol." } 1 2 3 **Validation**: * ⚠️ Missing: `missing_recommended_description` warning ### image (Recommended) [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#image-recommended) **Type**: `string` (URI) **Purpose**: Agent avatar/logo displayed in explorers and NFT marketplaces. **Supported Formats**: * PNG (recommended) * SVG (vector graphics) * WebP (modern format) * JPG/JPEG (acceptable) **URI Schemes**: * `https://` - Direct HTTPS URL (recommended for reliability) * `ipfs://` - IPFS content hash * `ar://` - Arweave transaction ID * `data:image/png;base64,...` - Inline base64 (only for small images) **Guidelines**: * Recommended size: 512x512 px minimum * Aspect ratio: 1:1 (square) preferred * Max file size: 5 MB (suggestion, not enforced) * Use CDN for faster loading **Examples**: json { "image": "https://cdn.example.com/agents/dataanalyst-pro.png" } 1 2 3 json { "image": "ipfs://bafkreiaqdaerh5dvqmtjievkfnwfft6psghkxezygncbuvhl2uwyu6scn4" } 1 2 3 **Validation**: * ⚠️ Missing: `missing_recommended_image` warning * ⚠️ Relative path: validation warning (should be absolute URI) Additional Recommended Fields [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#additional-recommended-fields) ----------------------------------------------------------------------------------------------------------------------------------------- ### services / endpoints (SHOULD) [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#services-endpoints-should) **Type**: `array` of service/endpoint objects **Purpose**: Communication endpoints for interacting with the agent. **Importance**: MUST include at least one service if agent is meant to be interacted with. > **Field Name Migration (Jan 2026)** > > The official EIP-8004 specification changed this field from `endpoints` to `services`. > Parsers SHOULD support both for backward compatibility: > > | Field | Status | Usage | > | --- | --- | --- | > | `services` | ✅ **Recommended** | New official name (EIP-8004 Jan 2026+) | > | `endpoints` | ⚠️ Legacy | Still widely used, supported for compatibility | > > If both fields exist, `services` takes precedence. **General Structure**: json { "name": "EndpointType", "endpoint": "url_or_identifier", "version": "protocol_version" // ... type-specific fields } 1 2 3 4 5 6 7 **Validation**: * ⚠️ Using `endpoints`: `WA031` warning (recommend migrating to `services`) * ❌ Missing: `missing_endpoints` warning * ⚠️ Empty array: `empty_endpoints` warning (agent not reachable) * ⚠️ Common typo: `endpoint` (singular) instead of `endpoints`/`services` (plural) **See [Endpoint Types](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#endpoint-types) section for detailed specifications.** ### registrations (SHOULD) [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#registrations-should) **Type**: `array` of registration objects **Purpose**: Links to on-chain NFT identity, creating cryptographic bidirectional verification. **Structure**: json { "registrations": [\ {\ "agentId": 241,\ "agentRegistry": "eip155:11155111:0x8004a6090Cd10A7288092483047B097295Fb8847"\ }\ ] } 1 2 3 4 5 6 7 8 **Fields**: * `agentId` (number): Token ID from ERC-721 registry * `agentRegistry` (string): CAIP-10 format `namespace:chainId:contractAddress` **CAIP-10 Format**: text namespace : chainId : reference ↓ ↓ ↓ eip155 : 1 : 0x8004a6090Cd10A7288092483047B097295Fb8847 1 2 3 **Chain ID Examples**: * Ethereum Mainnet: `eip155:1:0x...` * Sepolia Testnet: `eip155:11155111:0x...` * Base Mainnet: `eip155:8453:0x...` * Base Sepolia: `eip155:84532:0x...` * Polygon: `eip155:137:0x...` **Validation**: * ✅ MUST match the on-chain agent ID and registry that points to this metadata file * ℹ️ Missing: `missing_registrations` info (no on-chain link, discovery-only) * ℹ️ Empty array: `empty_registrations` info (no on-chain link) * ℹ️ Null agentId: `registration_null_agent_id` info (expected for first-time deployments) * ⚠️ ID mismatch: `registration_agent_id_mismatch` warning * ⚠️ Invalid CAIP-10: `invalid_caip10_format` warning > **Note**: Missing or null `agentId` is expected during first-time deployments, as the tokenId is only assigned after the on-chain registration transaction confirms. Update the metadata after registration. **Circular Verification**: text NFT (on-chain) ↓ agentURI points to Metadata (offchain) ↓ registrations[0] points back to NFT (on-chain) ✅ verified 1 2 3 4 5 Endpoint Types [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#endpoint-types) ----------------------------------------------------------------------------------------------------------- ### 1\. MCP (Model Context Protocol) [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#_1-mcp-model-context-protocol) **Purpose**: Standard protocol for AI agents to expose tools, prompts, and resources. **Specification**: [MCP Protocol](https://modelcontextprotocol.io/) **Version Format**: Date-based (`YYYY-MM-DD`). Examples: `2025-06-18`, `2025-11-25`, `2026-01-29` **Structure**: json { "name": "MCP", "endpoint": "https://api.example.com/mcp", "version": "2025-11-25", "mcpTools": ["analyze_wallet", "detect_anomalies"], "capabilities": [] } 1 2 3 4 5 6 7 NOTE **v1.1 Change**: The `capabilities` field format changed from object `{}` to array `[]` in January 2026. **Fields**: * `endpoint` (string, REQUIRED): MCP server URL * `version` (string, REQUIRED): MCP protocol version in `YYYY-MM-DD` date format * `mcpTools` (array, OPTIONAL): List of available MCP tools * `mcpPrompts` (array, OPTIONAL): List of available prompts * `mcpResources` (array, OPTIONAL): List of available resources * `capabilities` (array, OPTIONAL): MCP server capabilities See [MCP Protocol Documentation](https://modelcontextprotocol.io/) for complete specification. ### 2\. A2A (Agent-to-Agent Protocol) [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#_2-a2a-agent-to-agent-protocol) **Purpose**: Enables agent-to-agent communication and collaboration. **Specification**: [A2A Protocol](https://a2a.to/) (current version: `0.3.0`) **Structure**: json { "name": "A2A", "endpoint": "https://agent.example/.well-known/agent-card.json", "version": "0.3.0", "a2aSkills": ["analytical_skills/coding_skills/text_to_code"] } 1 2 3 4 5 6 **Fields**: * `endpoint` (string, REQUIRED): URL to agent card (SHOULD use `/.well-known/agent-card.json` path) * `version` (string, REQUIRED): A2A protocol version (standard: `"0.3.0"`) * `a2aSkills` (array, OPTIONAL): OASF skill slugs for capability discovery **Agent Card**: The `endpoint` URL should resolve to an A2A Agent Card JSON. See [A2A Protocol Documentation](https://a2a.to/) for the complete Agent Card specification. ### 3\. OASF (Open Agentic Schema Framework) [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#_3-oasf-open-agentic-schema-framework) **Purpose**: Declares agent capabilities using standardized taxonomies for skills and domains. **Specification**: [OASF Releases](https://github.com/agntcy/oasf/releases) **Schema Browser**: [https://schema.oasf.outshift.com/](https://schema.oasf.outshift.com/) **Version Format**: Semver with optional 'v' prefix. Examples: `0.8.0`, `v0.8.0`, `0.8.3`, `0.7.4` NOTE OASF maintains multiple version lines (0.7.x, 0.8.x). Both are valid. Use the version that matches your OASF record's taxonomy. **Structure**: json { "name": "OASF", "endpoint": "https://github.com/agntcy/oasf/", "version": "0.8.0", "skills": [\ "analytical_skills/data_analysis/blockchain_analysis",\ "analytical_skills/pattern_recognition/anomaly_detection",\ "natural_language_processing/information_retrieval_synthesis/search"\ ], "domains": [\ "technology/blockchain",\ \ "technology/blockchain/cryptocurrency",\ "finance_and_business/investment_services"\ ] } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 **Fields**: * `endpoint` (string, REQUIRED): OASF repository URL (standard: `"https://github.com/agntcy/oasf/"`) * `version` (string, REQUIRED): OASF taxonomy version in semver format (e.g., `"0.8.0"` or `"v0.8.0"`) * `skills` (array, REQUIRED): OASF skill slugs (at least one of `skills` or `domains` required) * `domains` (array, REQUIRED): OASF domain slugs (at least one of `skills` or `domains` required) **Skill Taxonomy**: OASF skills follow a hierarchical structure: text category / subcategory / specific_skill ↓ ↓ ↓ analytical_skills / data_analysis / blockchain_analysis 1 2 3 **Common Skills** (examples from [legacy testnet data](https://best-practices.8004scan.io/docs/reference/sources.html#8-production-agent-metadata) ): * `natural_language_processing/natural_language_generation/summarization` * `tool_interaction/api_schema_understanding` * `multi_modal/image_processing/text_to_image` * `natural_language_processing/information_retrieval_synthesis/search` * `tool_interaction/workflow_automation` **Domain Taxonomy**: OASF domains categorize agent application areas: text industry / sector / specialization ↓ ↓ ↓ finance_and_business / investment_services 1 2 3 **Common Domains** (examples from [legacy testnet data](https://best-practices.8004scan.io/docs/reference/sources.html#8-production-agent-metadata) ): * `technology/blockchain` * `finance_and_business/finance` * `technology/software_engineering/apis_integration` * `technology/blockchain/cryptocurrency` * `media_and_entertainment/content_creation` **Resources**: * [OASF Schema Browser](https://schema.oasf.outshift.com/0.8.0) * [Complete skill list](https://github.com/agntcy/oasf/blob/v0.8.0/all_skills.json) * [Complete domain list](https://github.com/agntcy/oasf/blob/v0.8.0/all_domains.json) ### 4\. agentWallet [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#_4-agentwallet) IMPORTANT `agentWallet` is a **reserved onchain metadata key**. The verified wallet is set automatically to the owner during `register(...)` and can only be updated via `setAgentWallet(uint256 agentId, address newWallet, uint256 deadline, bytes signature)` (EIP-712 or ERC-1271). Deadline must be ≤ now + 5 minutes. Offchain declarations are for discovery only; the onchain value is authoritative for payments. **Purpose**: Payment wallet address for x402 protocol and agent-to-agent transactions. **Format**: CAIP-10 (Account ID Specification) **Offchain Structure** (for discovery): json { "name": "agentWallet", "endpoint": "eip155:1:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7" } 1 2 3 4 **Onchain Update** (v1.1.0): solidity // Update wallet with cryptographic verification (EIP-712 or ERC-1271) function setAgentWallet(uint256 agentId, address newWallet, uint256 deadline, bytes calldata signature) external 1 2 **Key behaviors**: * Callable by owner or approved operators * Initially set to the registering owner * Cannot be set via `setMetadata()` (reserved key) * Deadline must be current time or sooner than `now + 5 minutes` * New wallet must sign the typed data (or pass ERC-1271) * On transfer, resets to zero address (must be re-verified by new owner) **CAIP-10 Format**: text namespace : chainId : accountAddress ↓ ↓ ↓ eip155 : 1 : 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7 1 2 3 **Chain Examples**: * Ethereum Mainnet: `"eip155:1:0x..."` * Sepolia Testnet: `"eip155:11155111:0x..."` * Base Mainnet: `"eip155:8453:0x..."` * Base Sepolia: `"eip155:84532:0x..."` * Polygon: `"eip155:137:0x..."` **Validation**: * ⚠️ Invalid CAIP-10 format: `wallet_invalid_format` warning * ⚠️ Invalid checksum: `wallet_invalid_checksum` warning **Multiple Wallets**: Agents can have wallets on multiple chains: json { "services": [\ {\ "name": "agentWallet",\ "endpoint": "eip155:1:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7"\ },\ \ {\ "name": "agentWallet",\ "endpoint": "eip155:8453:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7"\ }\ ] } 1 2 3 4 5 6 7 8 9 10 11 12 13 ### 5\. ENS Name [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#_5-ens-name) **Purpose**: Human-readable Ethereum Name Service identifier. **Structure**: json { "name": "ENS", "endpoint": "dataanalyst.eth", "version": "v1" } 1 2 3 4 5 **Fields**: * `endpoint` (string, REQUIRED): ENS name (e.g., `"myagent.eth"`) * `version` (string, OPTIONAL): ENS version (typically `"v1"`) **Usage**: * Resolves to Ethereum address * Can be used for agent discovery * Human-friendly identifier ### 6\. DID (Decentralized Identifier) [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#_6-did-decentralized-identifier) **Purpose**: W3C DID standard for decentralized identity. **Structure**: json { "name": "DID", "endpoint": "did:ethr:0x1234567890abcdef1234567890abcdef12345678", "version": "v1" } 1 2 3 4 5 6 **Supported DID Methods**: * `did:ethr:...` - Ethereum DID * `did:web:...` - Web DID * `did:key:...` - Key DID **Fields**: * `endpoint` (string, REQUIRED): DID identifier * `version` (string, OPTIONAL): DID version ### 7\. Human-Facing Endpoints (NEW in v1.1) [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#_7-human-facing-endpoints-new-in-v1-1) NOTE **v1.1 Addition**: The January 2026 update added `web` and `email` as standard human-facing endpoint types. **Purpose**: Contact and information endpoints for human users (not agent-to-agent communication). **Structure**: json { "services": [\ {\ "name": "web",\ "endpoint": "https://myagent.example.com"\ },\ {\ "name": "email",\ "endpoint": "support@myagent.example.com"\ }\ ] } 1 2 3 4 5 6 7 8 9 10 11 12 **Fields**: * `web` - Agent's public website or landing page * `email` - Contact email for support or inquiries ### 8\. Custom Endpoints [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#_8-custom-endpoints) The ERC-8004 spec allows arbitrary endpoint types for protocol-specific needs. **Example 1: Custom API**: json { "name": "StarCard API", "version": "1.0.0", "endpoint": "https://aliasai.io/api/v1/star_card/agent/{uid}", "description": "Retrieve the user's complete star card information" } 1 2 3 4 5 6 **Example 2: Custom Protocol**: json { "name": "wallet", "endpoint": "eip155:11155111:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7" } 1 2 3 4 **Guidelines**: * Use descriptive `name` field * Include `description` for custom endpoints * Follow CAIP standards when applicable Optional Fields [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#optional-fields) ------------------------------------------------------------------------------------------------------------- ### supportedTrust (MAY) [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#supportedtrust-may) **Type**: `array` of strings **Purpose**: Declares trust models the agent supports for validation and reputation. **Structure**: json { "supportedTrust": ["reputation", "crypto-economic", "tee-attestation"] } 1 2 3 **Standard Values**: * `"reputation"` - On-chain feedback and reputation system * `"crypto-economic"` - Stake-secured validation with slashing * `"tee-attestation"` - Trusted Execution Environment proofs * `"social-graph"` - Social graph-based trust (emerging) **Validation**: * ⚠️ Unknown value: `unknown_trust_model` warning * ⚠️ Empty array: `empty_supported_trust` warning **Adoption** (from [legacy testnet data](https://best-practices.8004scan.io/docs/reference/sources.html#8-production-agent-metadata) ): See [Sources & References](https://best-practices.8004scan.io/docs/reference/sources.html) for detailed adoption statistics. ### active (MAY) [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#active-may) **Type**: `boolean` **Purpose**: Production readiness flag. **Structure**: json { "active": true } 1 2 3 **Values**: * `true` - Agent is production-ready and actively accepting requests * `false` - Agent is in development, testing, or inactive **Default**: `false` or `undefined` (inactive) **Validation**: * ⚠️ `active: false`: `agent_not_active` warning (not production-ready) * ⚠️ Non-boolean: `invalid_boolean_active` warning ### x402Support (MAY) [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#x402support-may) **Type**: `boolean` **Purpose**: Indicates support for x402 payment protocol (HTTP 402 Payment Required). **Structure**: json { "x402Support": true } 1 2 3 **Values**: * `true` - Agent accepts x402 payment requests * `false` - Agent does not support x402 **Requirements**: If `x402Support: true`, agent SHOULD have an `agentWallet` endpoint defined. **Validation**: * ⚠️ Non-boolean: `invalid_boolean_x402` warning ### updatedAt (MAY) [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#updatedat-may) **Type**: `number` (Unix timestamp) **Purpose**: Last update timestamp for metadata freshness tracking. **Structure**: json { "updatedAt": 1763112328 } 1 2 3 **Format**: Unix timestamp (seconds since epoch) **Usage**: * Helps explorers show "last updated" time * Can be used for ranking/sorting by freshness **Example**: javascript // Generate current timestamp const updatedAt = Math.floor(Date.now() / 1000); 1 2 URI Format Standards [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#uri-format-standards) ----------------------------------------------------------------------------------------------------------------------- ### Recommended Priority (by Immutability) [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#recommended-priority-by-immutability) **For production agents, choose URI format based on immutability guarantees:** | Priority | Format | Immutability | Gas Cost | Recommendation | | --- | --- | --- | --- | --- | | **🥇 Best** | Data URI | ✅✅✅ Guaranteed (on-chain) | 💰💰💰 High | **Most Recommended** - Perfect immutability | | **🥈 Good** | IPFS/Arweave | ✅✅ Strong (content-addressed) | 💰 Low | Good balance of immutability & cost | | **🥉 Acceptable** | HTTP/HTTPS | ❌ None (mutable, centralized) | 💰 Low | **Least Recommended** - Can change/disappear | **Immutability Trade-offs**: 1. **Data URI (Best Immutability)** ✅ * **Pros**: * Metadata stored directly on-chain * Cannot be changed or removed * No external dependencies * Instant retrieval (no network fetch) * **Cons**: * High gas cost (~70,000-340,000 gas for 3KB-20KB metadata) * Limited size (practical limit ~50KB due to block gas limit) * **When to Use**: Production agents requiring absolute immutability, regulatory compliance 2. **IPFS/Arweave (Good Immutability)** ⚖️ * **Pros**: * Content-addressed (CID verifies integrity) * Low gas cost (~40,000-70,000 gas for URI storage only) * Decentralized storage * **Cons**: * Requires gateway availability * Pinning needed to ensure availability * Potential network delays * **When to Use**: Most production agents, balance of cost and immutability 3. **HTTP/HTTPS (No Immutability)** ⚠️ * **Pros**: * Low gas cost (~40,000-70,000 gas for URI storage only) * Easy updates (dynamic metadata) * Fast retrieval from CDN * **Cons**: * **Can be changed at any time** (mutable) * **Can disappear** (centralized, single point of failure) * Trust required in server operator * **When to Use**: Development/testing only, or agents that need frequent metadata updates **Recommendation Summary**: * 🏆 **Production agents**: Use Data URI for critical metadata, IPFS for larger files * 🧪 **Development/Testing**: HTTP/HTTPS acceptable for rapid iteration * 🔄 **Hybrid Approach**: Store core metadata in Data URI, reference additional files via IPFS ### Supported URI Schemes [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#supported-uri-schemes) 8004scan supports 7 URI formats for AgentURI metadata, ensuring maximum compatibility with different storage systems. #### 1\. Data URI (🥇 Most Recommended for Immutability) [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#_1-data-uri-%F0%9F%A5%87-most-recommended-for-immutability) **Base64 Format**: text data:application/json;base64, 1 **Plain Format**: text data:application/json, 1 **Example (Base64)**: text data:application/json;base64,ewogICJ0eXBlIjogImh0dHBzOi8vZWlwcy5ldGhlcmV1bS5vcmcvRUlQUy9laXAtODAwNCNyZWdpc3RyYXRpb24tdjEiLAogICJuYW1lIjogIkFnZW50IE5hbWUiCn0= 1 **Example (Plain)**: text data:application/json,{"type":"https://eips.ethereum.org/EIPS/eip-8004#registration-v1","name":"Agent"} 1 **Benefits**: * ✅✅✅ **Perfect immutability** (stored on-chain) * ✅ No external dependencies * ✅ Instant retrieval (no network fetch) * ✅ Cryptographically verified by blockchain **Drawbacks**: * ⚠️ High gas cost (~70,000-340,000 gas for 3KB-20KB metadata) * ⚠️ Size limit (practical limit ~50KB due to block gas limit) **Parser Behavior**: * Extract base64 payload after `data:application/json;base64,` * Base64 decode → UTF-8 decode → JSON parse * For plain format: URL decode if needed → JSON parse **Edge Case**: Some URIs claim `base64` but contain plain JSON. Parser detects `{` or `[` at start and skips base64 decode.\ \ **Recommendation**: 🏆 **Use for production agents requiring absolute immutability**\ \ #### 2\. IPFS URIs (🥈 Good Balance - Recommended) [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#_2-ipfs-uris-%F0%9F%A5%88-good-balance-recommended)\ \ **Format**:\ \ text\ \ ipfs://CID\ \ ipfs://CID/path/to/file.json\ \ 1 \ 2 \ 3 \ \ **Examples**:\ \ text\ \ ipfs://bafkreiaqdaerh5dvqmtjievkfnwfft6psghkxezygncbuvhl2uwyu6scn4\ ipfs://QmXXX/metadata.json\ \ 1 \ 2 \ \ **Benefits**:\ \ * ✅✅ **Strong immutability** (content-addressed)\ * ✅ Decentralized storage\ * ✅ Low gas cost (~40,000-70,000 gas for URI storage)\ * ✅ Global availability via gateways\ * ✅ CID verifies content integrity\ \ **Drawbacks**:\ \ * ⚠️ Requires gateway availability\ * ⚠️ Pinning needed to ensure long-term availability\ * ⚠️ Potential network delays (gateway fetch time)\ \ **Gateway Resolution**: \ 8004scan uses fallback gateways for reliability:\ \ 1. `https://ipfs.io/ipfs/{CID}`\ 2. `https://cloudflare-ipfs.com/ipfs/{CID}`\ 3. `https://gateway.pinata.cloud/ipfs/{CID}`\ \ **Recommendation**: ⚖️ **Best balance of immutability and cost for most production agents**\ \ #### 3\. Arweave URIs (🥈 Good Balance - Permanent Storage) [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#_3-arweave-uris-%F0%9F%A5%88-good-balance-permanent-storage)\ \ **Format**:\ \ text\ \ ar://TX_ID\ \ ar://TX_ID/path\ \ 1 \ 2 \ 3 \ \ **Examples**:\ \ text\ \ ar://a1b2c3d4e5f6\ \ 1 \ \ **Benefits**:\ \ * ✅ Permanent storage (pay once, store forever)\ * ✅ Content-addressed\ * ✅ Decentralized\ \ **Gateway Resolution**:\ \ * `https://arweave.net/{TX_ID}`\ \ #### 4\. HTTP/HTTPS URLs (🥉 Least Recommended - Use Only for Development) [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#_4-http-https-urls-%F0%9F%A5%89-least-recommended-use-only-for-development)\ \ **Format**:\ \ text\ \ https://example.com/metadata.json\ \ http://example.com/api/agent/123\ \ 1 \ 2 \ 3 \ \ **Examples**:\ \ text\ \ https://cdn.example.com/agents/dataanalyst-pro.json\ https://api.example.com/v1/agents/241/metadata\ \ 1 \ 2 \ \ **Benefits**:\ \ * ✅ Low gas cost (~40,000-70,000 gas for URI storage)\ * ✅ Fast updates (dynamic metadata)\ * ✅ Direct control over content\ * ✅ Fast CDN retrieval\ \ **Drawbacks**:\ \ * ❌❌❌ **NO IMMUTABILITY** (metadata can be changed at any time)\ * ❌ **Can disappear** (server downtime, domain expiration, operator decision)\ * ⚠️ Centralized (single point of failure)\ * ⚠️ Trust required in server operator\ * ⚠️ May require authentication\ \ **Security Note**: HTTPS is strongly preferred over HTTP.\ \ **Recommendation**: ⚠️ **Use only for development/testing, or agents requiring frequent metadata updates. NOT recommended for production agents requiring trust.**\ \ #### 5\. Data URI (Non-Standard) - Edge Case [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#_5-data-uri-non-standard-edge-case)\ \ **Observed formats**:\ \ text\ \ \ data:text/plain;base64,\ data:;base64,\ data:application/json;charset=utf-8;base64,\ \ 1 \ 2 \ 3 \ 4 \ \ **Parser Behavior**:\ \ * Generic fallback parser\ * Try base64 decode first\ * If fails, try plain JSON\ * Log warning about non-standard format\ \ #### 6\. Plain JSON (No URI Scheme) - Edge Case [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#_6-plain-json-no-uri-scheme-edge-case)\ \ **Format**: Raw JSON stored as metadata URI (no URI scheme)\ \ **Example**:\ \ json\ \ { "type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1", "name": "Agent" }\ \ 1 \ \ **Parser Behavior**:\ \ * Fallback parser\ * Direct JSON parse\ * Log warning: `plain_json_without_uri_scheme`\ \ Data URI Compression Extension (Optional) [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#data-uri-compression-extension-optional)\ \ ---------------------------------------------------------------------------------------------------------------------------------------------------------------\ \ > **8004scan Extension**: This is an optional protocol extension designed to reduce on-chain gas costs while maintaining Data URI's perfect immutability guarantees.\ \ ### Overview [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#overview-1)\ \ Standard Data URI metadata can be expensive (70,000-340,000 gas for 3KB-20KB data). This compression extension reduces gas costs by **35-67%** through data compression while preserving all benefits of on-chain storage.\ \ **Format**:\ \ text\ \ data:application/json;enc=[;level=];base64,\ \ 1 \ \ **Supported Algorithms**: `zstd` (recommended), `gzip`, `br` (Brotli), `lz4`\ \ **Recommendation**: **Zstd level 9-15** for optimal balance of compression ratio and speed.\ \ ### When to Use [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#when-to-use)\ \ | Metadata Size | Recommendation |\ | --- | --- |\ | < 1KB | Optional (marginal savings) |\ | 1-3KB | Recommended (~24,000-32,000 gas saved) |\ | \> 3KB | Strongly recommended (~32,000+ gas saved) |\ \ ### Backward Compatibility [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#backward-compatibility)\ \ * ✅ **Compressed**: `data:application/json;enc=zstd;base64,...`\ * ✅ **Uncompressed**: `data:application/json;base64,...`\ * No breaking changes for existing agents\ \ **For detailed protocol specification, security considerations, and implementation examples**, see [Data URI Compression Extension](https://best-practices.8004scan.io/docs/extensions/data-uri-compression.html)\ .\ \ Onchain Metadata [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#onchain-metadata)\ \ ---------------------------------------------------------------------------------------------------------------\ \ In addition to AgentURI metadata (offchain), ERC-8004 supports **onchain metadata** stored as key-value pairs via `setMetadata(uint256 agentId, string key, bytes value)`.\ \ ### Common Keys [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#common-keys)\ \ | Key | Type | Description | Example |\ | --- | --- | --- | --- |\ | `agentWallet` | address | Payment wallet address (reserved) | `0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7` |\ | `agentHash` | bytes32 | Metadata content hash (8004scan ext.) | `0x1234...abcd` (keccak256) |\ | `agentName` | string | ENS name or human-readable identifier | `"dataanalyst.eth"` |\ | `version` | string | Agent version | `"1.0.0"` |\ | `category` | string | Classification tag | `"developer-tools"` |\ | `pricing` | string | Pricing tier | `"free"` |\ \ ### agentHash (8004scan Extension) [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#agenthash-8004scan-extension)\ \ > **8004scan Extension**: Optional integrity verification for HTTP/HTTPS agentURI.\ \ For HTTP/HTTPS URIs (which are mutable), owners MAY set `agentHash` to enable content integrity verification:\ \ solidity\ \ // Compute: keccak256(canonicalJSON) where keys are sorted alphabetically\ registry.setMetadata(agentId, "agentHash", abi.encodePacked(hash));\ \ 1 \ 2 \ \ **Benefits**:\ \ * Indexers can verify fetched content matches owner's intent\ * Signals intentional metadata updates when hash changes\ * Provides trust signal for mutable URIs\ \ **Note**: Not needed for IPFS/Arweave (already content-addressed).\ \ ### Relationship to AgentURI [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#relationship-to-agenturi)\ \ **Key Difference**:\ \ * **AgentURI metadata** (offchain): Comprehensive JSON with full agent details\ * **Onchain metadata** (on-chain): Key-value pairs for specific indexed fields\ \ **Best Practice**: Synchronize both when possible. For example:\ \ * AgentURI: `"services": [{"name": "agentWallet", "endpoint": "eip155:1:0x..."}]`\ * Onchain: `setMetadata(agentId, "agentWallet", 0x...)`\ \ **Precedence**: If both exist, AgentURI metadata is considered the source of truth for display purposes.\ \ Validation Levels [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#validation-levels)\ \ -----------------------------------------------------------------------------------------------------------------\ \ Implementations SHOULD validate agent metadata at multiple levels to ensure quality while remaining flexible for custom formats.\ \ ### Recommended Validation Approach [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#recommended-validation-approach)\ \ | Level | Focus | Description |\ | --- | --- | --- |\ | **Level 1** | Syntax | URI format, JSON parsing, base64 decoding |\ | **Level 2** | Schema | Required/recommended fields presence |\ | **Level 3** | Endpoints | Protocol-specific field validation |\ | **Level 4** | Semantic | Trust model values, cross-field consistency |\ | **Level 5** | Status | Production readiness flags |\ \ ### Validation Severity Levels [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#validation-severity-levels)\ \ Following RFC 2119/8174 terminology:\ \ | Level | RFC Keywords | Description |\ | --- | --- | --- |\ | **Error** | MUST, MUST NOT | Critical issues preventing proper functioning |\ | **Warning** | SHOULD, SHOULD NOT | Functional issues but not critical |\ | **Info** | MAY, RECOMMENDED | Best practices, recommendations, or expected states |\ \ **Examples by Severity**:\ \ * **Error**: Invalid JSON syntax, unsupported URI format\ * **Warning**: Missing required fields (type, name), invalid CAIP format\ * **Info**: Missing `agentId` (first-time deployment), A2A endpoint not using `.well-known` path\ \ **Implementation Note**: Validators SHOULD collect warnings and info messages without failing on non-critical issues. This allows maximum interoperability while providing feedback to agent developers.\ \ For a detailed implementation guide with specific warning codes and validation logic, see [Agent Metadata Parsing Guide](https://best-practices.8004scan.io/docs/implementation/agent-metadata-parsing.html#validation-error-codes)\ .\ \ Real-World Examples [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#real-world-examples)\ \ ---------------------------------------------------------------------------------------------------------------------\ \ For examples of agent metadata formats observed in production deployments, see [Real-World Examples](https://best-practices.8004scan.io/docs/reference/real-world-examples.html)\ .\ \ Updating Agent Metadata [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#updating-agent-metadata)\ \ -----------------------------------------------------------------------------------------------------------------------------\ \ ### Upgrading Metadata Version [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#upgrading-metadata-version)\ \ When updating agent metadata, increment `updatedAt` timestamp:\ \ **Before**:\ \ json\ \ {\ "name": "MyAgent v1",\ "updatedAt": 1763112328\ }\ \ 1 \ 2 \ 3 \ 4 \ \ **After**:\ \ json\ \ {\ "name": "MyAgent v2",\ "updatedAt": 1763200000 // ← New timestamp\ }\ \ 1 \ 2 \ 3 \ 4 \ \ **On-Chain Update** (v1.1.0):\ \ NOTE\ \ `setAgentURI()` is exposed on the registry; callable by owner or approved operator; emits `URIUpdated`.\ \ solidity\ \ // Update agentURI on ERC-8004 registry (owner or approved)\ agentRegistry.setAgentURI(agentId, newAgentURI);\ \ 1 \ 2 \ \ **Function Signature**:\ \ solidity\ \ function setAgentURI(uint256 agentId, string calldata newAgentURI) external;\ \ 1 \ \ **Requirements**:\ \ * Caller MUST be the agent owner or an approved operator\ * `agentId` MUST exist\ * Emits `URIUpdated(agentId, newAgentURI, updatedBy)`\ \ FAQ [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#faq)\ \ -------------------------------------------------------------------------------------\ \ ### Q: How do I deploy and index the same agent across multiple chains? [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#q-how-do-i-deploy-and-index-the-same-agent-across-multiple-chains)\ \ **A**: Use CAIP-2 chain IDs and the two-phase registration flow to link agents across chains:\ \ **Challenge**: Since `agentId` is assigned at registration time (auto-incrementing NFT token ID), you cannot know all IDs upfront when deploying to multiple chains.\ \ **Solution**: Use `register()` without URI first, then update with `setAgentURI()` after collecting all IDs.\ \ 1. **Phase 1 - Register on all chains** (without URI):\ \ solidity\ \ // On Base Sepolia (chain 84532)\ uint256 baseAgentId = baseRegistry.register(); // Returns 42\ \ // On Ethereum Sepolia (chain 11155111)\ uint256 ethAgentId = ethRegistry.register(); // Returns 99\ \ 1 \ 2 \ 3 \ 4 \ 5 \ \ 2. **Phase 2 - Create unified registration file** with all collected IDs:\ \ json\ \ {\ "name": "My Agent",\ "registrations": [\ {\ "agentId": 42,\ "agentRegistry": "eip155:84532:0x8004..."\ },\ {\ "agentId": 99,\ "agentRegistry": "eip155:11155111:0xAbcd..."\ }\ ]\ }\ \ 1 \ 2 \ 3 \ 4 \ 5 \ 6 \ 7 \ 8 \ 9 \ 10 \ 11 \ 12 \ 13 \ \ 3. **Phase 3 - Update URI on all chains** to point to the same file:\ \ solidity\ \ // Upload registration file to IPFS → ipfs://Qm...\ \ // Update on Base Sepolia\ baseRegistry.setAgentURI(42, "ipfs://Qm...");\ \ // Update on Ethereum Sepolia\ ethRegistry.setAgentURI(99, "ipfs://Qm...");\ \ 1 \ 2 \ 3 \ 4 \ 5 \ 6 \ 7 \ \ 4. **Indexing**: Treat `(agentRegistry, agentId)` as unique identifier\ \ * Tag feedback/validation records with source chain\ * Aggregate scores across all chains for global reputation\ * Indexers discover all deployments by parsing the `registrations` array\ \ * * *\ \ References [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#references)\ \ ---------------------------------------------------------------------------------------------------\ \ ### Official Specifications [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#official-specifications)\ \ * [EIP-8004: Trustless Agents](https://eips.ethereum.org/EIPS/eip-8004)\ \ * [CAIP-2: Chain ID Specification](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md)\ \ * [CAIP-10: Account ID Specification](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-10.md)\ \ \ ### Protocol Documentation [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#protocol-documentation)\ \ * [MCP Protocol](https://modelcontextprotocol.io/)\ \ * [A2A Protocol v0.3.0](https://a2a.to/)\ \ * [OASF v0.8.0 Taxonomy](https://github.com/agntcy/oasf/tree/v0.8.0)\ * [Schema Browser](https://schema.oasf.outshift.com/0.8.0)\ \ * [All Skills](https://github.com/agntcy/oasf/blob/v0.8.0/all_skills.json)\ \ * [All Domains](https://github.com/agntcy/oasf/blob/v0.8.0/all_domains.json)\ \ \ ### 8004scan Resources [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#_8004scan-resources)\ \ * [Agent Metadata Parsing Guide](https://best-practices.8004scan.io/docs/implementation/agent-metadata-parsing.html)\ \ * [Feedback Standard](https://best-practices.8004scan.io/docs/02-feedback-standard.html)\ \ * [Validation Standard](https://best-practices.8004scan.io/docs/03-validation-standard.html)\ \ * [Sources & References](https://best-practices.8004scan.io/docs/reference/sources.html)\ \ \ Field Name Migration: endpoints to services [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#field-name-migration-endpoints-to-services)\ \ --------------------------------------------------------------------------------------------------------------------------------------------------------------------\ \ ### Background [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#background)\ \ In January 2026, the official EIP-8004 specification updated the field name from `endpoints` to `services` in the Agent Registration File schema. This change aligns with broader industry terminology.\ \ **Official EIP-8004 Spec (Jan 2026)**:\ \ jsonc\ \ {\ "services": [\ { "name": "MCP", "endpoint": "https://..." },\ { "name": "A2A", "endpoint": "https://..." }\ ]\ }\ \ 1 \ 2 \ 3 \ 4 \ 5 \ 6 \ \ **Legacy Format (still supported)**:\ \ jsonc\ \ {\ "endpoints": [\ { "name": "MCP", "endpoint": "https://..." },\ { "name": "A2A", "endpoint": "https://..." }\ ]\ }\ \ 1 \ 2 \ 3 \ 4 \ 5 \ 6 \ \ ### Compatibility Strategy [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#compatibility-strategy)\ \ To ensure backward compatibility, parsers (including 8004scan backend) implement the following:\ \ 1. **Accept both fields**: `services` and `endpoints` are both valid\ 2. **Prefer `services`**: If both exist, `services` takes precedence\ 3. **Emit migration warning**: When `endpoints` is used, emit `WA031` warning message\ \ ### Migration Steps [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#migration-steps)\ \ **For Agent Developers**:\ \ 1. Update your agent metadata to use `services` instead of `endpoints`\ 2. The field structure remains identical—only the array name changes\ 3. No changes needed to individual service objects\ \ **Example Migration**:\ \ diff\ \ {\ "name": "My Agent",\ "type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",\ - "endpoints": [\ + "services": [\ {\ "name": "MCP",\ "endpoint": "https://mcp.myagent.com",\ "version": "2025-06-18"\ }\ ]\ }\ \ 1 \ 2 \ 3 \ 4 \ 5 \ 6 \ 7 \ 8 \ 9 \ 10 \ 11 \ 12 \ \ **For Parser Implementers**:\ \ plaintext\ \ # Support both field names with preference for 'services'\ services = metadata.get("services") OR metadata.get("endpoints")\ \ IF "endpoints" exists in metadata AND "services" does not exist THEN\ # Emit WA031 warning message recommending migration\ warnings.append({"code": "WA031", "message": "Using legacy 'endpoints' field..."})\ END IF\ \ 1 \ 2 \ 3 \ 4 \ 5 \ 6 \ 7 \ \ ### Timeline [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#timeline)\ \ | Phase | Date | Status |\ | --- | --- | --- |\ | Spec Updated | Jan 2026 | ✅ Complete |\ | Parser Support | Jan 2026 | ✅ Complete (8004scan v0.2.28+) |\ | Migration Period | Jan 2026 - Dec 2026 | 🔄 In Progress |\ | Legacy Deprecation | TBD | 📅 Planned |\ \ > **Note**: There is no immediate deprecation timeline for `endpoints`. Both field names will be supported for the foreseeable future. The `WA031` warning recommends migration but does not prevent usage.\ \ Changelog [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#changelog)\ \ -------------------------------------------------------------------------------------------------\ \ | Version | Date | Changes |\ | --- | --- | --- |\ | **1.3** | 2026-01-27 | Document `endpoints` → `services` field name migration per EIP-8004 Jan 2026 update; add WA031 warning code |\ | **1.2** | 2026-01-11 | Added 3-level validation severity (error/warning/info); adjusted agentId and A2A path to info level |\ | **1.1** | 2026-01-09 | v1.1: agentWallet onchain, MCP array, web/email, setURI |\ | **0.1** | 2025-12-20 | Initial draft based on 4,725 agent analysis |\ \ Contact [​](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html#contact)\ \ ---------------------------------------------------------------------------------------------\ \ * **Documentation Maintainer**: 8004scan Development Team\ * **Review Frequency**: Monthly\ * **Next Review**: 2026-02-09\ \ For questions about this standard:\ \ * **EIP-8004 Spec** → Refer to official specification\ * **Implementation** → Check [Agent Metadata Parsing Guide](https://best-practices.8004scan.io/docs/implementation/agent-metadata-parsing.html)\ \ * **Real-world usage** → See [sources and examples](https://best-practices.8004scan.io/docs/reference/sources.html)\ \ \ * * *\ \ **Version**: 1.3 \ **Last Updated**: 2026-01-27 \ **Status**: Community Guidelines ---