Lucid Agents Docs

The identity extension adds ERC-8004 on-chain identity support, enabling verifiable agent identity, domain proofs, and reputation tracking.

Installation

bun add @lucid-agents/identity viem

Basic usage

import { createAgent } from '@lucid-agents/core';
import { http } from '@lucid-agents/http';
import { wallets, walletsFromEnv } from '@lucid-agents/wallet';
import { identity, identityFromEnv } from '@lucid-agents/identity';

const agent = await createAgent({
  name: 'my-agent',
  version: '1.0.0',
})
  .use(http())
  .use(wallets({ config: walletsFromEnv() }))
  .use(identity({ config: identityFromEnv() }))
  .build();

Configuration

Environment variables

# Identity registry contract address
IDENTITY_REGISTRY_ADDRESS=0x...

# Agent's domain for identity binding
AGENT_DOMAIN=my-agent.example.com

# Auto-register identity if not exists
IDENTITY_AUTO_REGISTER=true

identityFromEnv()

Loads configuration from environment variables:

import { identityFromEnv } from '@lucid-agents/identity';

const config = identityFromEnv();

IdentityConfig

type IdentityConfig = {
  trust?: TrustConfig;
  domain?: string;
  autoRegister?: boolean;
  rpcUrl?: string;
  chainId?: number;
};

API reference

identity(options)

Creates the identity extension.

function identity(options: {
  config: IdentityConfig;
}): Extension<IdentityExtensionContext>

Requirements:

The wallets() extension must be added before identity()
An agent wallet is required for signing identity proofs

createAgentIdentity()

Bootstrap function for creating and registering agent identity:

import { createAgentIdentity } from '@lucid-agents/identity';

const identity = await createAgentIdentity({
  runtime: agent,
  domain: 'my-agent.example.com',
  autoRegister: true,  // Register on-chain if not exists
});

Host your registration file

After registration, host the ERC-8004 registration file at:

https://my-agent.example.com/.well-known/agent-registration.json

You can generate the file with the helper:

import { generateAgentRegistration } from '@lucid-agents/identity';

const registration = generateAgentRegistration(identity, {
  name: 'My Agent',
  description: 'An intelligent assistant',
  services: [
    {
      name: 'A2A',
      endpoint: 'https://my-agent.example.com/.well-known/agent-card.json',
    },
  ],
});

TrustConfig helpers

createAgentIdentity returns an object that includes trust (if available) and optional clients. Use getTrustConfig to normalize the trust configuration for manifests and adapters:

import { createAgentIdentity, getTrustConfig } from '@lucid-agents/identity';

const identity = await createAgentIdentity({ runtime: agent, autoRegister: true });
const trustConfig = getTrustConfig(identity);

ERC-8004 overview

ERC-8004 is a standard for on-chain agent identity:

Registry: Smart contract storing agent registrations
Domain binding: Prove ownership of a domain
Reputation: Track agent reputation feedback and scores
Trust models: Define trust relationships

Registration entry

type RegistrationEntry = {
  agentId: number | string;
  agentRegistry: string; // CAIP-10: namespace:chainId:address
  agentAddress?: string; // optional legacy owner address (CAIP-10)
  signature?: string;
};

Agent registration file

type AgentRegistration = {
  type: 'https://eips.ethereum.org/EIPS/eip-8004#registration-v1';
  name: string;
  description?: string;
  image?: string;
  domain?: string;
  url?: string;
  owner?: string;
  services?: Array<{
    name: string;
    endpoint: string;
    version?: string;
    description?: string;
  }>;
  registrations?: RegistrationEntry[];
  supportedTrust?: TrustModel[];
};

Trust models

type TrustModel = {
  id: string;
  name: string;
  description?: string;
  verificationMethod: 'domain' | 'registry' | 'signature';
};

Domain proofs

Prove ownership of a domain by signing a challenge:

// Server generates challenge
const challenge = await identity.createDomainChallenge('my-agent.example.com');

// Agent signs challenge with wallet
const proof = await agent.identity.signDomainProof(challenge);

// Server verifies proof
const isValid = await identity.verifyDomainProof(proof, 'my-agent.example.com');

Manifest integration

Identity information is included in the Agent Card:

{
  "name": "my-agent",
  "registrations": [
    {
      "agentId": "1",
      "agentRegistry": "eip155:84532:0xregistry",
      "agentAddress": "eip155:84532:0xowner"
    }
  ],
  "trustModels": ["feedback", "inference-validation"],
  "ValidationRequestsURI": "https://my-agent.example.com/validation/request",
  "ValidationResponsesURI": "https://my-agent.example.com/validation/response"
}

Registry operations

Identity registry client

import { createIdentityRegistryClient } from '@lucid-agents/identity';

const registry = createIdentityRegistryClient({
  address: '0x...',
  chainId: 84532,
  publicClient,  // viem public client
  walletClient,  // viem wallet client (required for writes)
});

// Lookup agent by ID
const agent = await registry.get(1n);
const metadata = await registry.getMetadata(1n, 'version');

// Register new agent
await registry.register({
  agentURI: 'https://my-agent.example.com/.well-known/agent-registration.json',
});

Reputation registry client

import { createReputationRegistryClient } from '@lucid-agents/identity';

const reputation = createReputationRegistryClient({
  address: '0x...',
  chainId: 84532,
  publicClient,
  walletClient,
});

// Get agent reputation
const summary = await reputation.getSummary(1n);
const score =
  summary.valueDecimals === 0
    ? Number(summary.value)
    : Number(summary.value) / 10 ** summary.valueDecimals;

// Submit feedback
await reputation.giveFeedback({
  toAgentId: 1n,
  value: 5,
  valueDecimals: 0,
  tag1: 'quality',
  tag2: 'speed',
});

Exports

// Extension
export { identity } from '@lucid-agents/identity';

// Configuration
export { identityFromEnv } from '@lucid-agents/identity';

// Bootstrap
export { createAgentIdentity } from '@lucid-agents/identity';

// Registry clients
export {
  createIdentityRegistryClient,
  createReputationRegistryClient,
  createValidationRegistryClient,
} from '@lucid-agents/identity';

// Manifest integration
export { createAgentCardWithIdentity } from '@lucid-agents/identity';

// Types
export type {
  IdentityConfig,
  IdentityRuntime,
  RegistrationEntry,
  TrustModel,
} from '@lucid-agents/identity';

@lucid-agents/identity

On this page