erc8004

The ERC-8004 package provides on-chain agent identity, discovery, and reputation. It enables agents to register on-chain as ERC-721 NFTs, store metadata on IPFS, and build reputation through feedback.

Installation

bun add @regent/erc8004 viem

Overview

ERC-8004 is an Ethereum standard for on-chain agent registry:

Agent Identity: Agents are represented as ERC-721 NFTs with off-chain metadata
Metadata Storage: Agent capabilities stored on IPFS (Pinata, Filecoin, or local node)
Discovery: Subgraph indexing for searching agents across chains
Reputation: On-chain feedback system for agent reputation
Multi-Chain: Support for Ethereum, Base, Polygon, and other EVM chains

Quick Start

import { SDK } from '@regent/erc8004';

// Initialize SDK
const sdk = new SDK({
  chainId: 84532,  // Base Sepolia
  rpcUrl: 'https://sepolia.base.org',
  signer: process.env.PRIVATE_KEY,
  ipfs: 'pinata',
  pinataJwt: process.env.PINATA_JWT,
});

// Create and register an agent
const agent = sdk.createAgent('My Agent', 'An intelligent assistant');
await agent.setMCP('https://mcp.example.com');
await agent.setA2A('https://a2a.example.com/agent.json');
agent.setTrust(true, false, false);  // Enable reputation trust model
agent.addSkill('natural_language_processing/summarization');

const registration = await agent.registerIPFS();
console.log('Registered:', registration.agentId);  // e.g., "84532:42"

SDK Configuration

SDKConfig

interface SDKConfig {
  chainId: ChainId;
  rpcUrl: string;
  signer?: string;  // Private key (optional for read-only)

  // Registry overrides
  registryOverrides?: Record<ChainId, Record<string, Address>>;

  // IPFS configuration
  ipfs?: 'node' | 'filecoinPin' | 'pinata';
  ipfsNodeUrl?: string;
  filecoinPrivateKey?: string;
  pinataJwt?: string;

  // Subgraph configuration
  subgraphUrl?: string;
  subgraphOverrides?: Record<ChainId, string>;
}

Initialization Examples

Full configuration:

const sdk = new SDK({
  chainId: 84532,
  rpcUrl: 'https://sepolia.base.org',
  signer: process.env.PRIVATE_KEY,
  ipfs: 'pinata',
  pinataJwt: process.env.PINATA_JWT,
  subgraphUrl: 'https://subgraph.example.com',
});

Read-only mode:

const sdk = new SDK({
  chainId: 84532,
  rpcUrl: 'https://sepolia.base.org',
  // No signer = read-only mode
});

console.log(sdk.isReadOnly);  // true

Custom registries:

const sdk = new SDK({
  chainId: 84532,
  rpcUrl: 'https://sepolia.base.org',
  registryOverrides: {
    84532: {
      IDENTITY: '0x1234...',
      REPUTATION: '0x5678...',
      VALIDATION: '0x9abc...',
    },
  },
});

SDK Methods

Agent Lifecycle

// Create new agent in memory
const agent = sdk.createAgent(name: string, description: string, image?: string);

// Load existing registered agent
const agent = await sdk.loadAgent(agentId: string);

// Get agent summary from subgraph
const summary = await sdk.getAgentById(agentId: string);

// Transfer agent ownership
const { txHash, from, to } = await sdk.transferAgent(agentId, newOwner);

Search & Discovery

// Search agents with filters
const results = await sdk.searchAgents(
  params?: SearchParams,
  sort?: string[],
  pageSize?: number,
  cursor?: string
);

// Search by reputation
const results = await sdk.searchAgentsByReputation({
  tags: ['quality'],
  minAverageScore: 80,
  capabilities: ['tools'],
});

Feedback & Reputation

// Prepare feedback
const feedback = sdk.prepareFeedback(agentId, {
  score: 90,
  tags: ['quality', 'speed'],
  text: 'Excellent service!',
  capability: 'tools',
  name: 'web_search',
});

// Submit feedback on-chain
const result = await sdk.giveFeedback(agentId, feedback);

// Get reputation summary
const summary = await sdk.getReputationSummary(agentId, tag1?, tag2?);
// Returns: { count: number, averageScore: number }

Registry Access

const identityRegistry = sdk.getIdentityRegistry();
const reputationRegistry = sdk.getReputationRegistry();
const validationRegistry = sdk.getValidationRegistry();
const subgraph = sdk.getSubgraphClient(chainId?);
const addresses = sdk.registries();
const chainId = await sdk.chainId();

Agent Class

Creating an Agent

const agent = sdk.createAgent('My Agent', 'Description', 'https://image.url');

Agent Properties

agent.agentId       // AgentId after registration (e.g., "84532:42")
agent.agentURI      // IPFS URI after registration
agent.name          // Agent name
agent.description   // Agent description
agent.image         // Agent image URL
agent.mcpEndpoint   // MCP endpoint URL
agent.a2aEndpoint   // A2A endpoint URL
agent.ensEndpoint   // ENS name
agent.walletAddress // Agent wallet address

Setting Endpoints

// MCP endpoint (auto-fetches capabilities if autoFetch=true)
await agent.setMCP('https://mcp.example.com', '2025-06-18', true);

// A2A endpoint (auto-fetches skills)
await agent.setA2A('https://example.com/agent.json', '0.30', true);

// ENS name
agent.setENS('myagent.eth');

OASF Skills and Domains

// Add skills (Open Agent Skills Framework)
agent.addSkill('natural_language_processing/summarization');
agent.addSkill('data_analysis/visualization');

// Remove skill
agent.removeSkill('data_analysis/visualization');

// Add domains
agent.addDomain('technology/artificial_intelligence');

Trust Models

// Enable trust models
agent.setTrust(
  reputation: boolean,       // On-chain feedback
  cryptoEconomic: boolean,   // Economic stake
  teeAttestation: boolean    // TEE verification
);

// Example: reputation only
agent.setTrust(true, false, false);

Agent Wallet

// Set agent's operational wallet
agent.setAgentWallet('0x1234...', 84532);  // address, chainId

Registration

// Register with IPFS metadata storage
const registration = await agent.registerIPFS();

// Register with HTTP metadata storage
const registration = await agent.registerHTTP('https://example.com/metadata.json');

Registration File

interface RegistrationFile {
  agentId?: string;
  agentURI?: string;
  name: string;
  description: string;
  image?: string;
  walletAddress?: string;
  walletChainId?: number;
  endpoints: Endpoint[];
  trustModels: string[];
  owners: string[];
  operators: string[];
  active: boolean;
  x402support: boolean;
  metadata: Record<string, any>;
  updatedAt: number;
}

IPFS Client

Configuration

import { IPFSClient } from '@regent/erc8004';

const ipfs = new IPFSClient({
  url: 'http://localhost:5001',       // Local IPFS node
  // OR
  pinataEnabled: true,
  pinataJwt: process.env.PINATA_JWT,
  // OR
  filecoinPinEnabled: true,
  filecoinPrivateKey: process.env.FILECOIN_KEY,
});

Methods

// Add JSON data
const cid = await ipfs.addJson({ key: 'value' });

// Get JSON data
const data = await ipfs.getJson(cid);

// Add registration file
const cid = await ipfs.addRegistrationFile(file, chainId, registryAddress);

// Add feedback
const cid = await ipfs.addFeedback(feedback);

Subgraph Client

Configuration

import { SubgraphClient } from '@regent/erc8004';

const subgraph = new SubgraphClient('https://subgraph.example.com');

Methods

// Get agents with filters
const agents = await subgraph.getAgents({
  where: { active: true },
  first: 50,
  orderBy: 'createdAt',
  orderDirection: 'desc',
});

// Get agent by ID
const agent = await subgraph.getAgentById('84532:42');

// Search agents
const agents = await subgraph.searchAgents({
  mcp: true,
  a2a: true,
  supportedTrust: ['reputation'],
});

// Search by reputation
const agents = await subgraph.searchAgentsByReputation({
  minAverageScore: 80,
  tags: ['quality'],
});

// Search feedback
const feedback = await subgraph.searchFeedback({
  agents: ['84532:42'],
  minScore: 70,
});

Search Parameters

interface SearchParams {
  chains?: number[] | 'all';
  owners?: string[];
  mcp?: boolean;
  a2a?: boolean;
  oasfSkills?: string[];
  oasfDomains?: string[];
  supportedTrust?: ('reputation' | 'crypto-economic' | 'tee-attestation')[];
  active?: boolean;
  x402support?: boolean;
}

Feedback Manager

Giving Feedback

import { FeedbackManager } from '@regent/erc8004';

// Prepare feedback data
const feedbackFile = sdk.prepareFeedback('84532:42', {
  score: 85,              // 0-100
  tags: ['quality', 'speed'],
  text: 'Great service!',
  capability: 'tools',    // 'prompts' | 'resources' | 'tools' | 'completions'
  name: 'web_search',     // Tool/resource/prompt name
  skill: 'search',        // A2A skill name
  task: 'task-123',       // Task identifier
  context: { requestId: 'abc' },
  proofOfPayment: { txHash: '0x...' },
});

// Submit on-chain
const feedback = await sdk.giveFeedback('84532:42', feedbackFile);

Reading Feedback

// Get specific feedback
const feedback = await sdk.getFeedback(agentId, clientAddress, feedbackIndex);

// Search feedback
const results = await sdk.searchFeedback({
  agents: ['84532:42'],
  tags: ['quality'],
  minScore: 70,
});

Responding to Feedback

// Agent responds to feedback
await sdk.appendResponse(agentId, clientAddress, feedbackIndex, {
  text: 'Thank you for your feedback!',
});

// Revoke feedback (only feedback giver can do this)
await sdk.revokeFeedback(agentId, feedbackIndex);

Endpoint Crawler

Automatically extract capabilities from MCP and A2A endpoints:

import { EndpointCrawler } from '@regent/erc8004';

const crawler = new EndpointCrawler(5000);  // 5 second timeout

// Crawl MCP endpoint
const mcpCaps = await crawler.fetchMcpCapabilities('https://mcp.example.com');
// Returns: { mcpTools: string[], mcpPrompts: string[], mcpResources: string[] }

// Crawl A2A endpoint
const a2aCaps = await crawler.fetchA2aCapabilities('https://example.com/agent.json');
// Returns: { a2aSkills: string[] }

Multi-Chain Support

Agent Indexer

Search across multiple chains:

import { AgentIndexer } from '@regent/erc8004';

const indexer = new AgentIndexer({
  defaultChainId: 84532,
  subgraphUrls: {
    84532: 'https://subgraph.base-sepolia.example.com',
    11155111: 'https://subgraph.sepolia.example.com',
  },
});

// Search all chains
const results = await indexer.searchAgents(
  { mcp: true },
  ['averageScore:desc'],
  50,
  undefined,
  'all'
);

console.log(`Found ${results.items.length} agents`);
console.log(`Successful chains: ${results.meta.successfulChains}`);
console.log(`Failed chains: ${results.meta.failedChains}`);

Supported Chains

The SDK supports any EVM chain. Common chains:

Chain

Chain ID

Ethereum Mainnet

Ethereum Sepolia

11155111

Base Mainnet

8453

Base Sepolia

84532

Polygon Mainnet

137

Polygon Amoy

80002

Arbitrum One

42161

Optimism

Agent ID Format

Agent IDs are formatted as chainId:tokenId:

const agentId = '84532:42';  // Base Sepolia, token ID 42

Endpoint Types

enum EndpointType {
  MCP = 'MCP',          // Model Context Protocol
  A2A = 'A2A',          // Agent-to-Agent
  ENS = 'ENS',          // Ethereum Name Service
  DID = 'DID',          // Decentralized Identifier
  WALLET = 'wallet',    // Agent wallet (eip155:chainId:address)
  OASF = 'OASF',        // Open Agent Skills Framework
}

Trust Models

enum TrustModel {
  REPUTATION = 'reputation',           // On-chain feedback
  CRYPTO_ECONOMIC = 'crypto-economic', // Economic stake
  TEE_ATTESTATION = 'tee-attestation', // TEE verification
}

Complete Example

import { SDK } from '@regent/erc8004';

async function main() {
  // Initialize SDK
  const sdk = new SDK({
    chainId: 84532,
    rpcUrl: 'https://sepolia.base.org',
    signer: process.env.PRIVATE_KEY,
    ipfs: 'pinata',
    pinataJwt: process.env.PINATA_JWT,
  });

  // Create agent
  const agent = sdk.createAgent(
    'Trading Advisor',
    'AI-powered trading recommendations',
    'https://example.com/logo.png'
  );

  // Configure endpoints
  await agent.setMCP('https://trading-advisor.com/mcp', '2025-06-18', true);
  await agent.setA2A('https://trading-advisor.com/.well-known/agent.json');

  // Configure trust
  agent.setTrust(true, false, false);

  // Add OASF skills
  agent.addSkill('financial_analysis/trading_recommendations');
  agent.addSkill('data_analysis/market_analysis');

  // Enable x402 payments
  agent.setX402Support(true);

  // Register on-chain
  const registration = await agent.registerIPFS();
  console.log('Agent ID:', registration.agentId);
  console.log('Agent URI:', registration.agentURI);

  // Search for similar agents
  const similar = await sdk.searchAgents({
    oasfSkills: ['financial_analysis'],
    supportedTrust: ['reputation'],
  });

  console.log(`Found ${similar.items.length} similar agents`);

  // Get reputation
  const reputation = await sdk.getReputationSummary(registration.agentId!);
  console.log(`Reputation: ${reputation.averageScore}/100 (${reputation.count} reviews)`);
}

main();

Exports

// Main SDK
export { SDK } from '@regent/erc8004';

// Core classes
export { Agent, Web3Client, IPFSClient, SubgraphClient } from '@regent/erc8004';
export { FeedbackManager, EndpointCrawler, AgentIndexer } from '@regent/erc8004';

// Types
export type {
  SDKConfig,
  RegistrationFile,
  AgentSummary,
  Feedback,
  Endpoint,
  EndpointType,
  TrustModel,
  SearchParams,
  McpCapabilities,
  A2aCapabilities,
} from '@regent/erc8004';

Previouscore Nextexpress

Last updated 2 months ago

Good night

hashtagInstallation

hashtagOverview

hashtagQuick Start

hashtagSDK Configuration

hashtagSDKConfig

hashtagInitialization Examples

hashtagSDK Methods

hashtagAgent Lifecycle

hashtagSearch & Discovery

hashtagFeedback & Reputation

hashtagRegistry Access

hashtagAgent Class

hashtagCreating an Agent

hashtagAgent Properties

hashtagSetting Endpoints

hashtagOASF Skills and Domains

hashtagTrust Models

hashtagAgent Wallet

hashtagRegistration

hashtagRegistration File

hashtagIPFS Client

hashtagConfiguration

hashtagMethods

hashtagSubgraph Client

hashtagConfiguration

hashtagMethods

hashtagSearch Parameters

hashtagFeedback Manager

hashtagGiving Feedback

hashtagReading Feedback

hashtagResponding to Feedback

hashtagEndpoint Crawler

hashtagMulti-Chain Support

hashtagAgent Indexer

hashtagSupported Chains

hashtagAgent ID Format

hashtagEndpoint Types

hashtagTrust Models

hashtagComplete Example

hashtagExports

Installation

Overview

Quick Start

SDK Configuration

SDKConfig

Initialization Examples

SDK Methods

Agent Lifecycle

Search & Discovery

Feedback & Reputation

Registry Access

Agent Class

Creating an Agent

Agent Properties

Setting Endpoints

OASF Skills and Domains

Trust Models

Agent Wallet

Registration

Registration File

IPFS Client

Configuration

Methods

Subgraph Client

Configuration

Methods

Search Parameters

Feedback Manager

Giving Feedback

Reading Feedback

Responding to Feedback

Endpoint Crawler

Multi-Chain Support

Agent Indexer

Supported Chains

Agent ID Format

Endpoint Types

Trust Models

Complete Example

Exports