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:

  1. Filecoin Pin CLI - Follow the complete setup guide here:

  2. Foundry - Ethereum development toolkit for contract interactions

  3. jq (optional but recommended) - JSON processor for viewing outputs

Required Tokens

You'll need testnet tokens on two networks:

Filecoin Calibration Testnet

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 version

  • name - Human-readable name for your agent

  • description - What the agent does

  • image - Avatar or logo URL

  • endpoints - 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 provides

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

Base Sepolia block explorer, showing NFT minted

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

Solution: Install the Filecoin Pin CLI:

Issue: Insufficient USDFC

Solution: Request more test USDFC at Filecoin Calibnet USDFC Faucet

Issue: Transaction reverted on Base Sepolia

Solution: 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

  1. Create custom agent cards for your services

  2. Deploy your own MCP server and reference it in the agent card

  3. Register multiple agents for different capabilities

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

Sponsered Storage for ERC-8004 Builders

Coming soon, stay tuned!


Additional Resources


Happy building! 🚀

Last updated

Was this helpful?