ERC-8004 + Pinata Examples

Scripts and wizard for ERC-8004 agent registration using Pinata for IPFS storage.

Note: ERC-8004 supports any storage backend (IPFS, Arweave, HTTPS, data URIs). This repo is specifically for the IPFS + Pinata workflow. The scripts upload agent cards to Pinata and set ipfs:// token URIs on-chain.

Quick Start

git clone https://github.com/PinataCloud/erc8004
cd erc8004
bun install
cp .env.example .env  # fill in your values

Copy an example agent card and customize it:

cp examples/minimal/agent-card.json my-agent.json
# edit my-agent.json with your agent details

Register your agent:

bun run register my-agent.json

Example Agent Cards

Example	Description
minimal	Bare minimum required fields
basic	Full spec with all supported fields

Scripts

bun run register <agent-card.json>              # Register new agent
bun run register <agent-card.json> --update 3   # Update agent #3
bun run verify <agent-id>                       # Verify registration
bun run check-registration <agent-id>           # Check registrations[] matches on-chain
bun run set-wallet <agent-id>                   # Set payment wallet
bun run unset-wallet <agent-id>                 # Clear payment wallet

Network Selection

By default, scripts use Ethereum Sepolia testnet. To use a different network:

Via environment variable:

NETWORK=base-mainnet bun run register my-agent.json

Via CLI flag:

bun run register my-agent.json --network base-mainnet
bun run verify 1 --network polygon-mainnet

Supported networks:

Network	ID	Type
Ethereum Mainnet	ethereum-mainnet	mainnet
Ethereum Sepolia	ethereum-sepolia	testnet
Base Mainnet	base-mainnet	mainnet
Base Sepolia	base-sepolia	testnet
Polygon Mainnet	polygon-mainnet	mainnet
Polygon Amoy	polygon-amoy	testnet
Monad Mainnet	monad-mainnet	mainnet
Monad Testnet	monad-testnet	testnet
BSC Mainnet	bsc-mainnet	mainnet
BSC Testnet	bsc-testnet	testnet

Verifying Agents

The verify script fetches agent cards from IPFS via your Pinata gateway.

Note: These scripts only support ipfs:// token URIs. Agents using other storage (data URIs, HTTPS URLs, Arweave) will show an error explaining the URI type isn't supported by this tool.

Verifying your own agents: Your Pinata gateway can access any content you've pinned, so verifying agents you registered works out of the box.

Verifying other agents: By default, Pinata gateways only serve content you've pinned. To verify any IPFS-based agent on the network, set up Gateway Access Controls and add a gateway key to your .env:

PINATA_GATEWAY_KEY=your_gateway_access_token

Or pass it via CLI:

bun run verify 1 --gateway-key your_token

Prerequisites

1. Pinata account — pinata.cloud
2. Native tokens for gas on your chosen network
3. Wallet private key

Resources

• ERC-8004 Spec
• Pinata Docs
• Wizard — Interactive terminal wizard for agent registration

Contract Addresses:

Network	Identity Registry
Mainnets	0x8004A169FB4a3325136EB29fA0ceB6D2e539a432
Testnets	0x8004A818BFB912233c491871b3d84c89A494BD9e

License

MIT