create-8004-agent

CLI tool to scaffold ERC-8004 compliant AI agents with A2A, MCP, and x402 payment support.

Supports both EVM chains and Solana.

- What is ERC-8004?
- Prerequisites
- Quick Start
- What Gets Generated
- Wizard Options
- Supported Chains
- Generated Project Usage
- 1. Configure Environment
- 2. Register Agent On-Chain
- 3. Updating Your Agent
- 4. Start Your Servers
- A2A, x402, and MCP Protocols
- Troubleshooting
- Development
- Resources

What is ERC-8004?

ERC-8004 is a protocol for discovering and trusting AI agents across organizational boundaries. It provides:

- Identity Registry - On-chain agent registration as NFTs
- Reputation Registry - Feedback and trust signals
- Validation Registry - Stake-secured verification

Prerequisites

Before using the generator, ensure you have:
- Node.js: Version 18.0.0 or higher.
- Package Manager: npm, pnpm, or bun.
- Wallet: An EVM or Solana wallet (the tool can generate one for you if needed).

Quick Start

``bash npx create-8004-agent`

That's it! The wizard will guide you through creating your agent.

`What Gets Generated`

The wizard creates a complete agent project with:

`my-agent/ ├── package.json ├── .env.example ├── registration.json # ERC-8004 metadata ├── tsconfig.json ├── src/ │ ├── register.ts # On-chain registration script │ ├── agent.ts # LLM agent (OpenAI) │ ├── a2a-server.ts # A2A protocol server (optional) │ ├── mcp-server.ts # MCP protocol server (optional) │ └── tools.ts # MCP tools (optional) └── .well-known/ └── agent-card.json # A2A discovery card`

`Wizard Options`

| Option | Description | | --------------------- | -------------------------------------------------------------------------------------------------------------- | | Project directory | Where to create the project | | Agent name | Your agent's name | | Agent description | What your agent does | | Agent image | URL to your agent's image/logo | | Agent wallet | EVM or Solana address (leave empty to auto-generate) | | A2A server | Enable agent-to-agent communication | | A2A streaming | Enable Server-Sent Events (SSE) for streaming responses | | MCP server | Enable Model Context Protocol tools | | x402 payments | x402 USDC micropayments (Base, Polygon) | | Chain | EVM: Ethereum, Base, Polygon, Monad (mainnet + testnets) / Solana: Devnet | | Trust models | reputation, crypto-economic, tee-attestation |

`Supported Chains`

`$3`

| Chain | Identity Registry | Status | | ------------- | -------------------------------------------- | ------------ | | ETH Sepolia |0x8004A818BFB912233c491871b3d84c89A494BD9e| ✅ Available | | Base Sepolia | Coming soon | 🔜 Pending | | Linea Sepolia | Coming soon | 🔜 Pending | | Polygon Amoy | Coming soon | 🔜 Pending |

`$3`

| Network | Program ID | | ------- | ---------------------------------------------- | | Devnet |HvF3JqhahcX7JfhbDRYYCJ7S3f6nJdrqu5yi9shyTREp |

`Generated Project Usage`

After generating your project:

`bash cd my-agent npm install`

`$3`

Edit .env and fill in:

`env PRIVATE_KEY=... # Auto-generated if you left wallet empty OPENAI_API_KEY=your_openai_key # For LLM responses PINATA_JWT=your_pinata_jwt # If using IPFS storage (requires pinJSONToIPFS scope)`

Auto-generated wallet: If you left the wallet address empty, a new wallet was generated and the private key is already in .env. Back up your .env file and fund the wallet with testnet tokens before registering.

- EVM chains: Fund with testnet ETH (use faucets for Sepolia, Base Sepolia, etc.) - Solana Devnet: Fund with devnet SOL viasolana airdrop or faucets

Pinata JWT: Create an API key at pinata.cloud with pinJSONToIPFS scope for public IPFS pinning.

`$3`

`bash npm run register`

EVM chains: Uploads metadata to IPFS and mints an NFT on the Identity Registry.

Solana: Validates metadata using buildRegistrationFileJson(), uploads to IPFS, and mints a Metaplex Core NFT via the 8004 program.

After registration, view your agent on 8004scan.io.

`$3`

If you update your agent's name, description, image, or OASF skills in src/register.ts, you need to sync these changes on-chain:

1. Update the configuration in src/register.ts. 2. Run the registration script again:`bash npm run register`This will upload the new metadata to IPFS and update your agent's URI on the Identity Registry.

`$3`

`bash

`Start A2A server`


npm run start:a2a
Start MCP server (in another terminal)

npm run start:mcp


A2A Protocol
The generated A2A server implements:

- Agent Card at /.well-known/agent-card.json- JSON-RPC 2.0 endpoint at/a2a- Methods:message/send, tasks/get, tasks/cancel

`$3`

1. Start the server:

`bash npm run start:a2a`

2. Test the agent card:

`bash curl http://localhost:3000/.well-known/agent-card.json`

3. Test the JSON-RPC endpoint:

`bash curl -X POST http://localhost:3000/a2a \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "message/send", "params": { "message": { "role": "user", "parts": [{"type": "text", "text": "Hello!"}] } }, "id": 1 }'`

`x402 Payments`

x402 payment support enables USDC micropayments for your agent. Available on:

| Chain | Facilitator | Status | | ----- | ----------- | ------ | | Base Mainnet | PayAI | ✅ Production | | Base Sepolia | PayAI | ✅ Testnet | | Polygon Mainnet | PayAI | ✅ Production | | Polygon Amoy | PayAI | ✅ Testnet |

When enabled, the A2A server uses x402 middleware for micropayments: - Per-request pricing (default: $0.001 USDC) - Automatic payment verification via facilitator - Payment configuration in.env: X402_PAYEE_ADDRESS, X402_PRICE

`MCP Protocol`

The generated MCP server includes sample tools:

- chat- Conversation with the LLM -echo- Echo back input (testing) -get_time - Current timestamp

Add your own tools in src/tools.ts.

`$3`

MCP uses stdio for communication. To test with the MCP Inspector:

`bash

`Install MCP Inspector`


npx @modelcontextprotocol/inspector
Or test directly with your MCP client

npm run start:mcp


The server will communicate over stdin/stdout following the MCP protocol.
Registration File Structure

`json { "type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1", "name": "My Agent", "description": "An AI agent...", "image": "https://example.com/image.png", "endpoints": [ { "name": "A2A", "endpoint": "http://localhost:3000/.well-known/agent-card.json", "version": "0.3.0" }, { "name": "MCP", "endpoint": "http://localhost:3001", "version": "2025-06-18" }, { "name": "agentWallet", "endpoint": "eip155:11155111:0x..." } ], "registrations": [ { "agentId": 123, "agentRegistry": "eip155:11155111:0x8004..." } ], "supportedTrust": ["reputation", "crypto-economic", "tee-attestation"] }`

`Development`

`$3`

`bash npm test`

`$3`

To run the full x402 integration tests (verifying paid requests work), you need a test wallet with testnet USDC:

1. Create a .envfile in the project root:`env TEST_PAYER_PRIVATE_KEY=0x...your_private_key...`

2. Fund the wallet with testnet USDC on: - Base Sepolia - Polygon Amoy

If TEST_PAYER_PRIVATE_KEY` is not set, x402 paid request tests will be skipped (other tests still run).

Resources

- ERC-8004 Specification
- 8004scan Explorer - View registered agents
- A2A Protocol
- Model Context Protocol
- x402 Protocol
- PayAI Facilitator - x402 facilitator for Base, Polygon
- 8004-solana SDK - Solana implementation

License

MIT

create-8004-agent

CLI tool to scaffold ERC-8004 compliant AI agents with A2A, MCP, and x402 payment support.

Supports both EVM chains and Solana.

What is ERC-8004?

ERC-8004 is a protocol for discovering and trusting AI agents across organizational boundaries. It provides:

- Identity Registry - On-chain agent registration as NFTs
- Reputation Registry - Feedback and trust signals
- Validation Registry - Stake-secured verification

Prerequisites

Quick Start

``bash npx create-8004-agent`

That's it! The wizard will guide you through creating your agent.

`What Gets Generated`

The wizard creates a complete agent project with:

`Wizard Options`

`Supported Chains`

`$3`

| Network | Program ID | | ------- | ---------------------------------------------- | | Devnet |HvF3JqhahcX7JfhbDRYYCJ7S3f6nJdrqu5yi9shyTREp |

`Generated Project Usage`

After generating your project:

`bash cd my-agent npm install`

`$3`

Edit .env and fill in:

`env PRIVATE_KEY=... # Auto-generated if you left wallet empty OPENAI_API_KEY=your_openai_key # For LLM responses PINATA_JWT=your_pinata_jwt # If using IPFS storage (requires pinJSONToIPFS scope)`

- EVM chains: Fund with testnet ETH (use faucets for Sepolia, Base Sepolia, etc.) - Solana Devnet: Fund with devnet SOL viasolana airdrop or faucets

Pinata JWT: Create an API key at pinata.cloud with pinJSONToIPFS scope for public IPFS pinning.

`$3`

`bash npm run register`

EVM chains: Uploads metadata to IPFS and mints an NFT on the Identity Registry.

Solana: Validates metadata using buildRegistrationFileJson(), uploads to IPFS, and mints a Metaplex Core NFT via the 8004 program.

After registration, view your agent on 8004scan.io.

`$3`

If you update your agent's name, description, image, or OASF skills in src/register.ts, you need to sync these changes on-chain:

`$3`

`bash

`Start A2A server`


npm run start:a2a
Start MCP server (in another terminal)

npm run start:mcp


A2A Protocol
The generated A2A server implements:

- Agent Card at /.well-known/agent-card.json- JSON-RPC 2.0 endpoint at/a2a- Methods:message/send, tasks/get, tasks/cancel

`$3`

1. Start the server:

`bash npm run start:a2a`

2. Test the agent card:

`bash curl http://localhost:3000/.well-known/agent-card.json`

3. Test the JSON-RPC endpoint:

`x402 Payments`

x402 payment support enables USDC micropayments for your agent. Available on:

`MCP Protocol`

The generated MCP server includes sample tools:

- chat- Conversation with the LLM -echo- Echo back input (testing) -get_time - Current timestamp

Add your own tools in src/tools.ts.

`$3`

MCP uses stdio for communication. To test with the MCP Inspector:

`bash

`Install MCP Inspector`


npx @modelcontextprotocol/inspector
Or test directly with your MCP client

npm run start:mcp


The server will communicate over stdin/stdout following the MCP protocol.
Registration File Structure

`Development`

`$3`

`bash npm test`

`$3`

To run the full x402 integration tests (verifying paid requests work), you need a test wallet with testnet USDC:

1. Create a .envfile in the project root:`env TEST_PAYER_PRIVATE_KEY=0x...your_private_key...`

2. Fund the wallet with testnet USDC on: - Base Sepolia - Polygon Amoy

If TEST_PAYER_PRIVATE_KEY` is not set, x402 paid request tests will be skipped (other tests still run).

Resources

License

MIT

create-8004-agent

create-8004-agent

Table of Contents

What is ERC-8004?

Prerequisites

Quick Start

What Gets Generated

Wizard Options

Supported Chains

$3

$3

Generated Project Usage

$3

$3

$3

$3

Start A2A server

Start MCP server (in another terminal)

A2A Protocol

$3

x402 Payments

MCP Protocol

$3

Install MCP Inspector

Or test directly with your MCP client

Registration File Structure

Development

$3

$3

Resources

License

create-8004-agent

create-8004-agent

Table of Contents

What is ERC-8004?

Prerequisites

Quick Start

What Gets Generated

Wizard Options

Supported Chains

$3

$3

Generated Project Usage

$3

$3

$3

$3

Start A2A server

Start MCP server (in another terminal)

A2A Protocol

$3

x402 Payments

MCP Protocol

$3

Install MCP Inspector

Or test directly with your MCP client

Registration File Structure

Development

$3

$3

Resources

License

`What Gets Generated`

`Wizard Options`

`Supported Chains`

`$3`

`$3`

`Generated Project Usage`

`$3`

`$3`

`$3`

`$3`

`Start A2A server`

`$3`

`x402 Payments`

`MCP Protocol`

`$3`

`Install MCP Inspector`

`Development`

`$3`

`$3`

`What Gets Generated`

`Wizard Options`

`Supported Chains`

`$3`

`$3`

`Generated Project Usage`

`$3`

`$3`

`$3`

`$3`

`Start A2A server`

`$3`

`x402 Payments`

`MCP Protocol`

`$3`

`Install MCP Inspector`

`Development`

`$3`

`$3`