npm package: 8004sdk
Description: Ready to plug 8004 agents
Author: fzn0x
Latest version: 1.0.0

# 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](https://eips.ethereum.org/EIPS/eip-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

```bash
npm install 8004sdk
```

## Quick Start

### 1. Generating an Agent Identity

Ensure you have your environment variables set

```typescript
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:

```typescript
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:

```typescript
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.

```bash
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](LICENSE) file for details.