Guides

This guide covers integrating ERC-8004 on-chain agent identity, discovery, and reputation into your Regent agent.

Overview

ERC-8004 provides:

On-chain Identity: Register your agent on the blockchain with a unique ID
Agent Discovery: Search for agents by capabilities, skills, and reputation
Reputation System: Feedback and ratings for agent performance
IPFS Metadata: Store agent details on IPFS with on-chain references

Quick Start

Option 1: Using the Unified SDK

import { createRegentAgent } from 'regent-sdk';

const agent = await createRegentAgent({
  name: 'My Agent',
  description: 'An intelligent assistant',
  version: '1.0.0',

  // ERC-8004 Identity configuration
  identity: {
    chainId: 84532, // Base Sepolia
    rpcUrl: process.env.RPC_URL!,
    ipfs: 'pinata',
    ipfsConfig: {
      pinataJwt: process.env.PINATA_JWT,
    },
  },

  // Wallet for signing transactions
  wallet: {
    privateKey: process.env.PRIVATE_KEY,
  },

  // Discovery configuration
  discovery: {
    mcpEndpoint: 'https://myagent.com/mcp',
    a2aEndpoint: 'https://myagent.com/.well-known/agent-card.json',
    oasfSkills: ['code_generation', 'data_analysis'],
    oasfDomains: ['software_development'],
  },

  // Trust model
  trust: {
    reputation: true,
    cryptoEconomic: false,
    teeAttestation: false,
  },
});

// Register on-chain
const { agentId } = await agent.registerOnchain();
console.log('Registered agent:', agentId);

Option 2: Using the ERC-8004 SDK Directly

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

const sdk = new SDK({
  chainId: 84532,
  rpcUrl: process.env.RPC_URL!,
  signer: process.env.PRIVATE_KEY,
  ipfs: 'pinata',
  pinataJwt: process.env.PINATA_JWT,
});

// Create and configure agent
const agent = sdk.createAgent(
  'My Agent',
  'An intelligent assistant',
  'https://example.com/logo.png'
);

// Set capabilities
await agent.setMCP('https://myagent.com/mcp', '2025-06-18');
await agent.setA2A('https://myagent.com/a2a.json', '0.30');
agent.setENS('myagent.eth');
agent.setActive(true);

// Configure trust model
agent.setTrust(true, false, false); // reputation, cryptoEconomic, teeAttestation

// Register on IPFS and blockchain
const result = await agent.registerIPFS();
console.log('Agent ID:', result.agentId);
console.log('IPFS URI:', result.agentURI);

Supported Chains

Chain

Chain ID

Status

Ethereum Mainnet

Supported

Sepolia

11155111

Supported

Base

8453

Supported

Base Sepolia

84532

Recommended for testing

Arbitrum One

42161

Supported

Polygon

137

Supported

Optimism

Supported

Agent Registration

Basic Registration

const agent = sdk.createAgent('Name', 'Description', 'https://logo.url');
const result = await agent.registerIPFS();

With HTTP URI (No IPFS)

const agent = sdk.createAgent('Name', 'Description', 'https://logo.url');
await agent.registerHTTP('https://myserver.com/agent-metadata.json');

Registration Fields

// Required
agent.name          // Agent name
agent.description   // Agent description

// Optional endpoints
await agent.setMCP(endpoint, version);    // MCP server endpoint
await agent.setA2A(endpoint, version);    // A2A agent card endpoint

// Optional identity
agent.setENS('myagent.eth', '1.0');       // ENS domain
agent.setAgentWallet(address, chainId);   // Payment wallet

// Configuration
agent.setActive(true);                    // Active status
agent.setX402Support(true);               // x402 payment support
agent.setTrust(reputation, crypto, tee);  // Trust models

// Custom metadata
agent.setMetadata({
  category: 'assistant',
  languages: ['en', 'es'],
});

Agent Discovery

Search by Capabilities

// Find agents with MCP endpoints
const mcpAgents = await sdk.searchAgents({ mcp: true });

// Find agents by skill
const coders = await sdk.searchAgents({
  a2aSkills: ['code_generation']
});

// Find agents by name
const assistants = await sdk.searchAgents({
  name: 'assistant'
});

// Combined filters
const results = await sdk.searchAgents({
  mcp: true,
  a2aSkills: ['data_analysis'],
  active: true,
});

Search by Reputation

const topRated = await sdk.searchAgentsByReputation(
  undefined,  // specific agents
  ['helpful'], // tags
  undefined,  // reviewers
  ['code_generation'], // capabilities
  ['python'], // skills
  undefined,  // tasks
  undefined,  // names
  80          // minimum average score
);

Pagination

// First page
const page1 = await sdk.searchAgents({ active: true }, undefined, 10);

// Next page
if (page1.nextCursor) {
  const page2 = await sdk.searchAgents(
    { active: true },
    undefined,
    10,
    page1.nextCursor
  );
}

Load Full Agent Data

// Get summary from search
const summary = await sdk.getAgent('84532:123');

// Load full agent with methods
const agent = await sdk.loadAgent('84532:123');
console.log(agent.name);
console.log(agent.mcpEndpoint);

Reputation & Feedback

Submitting Feedback

Feedback requires authorization from the agent owner:

// Agent owner signs authorization
const agentSdk = new SDK({
  chainId, rpcUrl,
  signer: agentPrivateKey,
  ipfs: 'pinata',
  pinataJwt,
});

const auth = await agentSdk.signFeedbackAuth(
  agentId,
  clientAddress,
  undefined, // expiresAt (optional)
  24         // hours valid
);

// Client submits feedback
const clientSdk = new SDK({
  chainId, rpcUrl,
  signer: clientPrivateKey,
  ipfs: 'pinata',
  pinataJwt,
});

const feedback = clientSdk.prepareFeedback(
  agentId,
  85,                    // score (0-100)
  ['helpful', 'fast'],   // tags
  'Great experience!',   // text (optional)
  'code_generation',     // capability
  undefined,             // name
  'python',              // skill
  undefined,             // task
  { context: 'enterprise' } // metadata
);

await clientSdk.giveFeedback(agentId, feedback, auth);

Querying Feedback

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

// Search feedback
const results = await sdk.searchFeedback(
  agentId,
  ['helpful'],           // tags
  ['code_generation'],   // capabilities
  ['python'],            // skills
  70,                    // minScore
  100                    // maxScore
);

Agent Response to Feedback

await agentSdk.appendResponse(
  agentId,
  clientAddress,
  feedbackIndex,
  {
    uri: 'ipfs://Qm...',
    hash: '0x...',
  }
);

IPFS Configuration

Pinata (Recommended)

const sdk = new SDK({
  chainId: 84532,
  rpcUrl,
  ipfs: 'pinata',
  pinataJwt: process.env.PINATA_JWT,
});

Get your JWT at pinata.cloud.

Local IPFS Node

const sdk = new SDK({
  chainId: 84532,
  rpcUrl,
  ipfs: 'node',
  ipfsNodeUrl: 'http://localhost:5001',
});

Filecoin Pin

const sdk = new SDK({
  chainId: 84532,
  rpcUrl,
  ipfs: 'filecoinPin',
  filecoinPrivateKey: process.env.FILECOIN_KEY,
});

Multi-Chain Support

Query Agents Across Chains

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

const indexer = new AgentIndexer();

// Get all agents from multiple chains
const agents = await indexer.getAllAgents([84532, 11155111, 8453]);

// Search with chain filter
const baseAgents = await indexer.searchAgents({
  chainId: 8453,
  mcp: true,
});

Agent Transfer

// Transfer ownership
const result = await agent.transfer('0xNewOwnerAddress');
console.log('Transfer TX:', result.txHash);

// Or via SDK
await sdk.transferAgent(agentId, '0xNewOwnerAddress');

Environment Variables

# Required
CHAIN_ID=84532
RPC_URL=https://base-sepolia.g.alchemy.com/v2/YOUR_KEY

# For registration (one required)
PRIVATE_KEY=0x...
# or
WALLET_PRIVATE_KEY=0x...

# For IPFS (choose one)
IPFS_PROVIDER=pinata
PINATA_JWT=your_jwt
# or
IPFS_PROVIDER=node
IPFS_NODE_URL=http://localhost:5001

# Optional
SUBGRAPH_URL=https://api.thegraph.com/subgraphs/name/...

Environment-Based Setup

import {
  createRegentSDKConfigFromEnv,
  createRegentSDK
} from 'regent-sdk';

// Automatically reads from process.env
const config = createRegentSDKConfigFromEnv();
const sdk = createRegentSDK(config);

// With overrides
const config = createRegentSDKConfigFromEnv(process.env, {
  chainId: 8453, // Override chain
});

Error Handling

try {
  const result = await agent.registerIPFS();
} catch (error) {
  if (error.message.includes('insufficient funds')) {
    console.error('Need ETH for gas fees');
  } else if (error.message.includes('pinataJwt')) {
    console.error('Invalid or missing Pinata JWT');
  } else {
    throw error;
  }
}

Best Practices

Use testnet first: Start with Base Sepolia (84532) before mainnet
Cache agent cards: Use agentCardTtlMs option to reduce RPC calls
Batch operations: Use pagination for large result sets
Secure keys: Never commit private keys; use environment variables
Monitor gas: Registration and feedback require ETH for gas

PreviousWallet NextPayment testing

Last updated 1 month ago

Good afternoon

hashtagOverview

hashtagQuick Start

hashtagOption 1: Using the Unified SDK

hashtagOption 2: Using the ERC-8004 SDK Directly

hashtagSupported Chains

hashtagAgent Registration

hashtagBasic Registration

hashtagWith HTTP URI (No IPFS)

hashtagRegistration Fields

hashtagAgent Discovery

hashtagSearch by Capabilities

hashtagSearch by Reputation

hashtagPagination

hashtagLoad Full Agent Data

hashtagReputation & Feedback

hashtagSubmitting Feedback

hashtagQuerying Feedback

hashtagAgent Response to Feedback

hashtagIPFS Configuration

hashtagPinata (Recommended)

hashtagLocal IPFS Node

hashtagFilecoin Pin

hashtagMulti-Chain Support

hashtagQuery Agents Across Chains

hashtagAgent Transfer

hashtagEnvironment Variables

hashtagEnvironment-Based Setup

hashtagError Handling

hashtagBest Practices

hashtagRelated Resources

Overview

Quick Start

Option 1: Using the Unified SDK

Option 2: Using the ERC-8004 SDK Directly

Supported Chains

Agent Registration

Basic Registration

With HTTP URI (No IPFS)

Registration Fields

Agent Discovery

Search by Capabilities

Search by Reputation

Pagination

Load Full Agent Data

Reputation & Feedback

Submitting Feedback

Querying Feedback

Agent Response to Feedback

IPFS Configuration

Pinata (Recommended)

Local IPFS Node

Filecoin Pin

Multi-Chain Support

Query Agents Across Chains

Agent Transfer

Environment Variables

Environment-Based Setup

Error Handling

Best Practices

Related Resources