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

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

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).

npx create-8004-agent

That's it! The wizard will guide you through creating your agent. If you want 4mica-powered x402 payments, choose a supported chain (Ethereum Sepolia or Polygon Amoy), enable x402 payments, and select 4mica as the provider when prompted.

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

After generating your project:

cd my-agent
npm install

Edit .env and fill in:

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 via solana airdrop or faucets

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

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.

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:

   npm run register

This will upload the new metadata to IPFS and update your agent's URI on the Identity Registry.

# Start A2A server
npm run start:a2a

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

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

1. Start the server:

npm run start:a2a

2. Test the agent card:

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

3. Test the JSON-RPC endpoint:

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 payment support enables USDC micropayments for your agent. Available on:

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
• 4mica only: X402_TAB_ENDPOINT (public tab endpoint advertised to clients)

If you select x402 payments and choose 4mica during the wizard, you will be prompted: Register with 4mica now (optional collateral deposit)?

If you say yes, the CLI will:

• Ask for a wallet private key (or use the one it generated).
• Ask which asset to deposit (USDC, USDT, or native token) and how much.
• Submit an on-chain deposit via the 4mica SDK and print the transaction hash.

You can safely skip this step if you are not ready to fund the wallet yet. The agent still generates and runs; you can enable 4Mica later after funding a wallet.

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.

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

# 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.

{
  "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"]
}

npm test

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

1. Create a .env file in the project root:

TEST_PAYER_PRIVATE_KEY=0x...your_private_key...

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

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

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

MIT