8004sdk

8004sdk

A robust, developer-friendly TypeScript SDK for generating and registering ERC-8004 compliant agent identities. Seamlessly interact with 8004 registries and inject AgentCard metadata into modern web frameworks.

Features

• Standard Compliant: Adheres directly to the draft ERC-8004 standard for Agent discovery and interaction.
• Framework Adapters: Out-of-the-box routing configurations for Express and Hono.
• Chain Agnostic: Native support for Mainnets and Testnets across Ethereum, Base, Abstract, Arbitrum, Avalanche, Celo, Linea, Optimism, Polygon, and more.
• Typescript Native: Built with viem to ensure end-to-end type safety.
• Lightweight: No heavy dependencies, just viem.
• Tested: Using vitest for unit and integration testing.

Installation

npm install 8004sdk

Quick Start

1. Generating an Agent Identity

Ensure you have your environment variables set

import { createAgentIdentity, generateAgentRegistration, generateAgentCard, REGISTRIES } from '8004sdk';
import 'dotenv/config';

const chainId = 'base-sepolia'; // You can pass numbers (84532) or standard aliases like 'base', 'ethereum', 'polygon', etc.

console.log(`Identity Registry bounds: ${REGISTRIES[chainId].IdentityRegistry}`);

const identity = await createAgentIdentity({
  rpcUrl: 'https://sepolia.base.org',
  chainId,
  privateKey: process.env.AGENT_PRIVATE_KEY, 
  autoRegister: true, // Auto-registers on-chain if not already holding an NFT
  agentURI: "https://my-agent.com/.well-known/agent-registration.json" // add offchain agent uri
});

const registration = await generateAgentRegistration(identity, {
  name: "My AI Agent",
  description: "An ERC-8004 compliant intelligent agent",
  services: [
    { name: "A2A", endpoint: "https://my-agent.com/.well-known/agent-card.json" } // change to your agent's endpoint
  ],
  supportedTrust: ["reputation"]
});

const agentCard = generateAgentCard({
  name: "My AI Agent",
  description: "An ERC-8004 compliant intelligent agent",
  url: "https://my-agent.com/"
});

console.log(registration); 

2. Serving Agent Metadata (Express)

Automatically serve your agent registration details to the required .well-known endpoints:

import express from 'express';
// Note the modular import!
import { injectAgentRoutes } from '8004sdk/express'; 

const app = express();

injectAgentRoutes(app, registration, agentCard);

app.listen(3000, () => {
    console.log('Serving agent details on http://localhost:3000/.well-known/agent-card.json');
});

3. Serving Agent Metadata (Hono)

If you're deploying on edge environments like Cloudflare Workers with Hono:

import { Hono } from 'hono';
// Note the modular import!
import { injectAgentRoutes } from '8004sdk/hono'; 

const app = new Hono();

injectAgentRoutes(app, registration, agentCard);

export default app;

API Reference

createAgentIdentity(options: CreateAgentIdentityOptions): Promise<AgentIdentity>

Creates a new internal agent identity mapping, extracting wallet addresses directly from the provided private keys, handling determinism, and (optionally) executing the register() method on the Identity Registry.

Parameters (CreateAgentIdentityOptions):

• rpcUrl (string): HTTP endpoint for the Ethereum execution node.
• chainId (number): The EIP-155 Chain ID you are deploying to (e.g., 84532 for Base Sepolia).
• privateKey (string): (Optional) The 0x prefixed hexadecimal private key used to derive the walletAddress. Required if autoRegister is true.
• autoRegister (boolean): (Optional) If true, the SDK will build, sign, and broadcast an on-chain register transaction to the target IdentityRegistry. Default is false.
• agentURI (string): (Optional) A URL to your off-chain agent-registration.json. Will be passed into the register(string agentURI) smart contract call if supplied.

Returns (AgentIdentity):

• Returns the strictly mapped agentId, agentRegistry, walletAddress, and chainId.

generateAgentRegistration(identity: AgentIdentity, metadata: GenerateRegistrationOptions): Promise<RegistrationFile>

Format mapped identity and registration metadata into the rigid JSON structure expected by the ERC-8004 specification for identity payloads (agent-registration.json).

Parameters:

• identity (AgentIdentity): The identity instance generated by createAgentIdentity.
• metadata (GenerateRegistrationOptions): An object containing descriptive properties (like name, description, image, services, x402Support, supportedTrust). name and description are strictly required.

Returns (RegistrationFile):

• A JSON-compatible object adhering to the EIP-8004 draft format for Identity Mapping payloads.

generateAgentCard(metadata: GenerateAgentCardOptions): AgentCard

Format operational agent capability configurations into the rigid structure expected by the ERC-8004 specification for agent card payloads (agent-card.json).

Parameters:

• metadata (GenerateAgentCardOptions): An object specifying operational endpoints like skills, entrypoints, payments, supportedInterfaces, and capabilities (streaming, pushNotifications). name is required.

Returns (AgentCard):

• A JSON-compatible object adhering to the standard EIP-8004 format for Protocol Endpoints payloads.

injectAgentRoutes(app: Express | Hono, registration: RegistrationFile, agentCard: AgentCard)

Mounts the static generated instances strictly to their respective standardized URL route constraints (/.well-known/...) gracefully via dependency injection.

Parameters:

• app: Your backend application instance. You MUST import the matching specific adapter: 8004sdk/express or 8004sdk/hono.
• registration: the payload returned by generateAgentRegistration()
• agentCard: the payload returned by generateAgentCard()

Structure

The configuration serves the AgentRegistration payload simultaneously on the following standardized endpoints during server initialization:

• /.well-known/agent-registration.json
• /.well-known/agent-card.json
• /.well-known/agent.json

Examples

See the /examples directory for runnable examples.

npm run example:express
npm run example:hono

Support

If you need help or encounter issues while using the 8004sdk, please don't hesitate to reach out on github issues.

QnA

Is there any validation registry support?

Right now, we don't have validation registry support because EIP 8004 Validation Registry is still under active update and discussion with the TEE community. But I'm planning to add it in the future.

Is there any x402 support?

No, we don't have embeded x402 support right now. But I'm planning to add it in the future. Check https://github.com/fzn0x/x402sdk for x402 support.

Is there any differences between agent-card.json and agent.json?

No, they are the same. agent.json is just a symlink to agent-card.json.

Is there any differences between 8004sdk and other libraries?

Yes, 8004sdk is a lightweight library that is specifically designed for ERC-8004. It is not a full-featured framework, but it is a good starting point for building ERC-8004 compliant agents. It is also open source and free to use.

License

This project is licensed under the MIT License - see the LICENSE file for details.