This repository contains everything you need to register an existing service as an ERC-8004 compliant agent with verifiable persistent storage on Filecoin.
ERC-8004 is a standard for registering trustless autonomous agents on-chain. The challenge has always been: where do you store the agent metadata (the JSON file describing what an agent does and how to connect to it)?
This demo shows you how to:
- Store agent metadata on Filecoin with cryptographic proof (PDP - Proof of Data Possession)
- Register the agent on the ERC-8004 Identity Registry (Base Sepolia testnet)
- Verify that your agent is discoverable and its storage is provably persistent
⚠️ Important: This demo uses Filecoin Calibration testnet, which has no persistence guarantees and limited data retention. For production use requiring long-term storage, you'll need to migrate to Filecoin mainnet.
- Blog Post: Making Services Discoverable with ERC-8004
- Tutorial: ERC-8004 Agent Registration with Filecoin Pin
By the end of this, you'll have:
- An agent card (JSON metadata) stored on Filecoin with daily PDP proofs
- An ERC-721 NFT representing your agent on Base Sepolia
- A discoverable, verifiable agent identity that other agents can find and use
The example in this repo registers GitHub's official MCP server as an ERC-8004 agent, but you can adapt it for any service you want to make discoverable.
You'll need these installed:
-
Filecoin Pin CLI - For uploading to Filecoin with PDP proofs
npm install -g filecoin-pin
-
Foundry - Ethereum development toolkit (we use
castfor contract interactions)curl -L https://foundry.paradigm.xyz | bash foundryup -
jq (optional but recommended) - JSON processor for viewing outputs
# macOS brew install jq # Ubuntu/Debian sudo apt-get install jq
You'll need tokens on two testnets:
- tFIL (testnet Filecoin) - For gas fees
- Faucet: https://faucet.calibnet.chainsafe-fil.io/funds.html
- Amount needed: ~5 tFIL
- USDFC (Filecoin stablecoin) - For storage payments
- Mint at: https://stg.usdfc.net (requires tFIL as collateral)
- Amount needed: ~5 USDFC
- Sepolia ETH - For NFT minting and registration
- Faucet: https://www.alchemy.com/faucets/base-sepolia
- Amount needed: ~0.001 ETH
Note: The same Ethereum wallet works on both Filecoin Calibration and Base Sepolia. You only need one private key.
git clone https://github.com/[your-username]/FilecoinPin-for-ERC8004.git
cd FilecoinPin-for-ERC8004Copy the example environment file and fill in your values:
cp .env.example .envEdit .env and add:
- Your private key (with 0x prefix)
- Your wallet address
The other values are pre-configured for the testnets.
Visit the faucets listed in the Prerequisites section to get:
- tFIL from the Filecoin Calibration faucet
- USDFC by minting at stg.usdfc.net
- Sepolia ETH from the Base Sepolia faucet
The repo includes github-agent-card.json which registers GitHub's MCP server. If you want to register your own service:
- Edit
github-agent-card.json - Update the
name,description, andendpointsto match your service - Follow the ERC-8004 specification for the schema
Run the scripts in order:
./scripts/0-prerequisites.shThis verifies you have all the required tools and testnet tokens.
./scripts/1-upload-to-filecoin.shThis uploads your agent card to Filecoin with PDP proofs and returns a CID (Content Identifier).
Important: Copy the AGENT_CARD_CID and DATASET_ID from the output and add them to your .env file.
./scripts/2-register-agent.shThis mints an ERC-721 NFT representing your agent on the ERC-8004 Identity Registry.
Important: Copy the AGENT_ID from the output and add it to your .env file.
./scripts/3-verify-storage.shThis verifies:
- Your agent card is retrievable via IPFS
- PDP proofs are active
- Your agent is registered on-chain
- The tokenURI matches your uploaded content
./scripts/4-query-agent.shThis demonstrates how other agents/applications would discover and use your agent:
- Query the registry for your agent ID
- Retrieve the tokenURI
- Fetch the agent card from IPFS
- Parse capabilities
FilecoinPin-for-ERC8004/
├── README.md # This file
├── .env.example # Environment template
├── github-agent-card.json # Example agent card (GitHub MCP server)
└── scripts/
├── 0-prerequisites.sh # Check tools and tokens
├── 1-upload-to-filecoin.sh # Upload to Filecoin Pin
├── 2-register-agent.sh # Register on ERC-8004 registry
├── 3-verify-storage.sh # Verify storage and registration
└── 4-query-agent.sh # Demonstrate agent discovery
After running these scripts successfully, you'll have:
- ✅ Persistent storage - Your agent card stored on Filecoin with cryptographic PDP proofs
- ✅ On-chain registration - An ERC-721 NFT representing your agent on Base Sepolia
- ✅ Discoverability - Other agents can find your agent via the ERC-8004 registry
- ✅ Verifiability - Anyone can verify your storage proofs and on-chain data
- ✅ IPFS compatibility - Your agent card is accessible via any IPFS gateway
Install the Filecoin Pin CLI:
npm install -g filecoin-pinMint more USDFC at https://stg.usdfc.net using tFIL as collateral.
Check your Base Sepolia ETH balance and get more from the faucet if needed.
IPFS propagation can take a few minutes. Try different gateways:
- https://ipfs.io/ipfs//github-agent-card.json
- https://gateway.pinata.cloud/ipfs//github-agent-card.json
- https://cloudflare-ipfs.com/ipfs//github-agent-card.json
PDP proofs can take up to 24 hours to begin after upload. This is normal - your data is still stored, proofs just take time to generate.
- ERC-8004 Specification: https://eips.ethereum.org/EIPS/eip-8004
- Filecoin Pin Documentation: https://docs.filecoin.io/builder-cookbook/filecoin-pin
- Base Sepolia Explorer: https://sepolia.basescan.org
- ERC-8004 Reference Implementation: https://github.com/ChaosChain/trustless-agents-erc-ri
This is an experimental demo running on testnets. We'd love feedback on what works and what doesn't!
If you encounter issues or have suggestions, please open an issue on GitHub.
MIT