How to Register Your AI Agent with ERC-8004

You've heard about ERC-8004 and understand why on-chain identity matters for AI agents. Now it's time for the practical part: actually registering your agent. This guide walks you through the entire process, from generating keys to earning your first attestations.

Prerequisites

Before we start, make sure you have:

• An Ethereum wallet with some ETH for gas fees
• Node.js 18+ installed on your machine
• An AI agent (or at least the concept of one you're building)
• Basic familiarity with Ethereum transactions

Don't worry if you're not a Solidity expert—you won't need to write any smart contracts. We'll interact with the existing ERC-8004 registry.

Step 1: Generate Your Agent's Keys

Every AI agent needs its own Ethereum address. This address becomes the agent's permanent identity, so we'll generate a fresh keypair specifically for the agent.

Using ethers.js:

import { Wallet } from 'ethers';
// Generate a new random wallet for the agent
const agentWallet = Wallet.createRandom();
console.log('Agent Address:', agentWallet.address);
console.log('Private Key:', agentWallet.privateKey);
// IMPORTANT: Store the private key securely!
// Your agent will need this to sign transactions

Step 2: Prepare Your Agent Metadata

ERC-8004 stores minimal data on-chain to keep gas costs low. Detailed information about your agent lives off-chain, referenced by a URI. This metadata follows a standard schema.

Create a JSON file describing your agent:

{
  "name": "TradingBot Alpha",
  "description": "An autonomous trading agent specialized in DEX arbitrage opportunities across Ethereum L2s.",
  "version": "1.0.0",
  "operator": {
    "name": "Acme AI Labs",
    "website": "https://acmeai.example",
    "contact": "agents@acmeai.example"
  },
  "capabilities": [
    "defi-trading",
    "cross-chain-bridging",
    "gas-optimization"
  ],
  "protocols": [
    "uniswap-v3",
    "aave-v3",
    "across-bridge"
  ],
  "security": {
    "audited": false,
    "bugBounty": null,
    "sourceCode": "https://github.com/acmeai/tradingbot-alpha"
  },
  "compliance": {
    "jurisdictions": ["US", "EU"],
    "restrictions": ["No sanctioned addresses"]
  },
  "image": "ipfs://Qm..."
}

This metadata helps other protocols and users understand what your agent does and who's behind it.

Step 3: Upload Metadata to IPFS

The metadata needs to be stored somewhere permanent and content-addressable. IPFS is the standard choice.

Using Pinata (popular IPFS pinning service):

import axios from 'axios';
const metadata = {
  // ... your metadata object from above
};
const response = await axios.post(
  'https://api.pinata.cloud/pinning/pinJSONToIPFS',
  metadata,
  {
    headers: {
      'Authorization': Bearer ${PINATA_JWT},
      'Content-Type': 'application/json'
    }
  }
);
const metadataURI = ipfs://${response.data.IpfsHash};
console.log('Metadata URI:', metadataURI);

Alternatively, you can use:

• web3.storage (free IPFS/Filecoin storage)
• Arweave (permanent storage, one-time payment)
• NFT.storage (free for NFT-related data)

Step 4: Register on the ERC-8004 Registry

Now for the main event: calling the registration function on the ERC-8004 registry contract.

import { ethers } from 'ethers';
// Connect to Ethereum (mainnet or testnet)
const provider = new ethers.JsonRpcProvider(RPC_URL);
const operatorWallet = new ethers.Wallet(OPERATOR_PRIVATE_KEY, provider);
// ERC-8004 Registry contract
const REGISTRY_ADDRESS = '0x...'; // Official registry address
const REGISTRY_ABI = [
  'function register(address agent, string memory metadataURI) external payable',
  'function registrationFee() external view returns (uint256)',
  'event AgentRegistered(address indexed agent, address indexed operator, string metadataURI)'
];
const registry = new ethers.Contract(REGISTRY_ADDRESS, REGISTRY_ABI, operatorWallet);
// Check registration fee
const fee = await registry.registrationFee();
console.log('Registration fee:', ethers.formatEther(fee), 'ETH');
// Register the agent
const tx = await registry.register(
  agentWallet.address,  // The agent's address
  metadataURI,          // IPFS URI from step 3
  { value: fee }        // Pay registration fee
);
console.log('Transaction submitted:', tx.hash);
const receipt = await tx.wait();
console.log('Agent registered! Block:', receipt.blockNumber);

Once the transaction confirms, your agent officially exists on the ERC-8004 registry.

Step 5: Verify Registration

Let's confirm everything worked:

const REGISTRY_VIEW_ABI = [
  'function isRegistered(address agent) external view returns (bool)',
  'function getAgent(address agent) external view returns (tuple(address operator, string metadataURI, uint256 registeredAt, uint8 status))'
];
const registryRead = new ethers.Contract(REGISTRY_ADDRESS, REGISTRY_VIEW_ABI, provider);
// Check registration status
const isRegistered = await registryRead.isRegistered(agentWallet.address);
console.log('Is registered:', isRegistered); // Should be true
// Get full agent info
const agentInfo = await registryRead.getAgent(agentWallet.address);
console.log('Agent info:', {
  operator: agentInfo.operator,
  metadataURI: agentInfo.metadataURI,
  registeredAt: new Date(Number(agentInfo.registeredAt)  1000),
  status: agentInfo.status // 0 = Active
});

// In your agent's code
const agentSigner = new ethers.Wallet(AGENT_PRIVATE_KEY, provider);
// When interacting with ERC-8004 aware protocols,
// use the agent's wallet to prove identity
async function executeWithIdentity(targetContract, functionData) {
  // The agent signs and sends the transaction
  // Receiving protocol can verify agent's ERC-8004 registration
  const tx = await agentSigner.sendTransaction({
    to: targetContract,
    data: functionData
  });
  return tx;
}

// Claim your agent's capabilities
const attestation = {
  subject: agentWallet.address,
  type: 'capability',
  data: {
    capabilities: ['defi-trading', 'gas-optimization'],
    maxTransactionSize: '10 ETH',
    operatingSince: '2025-01-01'
  },
  issuedAt: Date.now()
};
// Sign with operator wallet (EIP-712)
const signature = await operatorWallet.signTypedData(
  EIP712_DOMAIN,
  ATTESTATION_TYPES,
  attestation
);

// Example: After completing trades on a DEX
// The DEX can attest to your agent's track record
const dexAttestation = {
  subject: agentWallet.address,
  type: 'behavior',
  issuer: '0xDEX_ADDRESS',
  data: {
    totalTrades: 150,
    successRate: 0.99,
    totalVolume: '500 ETH',
    period: '2025-Q1'
  }
};

const UPDATE_ABI = [
  'function updateMetadata(address agent, string memory newURI) external'
];
const registryWrite = new ethers.Contract(REGISTRY_ADDRESS, UPDATE_ABI, operatorWallet);
// Upload new metadata to IPFS first
const newMetadataURI = 'ipfs://QmNewHash...';
// Update on-chain reference
await registryWrite.updateMetadata(agentWallet.address, newMetadataURI);