ERC-8004 identity (external wallet)

Register the agent on the ERC-8004 Identity Registry using your signer. Use numeric chainId (e.g. 11155111 for Sepolia), not string network names. Supported values are listed in ERC-8004 agent identity.

Requirements

Requirement	Details
Address match	`evmAddress` on create must equal the account that signs the registry tx
Gas	That account needs native token on the target `chainId`
Backend	IdentityRegistry must be configured for your `chainId` on Agent Kit
Credentials	No `accessKey` or `organizationId` — do not use `registerAgentIdentity()` (server-only)

Option A — `registerAgentIdentityExternal` (recommended)

import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { sepolia } from 'viem/chains';

const { agent } = await agentKit.createAgent({
  wallet: 'external',
  evmAddress: process.env.DEV_EVM_ADDRESS!,
  name: 'My Agent',
  description: 'AI agent with external wallet',
  userIdentity: '[email protected]',
});

const { registration } = await agentKit.registerAgentIdentityExternal({
  agentId: agent.id,
  evmAddress: process.env.DEV_EVM_ADDRESS!,
  chainId: 11155111,
  signTransaction: async ({ prepare, fromAddress }) => {
    const account = privateKeyToAccount(
      process.env.DEV_PRIVATE_KEY as `0x${string}`,
    );
    const walletClient = createWalletClient({
      account,
      chain: sepolia,
      transport: http(prepare.rpcUrl),
    });
    return walletClient.sendTransaction({
      account: fromAddress,
      chain: sepolia,
      to: prepare.registerCall.to as `0x${string}`,
      data: prepare.registerCall.data,
      value: BigInt(prepare.registerCall.value || '0'),
    });
  },
});

console.log(registration.agentIdentity);
// eip155:11155111:0x8004A818BFB912233c491871b3d84c89A494BD9e:42

signTransaction receives:

prepare — registerCall (to, data, value), rpcUrl, agentURI, chainId, identityRegistry
fromAddress — checksummed 0x address (must match agent evmAddress)

It must return the transaction hash (0x…).

Option B — Manual prepare / confirm

For MetaMask popups or custom UX between steps:

const prepare = await agentKit.prepareAgentIdentity(agent.id, {
  chainId: 11155111,
  services: [
    {
      name: 'agent-kit',
      endpoint: 'https://api.example.com/agents/registration',
      version: '1.0',
    },
  ],
});

// Sign prepare.registerCall with your wallet (viem, ethers, MetaMask, etc.)
const txHash = '0x…' as `0x${string}`;

const { registration } = await agentKit.confirmAgentIdentity(agent.id, {
  chainId: 11155111,
  txHash,
});

Read registration

const identity = await agentKit.getAgentIdentity(agent.id, 11155111);
console.log(identity.registration?.agentIdentity);

Public registration file (no API key):

GET {AGENT_KIT_PUBLIC_URL}/agent/{agentId}/registration

FAQ

Can I use MetaMask instead of a private key in signTransaction? Yes. Use prepareAgentIdentity + your wallet provider to sign prepare.registerCall, then confirmAgentIdentity with the returned txHash. Or wrap that logic inside signTransaction for registerAgentIdentityExternal. Who pays gas for ERC-8004 registration? The signing account pays gas for the registry transaction on the target chain.

External wallet overview — optional Privy, MetaMask, WalletConnect, and viem guide links
ERC-8004 agent identity — supported chainIds and registry addresses
External wallet API reference

​Requirements

​Option A — registerAgentIdentityExternal (recommended)

​Option B — Manual prepare / confirm

​Read registration

​FAQ

​Related

Requirements

Option A — `registerAgentIdentityExternal` (recommended)

Option B — Manual prepare / confirm

Read registration

FAQ

Related