ERC-8004: Trustless Agents

ERC-8004 is a draft EIP for discovering, choosing, and interacting with AI agents across organizational boundaries without pre-existing trust. It defines three on-chain registries deployed as per-chain singletons on any EVM chain.

Authors: Marco De Rossi (MetaMask), Davide Crapis (EF), Jordan Ellis (Google), Erik Reppel (Coinbase)

Full spec: references/spec.md

Intent

Register AI agents on-chain with verifiable identity (ERC-721 NFTs), build and query reputation systems, discover agents by capability or trust model, and integrate with the Agent0 TypeScript SDK for trustless agent interaction. Use this skill when you need cryptographic proof of agent identity, want to award or read reputation signals from multiple validators, implement ERC-8004 smart contract integrations, or set up agent wallets, MCP/A2A endpoints, or OASF taxonomies across EVM chains.

Inputs

Environment Variables (see metadata.openclaw.envVars):

• RPC_URL (optional): JSON-RPC endpoint for the registry chain. If absent, SDK uses public fallback endpoints (may have rate limits). Recommendation: use Alchemy or Infura for production.
• PRIVATE_KEY (optional): 0x-prefixed hex string. Required for on-chain registration and feedback submission. Never commit to version control. Use throwaway keys on testnets; hardware wallet or scoped signer for mainnet. The SDK signs transactions with this key.
• PINATA_JWT (optional): Bearer token for Pinata IPFS service. Required if calling agent.registerIPFS(). If absent, registration falls back to HTTPS-only mode (caller must host registration JSON and call agent.registerHTTPS() instead).

Agent0 SDK Initialization:

{
  chainId: number,        // e.g. 84532 (Base Sepolia), 1 (Ethereum), 8453 (Base)
  rpcUrl: string,         // Optional; overrides RPC_URL env var
  privateKey: string,     // Optional; overrides PRIVATE_KEY env var
  ipfs: 'pinata',         // Pinata as IPFS provider
  pinataJwt: string,      // Optional; overrides PINATA_JWT env var
}

External Connections:

• EVM JSON-RPC (Ethereum, Base, Arbitrum, Polygon, Optimism, Avalanche, Celo, Gnosis, Linea, Mantle, MegaETH, Scroll, Taiko, Monad, BSC, and testnets).
• Pinata IPFS (for registration file pinning).
• Endpoint services: MCP (Model Context Protocol), A2A (Agent2Agent), ENS (Ethereum Name Service), agentWallet addresses, OASF taxonomy endpoints.

Agent Registration File Structure (JSON, hosted at agentURI):

{
  "type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
  "name": "MyAgent",
  "description": "What it does, pricing, interaction methods",
  "image": "https://example.com/agent.png",
  "services": [
    { "name": "MCP", "endpoint": "https://mcp.example.com", "version": "2025-06-18", "mcpTools": ["tool1"] },
    { "name": "A2A", "endpoint": "https://example.com/.well-known/agent-card.json", "version": "0.3.0" },
    { "name": "OASF", "endpoint": "https://github.com/agntcy/oasf/", "version": "v0.8.0",
      "skills": ["natural_language_processing/summarization"],
      "domains": ["finance_and_business/investment_services"] },
    { "name": "ENS", "endpoint": "myagent.eth", "version": "v1" },
    { "name": "agentWallet", "endpoint": "eip155:8453:0x..." }
  ],
  "registrations": [
    { "agentId": 42, "agentRegistry": "eip155:84532:0x8004A818BFB912233c491871b3d84c89A494BD9e" }
  ],
  "supportedTrust": ["reputation", "crypto-economic", "tee-attestation"],
  "active": true,
  "x402Support": true
}

Procedure

1. Install and Initialize Agent0 SDK

Input: npm package manager, Node.js 16+, agent0-sdk npm package

Steps:

npm install agent0-sdk

Create SDK instance with chain and signer:

import { SDK } from 'agent0-sdk';

const sdk = new SDK({
  chainId: 84532,  // Base Sepolia for testing
  rpcUrl: process.env.RPC_URL,
  privateKey: process.env.PRIVATE_KEY,
  ipfs: 'pinata',
  pinataJwt: process.env.PINATA_JWT,
});

Output: SDK instance ready for agent creation, search, and feedback operations.

---

2. Create and Configure an Agent Object

Input: SDK instance, agent name (string), description (string), image URL (string)

Steps:

const agent = sdk.createAgent(
  'MyAgent',
  'An AI agent that analyzes crypto markets',
  'https://example.com/agent-image.png'
);

Configure MCP endpoint (if available):

await agent.setMCP(
  'https://mcp.example.com',  // MCP server URL
  '2025-06-18',               // MCP version
  true                        // auto-fetch tools from introspection
);

Configure A2A endpoint (if using Agent2Agent):

await agent.setA2A(
  'https://example.com/.well-known/agent-card.json',  // AgentCard URL
  '0.3.0',                                             // A2A version
  true                                                 // auto-fetch on registration
);

Configure ENS (optional):

agent.setENS('myagent.eth');

Set active status, x402 support, and trust model:

agent.setActive(true);
agent.setX402Support(true);  // Coinbase x402 HTTP payment protocol
agent.setTrust(true, false, false);  // reputation=true, crypto-economic=false, tee-attestation=false

Add OASF taxonomy skills and domains (use slash-separated paths):

agent.addSkill('natural_language_processing/natural_language_generation/summarization', true);
agent.addDomain('finance_and_business/investment_services', true);

Output: Fully configured agent object with endpoints, trust model, and taxonomy metadata.

---

3. Register Agent On-Chain (IPFS)

Input: Configured agent object, PRIVATE_KEY env var, PINATA_JWT env var, account with sufficient ETH for gas

Steps:

const tx = await agent.registerIPFS();

This transaction:

• Mints an ERC-721 NFT on the Identity Registry (agentId = tokenId).
• Uploads registration file to IPFS via Pinata.
• Sets agentURI to IPFS hash.
• Creates cryptographic link between on-chain NFT and off-chain registration file.

Wait for confirmation:

const { result } = await tx.waitConfirmed();
console.log(`Registered: ${result.agentId}`);  // e.g. "84532:42"

Output: Confirmed transaction receipt, agentId (numeric tokenId), agentRegistry string (eip155:chainId:contractAddress), IPFS hash of registration file.

---

4. Register Agent On-Chain (HTTPS)

Input: Configured agent object, PRIVATE_KEY env var, account with sufficient ETH for gas, HTTPS URL where registration file is already hosted

Steps (alternative to step 3 if no PINATA_JWT):

const httpsUrl = 'https://example.com/agents/myagent-registration.json';
const tx = await agent.registerHTTPS(httpsUrl);
const { result } = await tx.waitConfirmed();

The registration file must include the registrations field pointing back to the on-chain NFT to enable domain verification via /.well-known/agent-registration.json.

Output: Confirmed transaction receipt, agentId, agentRegistry, HTTPS URL.

---

5. Search for Agents by Capability

Input: SDK instance (no signer needed), optional chainId override

Steps:

const sdk = new SDK({ chainId: 84532, rpcUrl: process.env.RPC_URL });

const agents = await sdk.searchAgents({
  hasMCP: true,              // Must have MCP endpoint
  active: true,              // Must be marked active
  x402support: true,         // Must support x402 payments
  mcpTools: ['financial_analyzer'],  // Must expose this tool
  supportedTrust: ['reputation'],    // Must accept reputation feedback
});

Returns array of matching agents with agentId, name, description, endpoints.

Output: Array of agent objects matching search criteria.

---

6. Retrieve a Specific Agent

Input: SDK instance, agentId string (format: "chainId:tokenId")

Steps:

const agent = await sdk.getAgent('84532:42');
console.log(agent.name);
console.log(agent.services);
console.log(agent.supportedTrust);

Fetches on-chain metadata (NFT owner, registration file URI) and resolves registration file from IPFS/HTTPS.

Output: Agent object with complete metadata (name, description, image, services array, supported trust models, active status, x402 support).

---

7. Perform Semantic Search

Input: SDK instance, keyword string

Steps:

const results = await sdk.searchAgents(
  { keyword: 'crypto market analysis' },  // Natural language query
  { sort: ['semanticScore:desc'] }        // Sort by relevance descending
);

Uses embedding-based semantic search across agent descriptions and OASF taxonomy.

Output: Ranked array of agents by semantic relevance score.

---

8. Submit Feedback (Reputation)

Input: SDK instance, agentId string, feedback value (int, 0-100 or custom range), tag1 (reputation signal type), PRIVATE_KEY env var, account with sufficient ETH for gas

Steps (simple feedback):

const tx = await sdk.giveFeedback(
  '84532:42',   // agentId
  85,           // value: quality score 85/100
  'starred',    // tag1: reputation signal type
  '',           // tag2: optional second signal
  '',           // tag3: optional third signal
  undefined     // feedbackFile: optional off-chain details
);
await tx.waitConfirmed();

Steps (with off-chain feedback file):

const feedbackFile = await sdk.prepareFeedbackFile({
  text: 'Accurate market analysis, responded in <1s',
  capability: 'tools',
  name: 'financial_analyzer',
  proofOfPayment: {
    txHash: '0x...',
    chainId: '8453',
    fromAddress: '0x...',
    toAddress: '0x...'  // Agent's wallet
  },
});

const tx = await sdk.giveFeedback('84532:42', 85, 'starred', '', '', feedbackFile);
await tx.waitConfirmed();

Feedback values use fixed-point encoding: value (int128) + valueDecimals (uint8):

• starred (quality 0-100): value=85, valueDecimals=0
• uptime (% as 9977 for 99.77%): value=9977, valueDecimals=2
• responseTime (ms): value=560, valueDecimals=0
• reachable (binary): value=1, valueDecimals=0
• successRate (%): value=89, valueDecimals=0

Output: Confirmed transaction receipt, feedback index (counter incremented for this caller + agent pair).

---

9. Read Agent Reputation Summary

Input: SDK instance, agentId string, optional clientAddresses array (trusted reviewers)

Steps:

const summary = await sdk.getReputationSummary('84532:42');
console.log(`Average: ${summary.averageValue}`);
console.log(`Count: ${summary.count}`);
console.log(`Feedback by tag:`, summary.byTag);  // Breakdown by signal type

With trusted reviewer filter:

const summary = await sdk.getReputationSummary('84532:42', {
  clientAddresses: ['0xAlice', '0xBob', '0xCharlie']  // Only these reviewers count
});

Output: Reputation summary object with averageValue, count, byTag breakdown, lastUpdated timestamp.

---

10. Verify Agent Registration Domain

Input: Agent endpoint domain (e.g. https://example.com), agentId string

Steps:

// Agent publishes registration file at https://example.com/.well-known/agent-registration.json
// This file must contain the agent's agentId and agentRegistry pointing back to on-chain NFT
const isVerified = await sdk.verifyAgentDomain('https://example.com', '84532:42');

Creates bidirectional cryptographic link: NFT points to registration file, registration file points back to NFT.

Output: Boolean, true if domain ownership is verified.

---

11. Query Contract Addresses by Chain

Input: chainId (number)

Steps:

const contracts = sdk.getContractAddresses(84532);  // Base Sepolia
console.log(contracts.identity);    // Identity Registry address
console.log(contracts.reputation);  // Reputation Registry address
console.log(contracts.validation);  // Validation Registry address

Output: Object with identity, reputation, validation contract addresses (deterministic CREATE2 vanity addresses).

---

Decision Points

If PRIVATE_KEY is not set

Branch: Read-only mode.

• Cannot call agent.registerIPFS(), agent.registerHTTPS(), or sdk.giveFeedback().
• Can call sdk.getAgent(), sdk.searchAgents(), sdk.getReputationSummary().
• Recommendation: Set PRIVATE_KEY only in secure environments (CI/CD secrets, hardware wallet, or scoped signer services).

If PINATA_JWT is not set

Branch: HTTPS-only registration.

• Cannot use agent.registerIPFS().
• Must use agent.registerHTTPS() and host registration file on own domain.
• Registration file must include registrations field for domain verification.
• Recommendation: Set PINATA_JWT for production to ensure redundant IPFS pinning.

If RPC_URL is not set

Branch: Fallback to public endpoints.

• SDK will use public Infura or Alchemy endpoints.
• May hit rate limits on high-traffic chains.
• Recommendation: Set RPC_URL to private endpoint for production.

If getReputationSummary() is called without clientAddresses

Branch: Aggregate all feedback without Sybil filtering.

• Returns average across all reviewers (including potential duplicates or bad actors).
• Use clientAddresses parameter to filter to trusted reviewers only.
• Self-feedback is always rejected server-side (agent owner/operators cannot submit feedback on their own agent).

If agent search returns empty result set

Branch: No matching agents.

• Adjust search filters (relax hasMCP requirement, remove mcpTools filter, broaden supportedTrust).
• Perform semantic search instead if keyword query is too specific.
• Check that agents are marked active: true in registration file.

If registerIPFS() or giveFeedback() transaction fails

Branch: Error handling by error type.

• Insufficient gas: Increase gasPrice, reduce network congestion, check account ETH balance.
• PRIVATE_KEY invalid or missing: Verify env var is set, 0x-prefixed, 64 hex characters.
• Account not owner of agent: Only agent's ERC-721 token owner can call feedback on self (though self-feedback is rejected on-chain).
• Pinata upload failure: Check PINATA_JWT is valid and not expired, network connectivity to api.pinata.cloud.
• RPC timeout: Increase timeout on SDK init, use faster RPC endpoint, retry with backoff.

---

Output Contract

**Agent Registration (