Lucid Agents Docs

These examples exercise the draft ERC-8004 identity and reputation clients. Registration and writes consume gas and may be irreversible. Start with lookup only; enable registration in a deliberate deployment step.

Prerequisites

bun add @lucid-agents/core @lucid-agents/identity @lucid-agents/wallet viem

AGENT_DOMAIN=my-agent.example.com
RPC_URL=https://your-base-sepolia-rpc.example
CHAIN_ID=84532
DEVELOPER_WALLET_PRIVATE_KEY=0x...
IDENTITY_AUTO_REGISTER=false

The examples also accept an agent wallet as a compatibility fallback, but a dedicated developer/operator wallet makes the on-chain authority clearer.

Resolve an existing identity

identity-lookup.ts

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

const runtime = await createAgent({
  name: 'lookup-agent',
  version: '1.0.0',
})
  .use(wallets({ config: walletsFromEnv() }))
  .build();

const result = await createAgentIdentity({
  runtime,
  domain: process.env.AGENT_DOMAIN,
  rpcUrl: process.env.RPC_URL,
  chainId: Number(process.env.CHAIN_ID),
  autoRegister: false,
});

if (!result.record) {
  console.log('No existing identity:', result.status);
  process.exit(0);
}

console.log({
  agentId: result.record.agentId.toString(),
  owner: result.record.owner,
  agentURI: result.record.agentURI,
});

Check record, not only status: bootstrap can warn and let an agent continue without identity when RPC/client setup fails.

Register in an explicit step

After validating the chain, official registry addresses, domain, wallet, and gas balance:

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

if (process.env.CONFIRM_IDENTITY_WRITE !== 'yes') {
  throw new Error('Set CONFIRM_IDENTITY_WRITE=yes after reviewing the write');
}

const registration = await registerAgent({
  runtime,
  domain: process.env.AGENT_DOMAIN,
  rpcUrl: process.env.RPC_URL,
  chainId: Number(process.env.CHAIN_ID),
  agentURI:
    `https://${process.env.AGENT_DOMAIN}` +
    '/.well-known/agent-registration.json',
});

if (!registration.record) {
  throw new Error(`Registration failed: ${registration.status}`);
}

console.log({
  didRegister: registration.didRegister,
  transactionHash: registration.transactionHash,
  agentId: registration.record.agentId.toString(),
});

registerAgent() forces auto-registration when the record is missing. Reusing the same domain does not replace the need to verify the current owner and URI.

Generate discovery documents

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

const options = {
  name: 'Research Agent',
  description: 'Finds and synthesizes primary sources',
  selectedServices: ['A2A', 'web', 'OASF'] as ('A2A' | 'web' | 'OASF')[],
  x402Support: true,
  oasf: {
    authors: ['ops@my-agent.example.com'],
    skills: ['research'],
    domains: ['knowledge'],
    modules: ['https://my-agent.example.com/modules/core'],
    locators: ['https://my-agent.example.com/.well-known/oasf-record.json'],
  },
};

const registrationDocument = generateAgentRegistration(registration, options);
const oasfDocument = generateOASFRecord(registration, options, runtime);

Host the first document at the exact agentURI stored on-chain. If OASF is enabled, host the second at the configured locator. The HTTP identity extension can generate these documents from live runtime entrypoints.

Read identity and reputation

const clients = registration.clients;
if (!clients) {
  throw new Error('Registry clients were not created; inspect RPC warnings');
}

const current = await clients.identity.get(registration.record.agentId);
const summary = await clients.reputation.getSummary(
  registration.record.agentId
);

console.log(current?.owner, summary.count, summary.value);

Writes such as setMetadata(), identity transfers, approvals, and giveFeedback() require the configured wallet account. Make each write idempotent at the application/workflow level and record its transaction hash.

Validation is not part of the default example

registration.clients contains identity and reputation clients. It does not contain a validation client by default. Validation is under active development; the package only retains a manual createValidationRegistryClient() export for backward compatibility.

Do not use older examples that assume identity.clients.validation is always defined. Pin and audit the draft plus deployed validation contract before testing that compatibility client.

Repository examples

The repository includes:

quick-start.ts for lookup/registration bootstrap;
full-integration.ts for identity and reputation operations, with deprecated validation guarded;
test-clients.ts for client/RPC diagnostics.

Run them only against a funded test wallet and a reviewed test deployment:

bun run packages/examples/src/identity/quick-start.ts

For configuration, deployment addresses, OASF, security, and error handling, use the complete @lucid-agents/identity reference.

Identity examples