{"_id":"8004sdk","name":"8004sdk","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"8004sdk","version":"1.0.0","description":"Ready to plug 8004 agents","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.mts","default":"./dist/index.mjs"},"require":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"./express":{"import":{"types":"./dist/adapters/express.d.mts","default":"./dist/adapters/express.mjs"},"require":{"types":"./dist/adapters/express.d.ts","default":"./dist/adapters/express.js"}},"./hono":{"import":{"types":"./dist/adapters/hono.d.mts","default":"./dist/adapters/hono.mjs"},"require":{"types":"./dist/adapters/hono.d.ts","default":"./dist/adapters/hono.js"}}},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run --exclude test/integration/**","test:watch":"vitest --exclude test/integration/**","test:integration":"vitest run test/integration","test:e2e":"node test-e2e.js","test:all":"npm run test && npm run test:integration && npm run test:e2e","example:express":"tsx examples/express.ts","example:hono":"tsx examples/hono.ts"},"license":"MIT","author":{"name":"fzn0x"},"homepage":"https://github.com/fzn0x/8004sdk","repository":{"type":"git","url":"git+https://github.com/fzn0x/8004sdk.git"},"devDependencies":{"@hono/node-server":"^1.19.9","@types/base-64":"^1.0.2","@types/express":"^4.17.25","@types/node":"^25.3.0","dotenv":"^17.3.1","express":"^4.18.0","hono":"^4.0.0","tsup":"^8.0.0","tsx":"^4.21.0","typescript":"^5.0.0","vitest":"^4.0.18"},"dependencies":{"base-64":"^1.0.0","viem":"^2.46.3"},"_id":"8004sdk@1.0.0","gitHead":"c7f979ed79ff39ab91d978b2f120db7b41766e08","bugs":{"url":"https://github.com/fzn0x/8004sdk/issues"},"_nodeVersion":"22.19.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-HbCpSpDEgP7bbB4s8rWOIBDu9q8Exs2vbZi2oRbpgUz5nDVSFwcgOqneOt1B3hfzWc0pB3QHr7LbYhlqs6QWyg==","shasum":"a7d2a68125a311699a94dbff63798801d03ed32f","tarball":"https://registry.npmjs.org/8004sdk/-/8004sdk-1.0.0.tgz","fileCount":23,"unpackedSize":98422,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCcVebq5Lbc5vDxegTp25GaeZrCg2RdeoYTd4lBlYUQGAIhAOVcrvHWM6Z4YfToAQwLzPnDCrb6qyK+PwZNY5ZQ2e2J"}]},"_npmUser":{"name":"developerfauzan","email":"developerfauzan@gmail.com"},"directories":{},"maintainers":[{"name":"developerfauzan","email":"developerfauzan@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/8004sdk_1.0.0_1772096943755_0.1929931577805375"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-26T09:09:03.754Z","1.0.0":"2026-02-26T09:09:03.896Z","modified":"2026-02-26T09:09:04.063Z"},"maintainers":[{"name":"developerfauzan","email":"developerfauzan@gmail.com"}],"description":"Ready to plug 8004 agents","homepage":"https://github.com/fzn0x/8004sdk","repository":{"type":"git","url":"git+https://github.com/fzn0x/8004sdk.git"},"author":{"name":"fzn0x"},"bugs":{"url":"https://github.com/fzn0x/8004sdk/issues"},"license":"MIT","readme":"# 8004sdk\r\n\r\nA 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.\r\n\r\n## Features\r\n\r\n- **Standard Compliant:** Adheres directly to the draft [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) standard for Agent discovery and interaction.\r\n- **Framework Adapters:** Out-of-the-box routing configurations for `Express` and `Hono`.\r\n- **Chain Agnostic:** Native support for Mainnets and Testnets across Ethereum, Base, Abstract, Arbitrum, Avalanche, Celo, Linea, Optimism, Polygon, and more.\r\n- **Typescript Native:** Built with `viem` to ensure end-to-end type safety.\r\n- **Lightweight:** No heavy dependencies, just `viem`.\r\n- **Tested:** Using vitest for unit and integration testing.\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install 8004sdk\r\n```\r\n\r\n## Quick Start\r\n\r\n### 1. Generating an Agent Identity\r\n\r\nEnsure you have your environment variables set\r\n\r\n```typescript\r\nimport { createAgentIdentity, generateAgentRegistration, generateAgentCard, REGISTRIES } from '8004sdk';\r\nimport 'dotenv/config';\r\n\r\nconst chainId = 'base-sepolia'; // You can pass numbers (84532) or standard aliases like 'base', 'ethereum', 'polygon', etc.\r\n\r\nconsole.log(`Identity Registry bounds: ${REGISTRIES[chainId].IdentityRegistry}`);\r\n\r\nconst identity = await createAgentIdentity({\r\n  rpcUrl: 'https://sepolia.base.org',\r\n  chainId,\r\n  privateKey: process.env.AGENT_PRIVATE_KEY, \r\n  autoRegister: true, // Auto-registers on-chain if not already holding an NFT\r\n  agentURI: \"https://my-agent.com/.well-known/agent-registration.json\" // add offchain agent uri\r\n});\r\n\r\nconst registration = await generateAgentRegistration(identity, {\r\n  name: \"My AI Agent\",\r\n  description: \"An ERC-8004 compliant intelligent agent\",\r\n  services: [\r\n    { name: \"A2A\", endpoint: \"https://my-agent.com/.well-known/agent-card.json\" } // change to your agent's endpoint\r\n  ],\r\n  supportedTrust: [\"reputation\"]\r\n});\r\n\r\nconst agentCard = generateAgentCard({\r\n  name: \"My AI Agent\",\r\n  description: \"An ERC-8004 compliant intelligent agent\",\r\n  url: \"https://my-agent.com/\"\r\n});\r\n\r\nconsole.log(registration); \r\n```\r\n\r\n### 2. Serving Agent Metadata (Express)\r\n\r\nAutomatically serve your agent registration details to the required `.well-known` endpoints:\r\n\r\n```typescript\r\nimport express from 'express';\r\n// Note the modular import!\r\nimport { injectAgentRoutes } from '8004sdk/express'; \r\n\r\nconst app = express();\r\n\r\ninjectAgentRoutes(app, registration, agentCard);\r\n\r\napp.listen(3000, () => {\r\n    console.log('Serving agent details on http://localhost:3000/.well-known/agent-card.json');\r\n});\r\n```\r\n\r\n### 3. Serving Agent Metadata (Hono)\r\n\r\nIf you're deploying on edge environments like Cloudflare Workers with Hono:\r\n\r\n```typescript\r\nimport { Hono } from 'hono';\r\n// Note the modular import!\r\nimport { injectAgentRoutes } from '8004sdk/hono'; \r\n\r\nconst app = new Hono();\r\n\r\ninjectAgentRoutes(app, registration, agentCard);\r\n\r\nexport default app;\r\n```\r\n\r\n## API Reference\r\n\r\n### `createAgentIdentity(options: CreateAgentIdentityOptions): Promise<AgentIdentity>`\r\n\r\nCreates 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.\r\n\r\n**Parameters (`CreateAgentIdentityOptions`)**:\r\n- `rpcUrl` (string): HTTP endpoint for the Ethereum execution node.\r\n- `chainId` (number): The EIP-155 Chain ID you are deploying to (e.g., `84532` for Base Sepolia).\r\n- `privateKey` (string): (Optional) The `0x` prefixed hexadecimal private key used to derive the `walletAddress`. Required if `autoRegister` is `true`.\r\n- `autoRegister` (boolean): (Optional) If `true`, the SDK will build, sign, and broadcast an on-chain `register` transaction to the target `IdentityRegistry`. Default is `false`.\r\n- `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.\r\n\r\n**Returns (`AgentIdentity`)**: \r\n- Returns the strictly mapped `agentId`, `agentRegistry`, `walletAddress`, and `chainId`. \r\n\r\n### `generateAgentRegistration(identity: AgentIdentity, metadata: GenerateRegistrationOptions): Promise<RegistrationFile>`\r\n\r\nFormat mapped identity and registration metadata into the rigid JSON structure expected by the ERC-8004 specification for identity payloads (`agent-registration.json`).\r\n\r\n**Parameters**:\r\n- `identity` (`AgentIdentity`): The identity instance generated by `createAgentIdentity`.\r\n- `metadata` (`GenerateRegistrationOptions`): An object containing descriptive properties (like `name`, `description`, `image`, `services`, `x402Support`, `supportedTrust`). `name` and `description` are strictly required.\r\n\r\n**Returns (`RegistrationFile`)**: \r\n- A JSON-compatible object adhering to the EIP-8004 draft format for Identity Mapping payloads.\r\n\r\n### `generateAgentCard(metadata: GenerateAgentCardOptions): AgentCard`\r\n\r\nFormat operational agent capability configurations into the rigid structure expected by the ERC-8004 specification for agent card payloads (`agent-card.json`).\r\n\r\n**Parameters**:\r\n- `metadata` (`GenerateAgentCardOptions`): An object specifying operational endpoints like `skills`, `entrypoints`, `payments`, `supportedInterfaces`, and capabilities (`streaming`, `pushNotifications`). `name` is required.\r\n\r\n**Returns (`AgentCard`)**: \r\n- A JSON-compatible object adhering to the standard EIP-8004 format for Protocol Endpoints payloads.\r\n\r\n### `injectAgentRoutes(app: Express | Hono, registration: RegistrationFile, agentCard: AgentCard)`\r\n\r\nMounts the static generated instances strictly to their respective standardized URL route constraints (`/.well-known/...`) gracefully via dependency injection. \r\n\r\n**Parameters**:\r\n- `app`: Your backend application instance. You MUST import the matching specific adapter: `8004sdk/express` or `8004sdk/hono`.\r\n- `registration`: the payload returned by `generateAgentRegistration()` \r\n- `agentCard`: the payload returned by `generateAgentCard()` \r\n\r\n## Structure\r\n\r\nThe configuration serves the `AgentRegistration` payload simultaneously on the following standardized endpoints during server initialization:\r\n\r\n- `/.well-known/agent-registration.json`\r\n- `/.well-known/agent-card.json`\r\n- `/.well-known/agent.json`\r\n\r\n## Examples\r\nSee the `/examples` directory for runnable examples.\r\n\r\n```bash\r\nnpm run example:express\r\nnpm run example:hono\r\n```\r\n\r\n## Support\r\n\r\nIf you need help or encounter issues while using the 8004sdk, please don't hesitate to reach out on github issues.\r\n\r\n## QnA\r\n\r\nIs there any validation registry support?\r\n\r\n> 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.\r\n\r\nIs there any x402 support?\r\n\r\n> 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.\r\n\r\nIs there any differences between agent-card.json and agent.json?\r\n\r\n> No, they are the same. agent.json is just a symlink to agent-card.json.\r\n\r\nIs there any differences between 8004sdk and other libraries?\r\n\r\n> 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.\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n","readmeFilename":"README.md","_rev":"1-1fdfed38320cfe0e0f67f5a8e38b127b"}