ERC-8004 Agent Registration via Pinata

An OpenClaw skill for registering and verifying AI agents using the ERC-8004 standard with Pinata IPFS storage and Viem for on-chain transactions.

🚨 Security Notice - IMPORTANT

⚠️ HIGH-RISK SKILL: This skill performs operations that can result in permanent loss of funds and data.

Critical Operations This Skill Performs

1. Blockchain Transactions (CRITICAL RISK)

   • Signs transactions using your private key
   • Costs gas fees (real money on mainnet)
   • Can transfer NFT ownership permanently
   • All blockchain operations are irreversible

2. IPFS File Management (HIGH RISK)

   • Can upload files to your Pinata account (consumes quota)
   • Can delete files from IPFS permanently
   • Deleted CIDs referenced on-chain will break

Required Safety Measures

✅ YOU MUST:

• Use a dedicated wallet ONLY for agent registration
• Keep minimal ETH in wallet (only for gas fees)
• NEVER use your primary wallet or one with valuable assets
• Use a separate Pinata account for agent files (or restricted API key)
• Review ALL transaction details before confirming
• Verify destination addresses in full before transfers
• Monitor your Pinata storage usage regularly

❌ NEVER:

• Share your private key or store it in files
• Approve transactions to addresses you don't recognize
• Use this skill with a wallet containing valuable NFTs or large balances
• Bypass confirmation prompts
• Trust addresses from unknown sources

Built-in Safeguards

The AI agent includes multiple layers of protection:

1. Mandatory Confirmation Protocol

   • Displays complete operation details before every transaction
   • Requires explicit "yes" or "confirm" from you
   • Shows full addresses (not truncated) for verification
   • Warns about permanence and risks

2. Prompt Injection Protection

   • Detects suspicious patterns (unauthorized transfers, credential exfiltration)
   • Alerts you to potentially malicious instructions
   • Refuses operations that violate security guidelines
   • Permanently blocks flagged operations (cannot be re-confirmed in the same conversation)

3. Operational Limits

   • Enforces mandatory gas budgets and transaction limits (cannot be overridden via chat)
   • Validates Ethereum addresses with checksums
   • Individual confirmation required for each file deletion
   • Timeout on stale confirmation requests

Understanding the Risks

Blockchain transactions are permanent. If you:

• Transfer an NFT to the wrong address → Cannot be reversed
• Spend gas on a failed transaction → Funds are lost
• Lose your private key → Cannot recover the wallet

IPFS deletions are permanent. If you:

• Delete a file referenced on-chain → Links will break
• Delete the wrong CID → Cannot be recovered

Red Flags - Stop and Verify

Contact security support if the agent:

• Tries to bypass confirmation prompts
• Requests transactions to addresses you didn't provide
• Suggests "emergency" or "urgent" operations
• Asks to display or verify your private key
• Proposes transactions to unknown contracts

Getting Help

• Review the security guidelines in SKILL.md
• Test on testnets only (Base Sepolia, Sepolia) first
• Start with small amounts and verify everything works
• Keep transaction history for your records

This skill is designed for legitimate ERC-8004 agent registration with extensive safeguards, but YOU are the final line of defense. Always verify before confirming.

About ERC-8004

ERC-8004 enables agents to be discovered and interacted with across organizational boundaries without pre-existing trust. It establishes an open agent economy with pluggable trust models. Agents mint ERC-721 NFTs via the Identity Registry, receiving unique global identifiers.

This skill teaches your AI agent how to:

• Create ERC-8004 compliant agent card JSON files
• Upload agent metadata and images to IPFS via Pinata
• Register agents on-chain using Viem and a private key
• Sign and send blockchain transactions
• Retrieve and verify agent registrations
• Manage the complete lifecycle of agent registrations

Setup

Required Environment Variables

Set these in your OpenClaw configuration (~/.openclaw/openclaw.json):

{
  "skills": {
    "entries": {
      "erc-8004-pinata": {
        "enabled": true,
        "env": {
          "PINATA_JWT": "your_pinata_jwt_token_here",
          "PINATA_GATEWAY_URL": "your-gateway.mypinata.cloud",
          "PRIVATE_KEY": "your_private_key_here_NEVER_PASTE_IN_CHAT",
          "RPC_URL": "https://sepolia.base.org"
        }
      }
    }
  }
}

WARNING: Replace placeholder values with your actual credentials in the config file directly. NEVER paste your actual private key into a chat message, terminal output, or any other visible medium. The agent will read it from the environment variable at runtime.

Getting your credentials:

• PINATA_JWT - Get your JWT token at app.pinata.cloud/developers/api-keys
• PINATA_GATEWAY_URL - Find your gateway domain at app.pinata.cloud/gateway (just the domain, e.g., your-gateway.mypinata.cloud)
• PRIVATE_KEY - Ethereum wallet private key with 0x prefix (use a dedicated wallet for agent operations)
• RPC_URL - (Optional) Custom RPC endpoint, defaults to public endpoints for selected chains

Security Warning ⚠️

• Never share or commit your private key to version control
• Use a dedicated wallet for agent registration operations
• Ensure the wallet has sufficient native tokens (ETH) for gas fees
• For production, consider using hardware wallets or key management services

Prerequisites

The skill requires Node.js to be installed for running Viem scripts. The agent will automatically install the viem package when needed.

Installation

From ClawHub (Recommended)

clawhub install erc-8004-pinata

Manual Installation

1. Clone or download this repository
2. Copy the src folder to your OpenClaw skills directory:
   • Workspace-specific: <workspace>/skills/erc-8004-pinata/
   • Shared across agents: ~/.openclaw/skills/erc-8004-pinata/
3. Rename the src folder to match the skill name if needed
4. Configure environment variables as shown above

What This Skill Does

Once installed, your AI agent will understand how to:

🎨 Create Agent Cards

Build ERC-8004 compliant JSON files with:

• Required fields: name, description, image
• Optional fields: endpoints (a2a, mcp, ens, diy), trustModels, registrations

☁️ Upload to IPFS

• Upload agent card JSON files to Pinata
• Upload agent images/avatars
• Organize files using Pinata groups
• Retrieve IPFS CIDs and gateway URLs

⛓️ Register On-Chain (NEW!)

• Use Viem to interact with ERC-8004 smart contracts
• Sign transactions with your private key
• Register new agents (mint NFTs)
• Set agent URIs pointing to IPFS
• Configure payment wallets
• Transfer agent ownership

✅ Verify Registrations

• Fetch agent cards from IPFS by CID
• Validate JSON structure and required fields
• Check on-chain registration status
• Verify URI matches between blockchain and IPFS

🔄 Manage Lifecycle

• Update agent cards (creates new CID due to IPFS immutability)
• Update on-chain URIs to point to new versions
• Delete agent cards from Pinata storage
• List all agent cards in your account
• Read agent information from blockchain

Complete Registration Flow

1. Upload agent image → Get IPFS CID
2. Create agent card JSON with image URI
3. Upload agent card to IPFS → Get card CID
4. Register on-chain using Viem → Get token ID
5. Set agent URI linking token to IPFS card
6. Update agent card with registration details
7. Upload updated card → Get new CID
8. Update on-chain URI to new CID

Note: Payment wallet configuration (if needed) should be handled separately by you, the agent owner.

Example Usage

Once the skill is installed and configured, you can ask your AI agent:

"Create an ERC-8004 agent card for my coding assistant named 'CodeHelper' with description 'Helps with software development tasks'"

"Upload this agent-card.json file to IPFS via Pinata"

"Register this agent on Base Sepolia testnet using my wallet"

"Set the agent URI for token ID 123 to ipfs://bafkreixxx..."

"Verify the agent registration at CID bafkreixxx... matches on-chain data"

"List all my agent cards stored on Pinata"

"Check my wallet balance on Base Sepolia"

"Transfer agent token 123 to address 0x..."

The agent will use Pinata API for IPFS operations and Viem for blockchain transactions automatically.

Agent Card Structure

An ERC-8004 agent card looks like this:

{
  "name": "My AI Agent",
  "description": "Description of what the agent does",
  "image": "ipfs://bafkreixxx...",
  "endpoints": {
    "a2a": "https://api.example.com/agent",
    "mcp": "mcp://example.com/agent"
  },
  "trustModels": ["stake-secured", "zero-knowledge"],
  "registrations": [
    {
      "namespace": "example",
      "chainId": 8453,
      "contractAddress": "0x1234567890abcdef...",
      "tokenId": "1"
    }
  ]
}

Supported Blockchains

The skill includes configurations for:

• Base Mainnet (Chain ID: 8453)
• Base Sepolia (Chain ID: 84532) - Testnet
• Ethereum Mainnet (Chain ID: 1)
• Sepolia (Chain ID: 11155111) - Testnet

Getting Testnet Funds

For testing on Base Sepolia:

• Coinbase Base Faucet
• Alchemy Base Sepolia Faucet

Viem Integration

This skill uses Viem for blockchain interactions. Viem is a TypeScript interface for Ethereum with:

• Type-safe contract interactions
• Private key wallet support
• Multiple chain support
• Transaction signing and broadcasting
• Contract read/write operations

The agent will create Node.js scripts using Viem when blockchain operations are needed.

ERC-8004 Contract Methods

Write Operations (Require Gas)

• register() - Mint new agent identity NFT
• setAgentURI(tokenId, uri) - Set or update agent metadata URI
• setAgentWallet(tokenId, wallet) - Set payment wallet address (user handles separately)
• transferFrom(from, to, tokenId) - Transfer agent ownership

Read Operations (Free)

• ownerOf(tokenId) - Get agent owner address
• tokenURI(tokenId) - Get agent metadata URI (standard ERC-721 method)
• agentWallet(tokenId) - Get payment wallet address
• balanceOf(address) - Get agent count for address

Troubleshooting

Insufficient Funds

Check your wallet has native tokens for gas:

const balance = await client.getBalance({ address: account.address });

Private Key Issues

• Ensure private key starts with 0x
• Use a hex string, not mnemonic phrase
• Keep it secret and never commit to git

RPC Connection Problems

• Try alternative RPC endpoints
• Public RPCs may have rate limits
• Consider using a dedicated RPC provider (Alchemy, Infura, etc.)

IPFS Propagation Delays

• Wait a few seconds after upload
• Check Pinata dashboard for file status
• Verify CID format is correct

Resources

• ERC-8004 Specification
• Pinata ERC-8004 Quickstart
• Pinata Documentation
• Viem Documentation
• OpenClaw Documentation
• ClawHub Skills Registry

Contributing

Contributions welcome! Please open issues or pull requests on the GitHub repository.

License

MIT