Filecoin Pin for ERC-8004 Agents
How to use the Filecoin Pin CLI with ERC-8004 autonomous agents
Learn how to register a trustless autonomous agent on the ERC-8004 Identity Registry with verifiable persistent storage using Filecoin Pin for the agent registration file.
Overview
This tutorial walks you through registering an ERC-8004 compliant agent with cryptographically-verified persistent storage on Filecoin. You'll create an agent card (metadata describing your agent's capabilities), store it on Filecoin & IPFS using Filecoin Pin, and register it on-chain as an NFT on Base Sepolia.
What you'll learn:
How to create an ERC-8004 compliant agent card
How to use Filecoin Pin for persistent, verifiable storage
How to register an agent on the ERC-8004 Identity Registry
How to verify Filecoin storage proofs and on-chain registration
What you'll build: A GitHub Integration Agent that references GitHub's official MCP server, demonstrating how real-world services can be integrated with ERC-8004.
Example Code and Scripts
For example code and helper scripts to help with using Filecoin Pin and agent registration, check out the quickstart repository:
GitHub Repository: FilOzone/FilecoinPin-for-ERC8004
Why Filecoin Pin for Agent Storage?
Agent cards need persistent storage with provable guarantees. Unlike generic IPFS pinning services that may stop hosting your data without notice, Filecoin Pin provides:
✅ Cryptographic proof your data is stored (daily PDP proofs)
✅ Ongoing verification ensures storage persistence
✅ Decentralized storage across a global network
✅ IPFS compatible - works with existing tools and gateways
✅ Crypto payments - onchain payments
✅ Limited time - sponsered storage coming soon available for ERC-8004 builders
Prerequisites
Required Tools
Before starting, you'll need:
Filecoin Pin CLI - Follow the complete setup guide here:
This covers wallet creation, testnet tokens (tFIL and USDFC), and payment setup
Foundry - Ethereum development toolkit for contract interactions
jq (optional but recommended) - JSON processor for viewing outputs
Required Tokens
You'll need testnet tokens on two networks:
Filecoin Calibration Testnet
tFIL (testnet Filecoin) - For gas fees
Request tFIL from Filecoin Calibration Faucet
Amount requested: 100 tFIL
USDFC (Filecoin stablecoin) - For storage payments
Request test USDFC from Filecoin Calibnet USDFC Faucet
Or Mint at USDFC website (requires at tFIL as collateral)
Amount needed: ~5 USDFC
Base Sepolia Testnet
Sepolia ETH - For NFT minting and registration
Request test ETH on Base Sepolia on Faucet
Amount needed: ~0.001 ETH
NOTE! The same Ethereum wallet works on both Filecoin Calibration and Base Sepolia. You only need one private key.
ERC-8004 Registry Address
We'll be using the reference ERC-8004 Identity Registry deployed on the Base Sepolia testnet:
Step 1: Create Your Agent Card
An agent card is a JSON file that describes your agent's capabilities, endpoints, and trust model according to the ERC-8004 specification.
Create the Agent Card JSON
Create a file named github-agent-card.json:
Validate the JSON
Verify your agent card is valid JSON:
You should see the formatted JSON output with syntax highlighting.
Understanding the Agent Card Structure
Key fields in the agent card:
type- Links to the ERC-8004 specification versionname- Human-readable name for your agentdescription- What the agent doesimage- Avatar or logo URLendpoints- Array of service endpoints:MCP endpoint - Points to GitHub's official MCP server
agentWallet - The agent's wallet address (chain:chainId:address format)
capabilities- Tools and functions the agent providessupportedTrust- Trust mechanisms (reputation, stake, etc.)
💡 Note: This example uses GitHub's real public MCP server at
https://api.githubcopilot.com/mcp/. You can replace this with your own MCP server endpoint.
Step 2: Upload to Filecoin Pin
Now we'll store the agent card on Filecoin with PDP proofs.
Setup Payment System
If this is your first time using Filecoin Pin, set up the payment system:
This configures your wallet to pay for storage automatically. This may take a few minutes to complete.
You'll see output similar to:
NOTE! You only need to run this once per wallet. Subsequent uploads will use the existing payment configuration.
Upload Your Agent Card
Upload the agent card to Filecoin:
The --auto-fund flag ensures your storage provider wallet has sufficient funds.
You'll see output similar to:
NOTE! Data storage on the Calibration Testnet has a retention period of approximately 1 week. For production use and to ensure your data remains available, please switch to Filecoin mainnet.
Save Important Values
Copy these values from the output - you'll need them later:
Root CID - The IPFS content identifier (e.g.,
bafybeihhal5hlbylkibniig6j72wdrm7lr4nf6z47natleh2jkyosrg7di).Dataset ID - For checking PDP proof status (e.g.,
933)
⚠️ IMPORTANT: The Token URI for ERC-8004 registration must include the filename! Format it as:
Verify IPFS Retrieval
Test that your agent card is accessible via IPFS (it may take a few minutes to propogate!):
You should see your agent card JSON returned:
Step 3: Register on Base Sepolia
Now we'll register the agent on-chain as an ERC-8004 NFT on Base Sepolia.
Set Environment Variables
⚠️ SECURITY WARNING: Never commit your private key to version control or share it publicly.
Check Your Balance
Ensure you have sufficient Base Sepolia ETH:
You should have at least 0.001 ETH for the registration transaction.
Register the Agent
Send the registration transaction:
You'll see output similar to:
A status of 1 means the transaction succeeded and your agent NFT was minted!
Get Your Agent ID
Query the registry to find your agent's ID:
This returns the total number of registered agents. Your agent ID is this number (the latest registration):
Convert Agent ID to Decimal
The query returns a hex value (e.g., 0x38). Convert to decimal:
Verify Registration
Confirm your agent is registered correctly:
You will get output similar to:
The output is ABI-encoded. Decode it:
You should see your Token URI returned: ipfs://<ROOT_CID>/github-agent-card.json:
View on Block Explorer
Visit your agent on the Base Sepolia block explorer:
Replace <AGENT_ID_DECIMAL> with your agent's ID (e.g., 56).

Step 4: Check On-chain Storage Proofs
Finally, let's verify that your agent card is persistently stored with cryptographic proofs.
Check PDP Proof Status
Use the Dataset ID from Step 2:
You'll see output like:
💡 Note: PDP proofs may take up to 24 hours to begin after initial upload. This is normal.
Test Complete Workflow
Simulate how another agent would discover and use your agent:
Summary
✅ Your agent is now:
🔒 Persistently stored on Filecoin with cryptographic PDP proofs
🌐 Registered on-chain as an ERC-8004 NFT on Base Sepolia
🔍 Discoverable via the Identity Registry by any third party
✅ Verifiable - anyone can check storage proofs and on-chain data
🚀 Ready to use by other agents and applications
Troubleshooting
Issue: filecoin-pin: command not found
filecoin-pin: command not foundSolution: Install the Filecoin Pin CLI:
Issue: Insufficient USDFC
Insufficient USDFCSolution: Request more test USDFC at Filecoin Calibnet USDFC Faucet
Issue: Transaction reverted on Base Sepolia
Transaction reverted on Base SepoliaSolution: Check your Base Sepolia ETH balance:
Get more from the faucet if needed.
Issue: IPFS retrieval is slow or fails
Solution: IPFS propagation can take a few minutes. Try different gateways:
Issue: PDP proofs not showing
Solution: 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. Check back later with:
Issue: Token URI doesn't include filename
Solution: The Token URI must include the full path including filename. Correct format:
If you registered with the wrong format, you'll need to register a new agent with the corrected Token URI.
What's Next?
Now that your agent is registered with verifiable persistent storage, you can:
Build Your Own Agent
Create custom agent cards for your services
Deploy your own MCP server and reference it in the agent card
Register multiple agents for different capabilities
Update agent cards by uploading new versions (CID changes) and updating on-chain
Explore ERC-8004 Features
Reputation Registry - Build reputation for your agents
Validation Registry - Add validators to verify agent behavior
Multi-agent coordination - Discover and compose multiple agents
Join the Community
Filecoin Builders: on telegram; on Slack
ERC-8004 Discussion: GitHub Discussions
Filecoin Pin: Documentation
Builder Channels: Join ERC-8004 builder communities
Sponsered Storage for ERC-8004 Builders
Coming soon, stay tuned!
Additional Resources
Happy building! 🚀
Last updated
Was this helpful?