AIOZ Pin for AI Agents: Storing ERC-8004 Files on IPFS
AIOZ Pin for AI agents is a newer application of the exact same tooling this blog has covered for NFTs: content-addressed pinning, an NFT-based identity token, and gateways that serve the result. The specific standard driving this is ERC-8004 ("Trustless Agents"), a Draft Ethereum proposal for giving autonomous AI agents a verifiable on-chain identity backed by an IPFS-hosted document. NFTs as a category get called dated fairly often at this point, but the underlying mechanism, an ERC-721 token pointing at a pinned, content-addressed file, turns out to be exactly the right shape for agent identity too. This article covers what ERC-8004 actually defines and where AIOZ Pin's existing tooling fits into it.
TL;DR:
- ERC-8004 gives each AI agent an ERC-721 identity token pointing at a "Registration File"
- That file is a JSON document pinned to IPFS describing the agent's capabilities and endpoints
- AIOZ Pin's
pinNft()and pinning tooling map directly onto this: pin the file, reference it asipfs://{cid}, register the agent's token - ERC-8004 is currently a Draft EIP, not a finalized standard, so build against it carefully
What ERC-8004 Actually Defines
Per the official EIP text, the standard's abstract states it "proposes to use blockchains to discover, choose, and interact with agents across organizational boundaries without pre-existing trust, thus enabling open-ended agent economies." It defines three on-chain registries:
| Registry | What it does |
|---|---|
| Identity | Built on ERC-721 + URIStorage. register(agentURI, metadata) returns an agentId, the agent's permanent on-chain handle |
| Reputation | giveFeedback() records a 0-100 score plus tags per interaction, with optional off-chain detail via feedbackURI |
| Validation | validationRequest()/validationResponse() let independent validators score agent output 0-100, with evidence referenced off-chain |
The Identity Registry is the piece most directly relevant to pinning: it's an ERC-721 token, the same token standard AIOZ Pin's pinNft() method is already built around.
The Registration File Is Exactly What Pinning Services Exist For
Each agent's identity token points at a Registration File, a JSON document with a defined shape: type (pointing at the EIP spec itself), name, description, image, a services array listing the agent's endpoints, an x402Support flag, an active flag, and a registrations array. The spec's own convention for referencing it is direct: ipfs://{cid}, no separate hash field needed, since a CID already is a content hash. That's the same content-addressing property this blog has covered for NFT metadata tamper-evidence, applied to an agent's declared capabilities instead of an artwork's attributes. Pin the file, get a CID, reference the CID, done, the exact workflow AIOZ Pin's pinning API is built around.
Where Reputation and Validation Data Fits
Feedback and validation records store their core value (score, tags, timestamp) on-chain for cheap querying, but the spec allows richer detail, evidence files, detailed feedback, work samples, referenced off-chain through feedbackURI and responseURI fields with an optional feedbackHash/responseHash for integrity checking. This is a smaller-scale version of the same pattern: on-chain stores a pointer and a hash, off-chain (IPFS) stores the actual content, and the hash lets anyone verify the off-chain content hasn't been altered. AIOZ Pin's Premium Gateways are relevant here too, serving that off-chain evidence without the rate limits a public gateway would impose if a validator's evidence file gets checked frequently.
Why the Pinning Service API Standard Matters Here Specifically
This series' coverage of the IPFS Pinning Service API standard already makes the general portability case: build against the standard, and switching providers is an endpoint-and-key swap, not a rewrite. For agent infrastructure specifically, that portability matters more than it does for a typical file-storage integration. An agent's Identity Registry entry is meant to be a permanent, on-chain handle, and if the pinning provider behind its Registration File ever needs to change, whether from a pricing change, a shutdown, or simply switching vendors, the ability to migrate without rewriting the pinning logic in whatever framework the agent runs on is a real operational advantage. Building agent tooling against a standard-compliant pinning API, which AIOZ Pin's is, means that migration path exists from day one rather than being bolted on after a provider dependency becomes a problem.
An Important Caveat: This Is a Draft Standard
ERC-8004's status on the official EIP page is Draft, not Final. It's gotten real attention, reportedly refined with input from Coinbase, MetaMask, ENS, EigenLayer, and The Graph per community coverage, but "Draft" means the interface can still change before finalization. If you're building against it today, pin your Registration Files the same way you would any other content, but don't treat the exact JSON schema or registry interface as permanently locked until the EIP progresses further.
Not Just a Registration File: The Same Pattern Twice More
It's worth being clear that pinning shows up in ERC-8004 three separate times, not once. The Identity Registry's Registration File is the piece covered above, but the Reputation Registry's feedbackURI and the Validation Registry's responseURI follow the identical on-chain-pointer-plus-pinned-evidence pattern, covered in dedicated detail in this blog's coverage of why agent reputation data belongs on IPFS. An agent built on ERC-8004 end to end, identity, reputation tracking, and validated work, ends up pinning several distinct categories of file over its lifetime, not a single one-time upload at registration, which is part of why treating pinning as ongoing infrastructure rather than a one-off step matters for this use case specifically.
Frequently Asked Questions
What is ERC-8004? A Draft Ethereum standard, "Trustless Agents," that gives AI agents a verifiable on-chain identity via an ERC-721 token pointing at an IPFS-hosted Registration File, plus on-chain Reputation and Validation registries for tracking agent performance.
Is ERC-8004 a finalized standard? No. Its status on the official EIP page is Draft, not Final. The core registry interfaces are stable enough for real building, per community coverage, but the spec can still change before it's finalized.
How does IPFS fit into ERC-8004? Each agent's identity token references a Registration File, a JSON document describing the agent, pinned to IPFS and referenced as ipfs://{cid}. Reputation and Validation records can similarly reference off-chain evidence files the same way.
Can I use AIOZ Pin's existing NFT tooling for ERC-8004 agent identities? Yes. Since ERC-8004's Identity Registry is built on ERC-721, the same underlying token standard AIOZ Pin's pinNft() method targets, pinning a Registration File and referencing its CID follows the same workflow already covered for NFT metadata.
Who is backing ERC-8004? Per community coverage, it's been refined with input from Coinbase, MetaMask, ENS, EigenLayer, and The Graph, though this is secondary reporting, not a claim made by the EIP text itself.
Related Reading
- How AIOZ Pin Works: Pinning, Gateways, and NFT Tools - the
pinNft()and gateway mechanics this pillar builds on - How AIOZ Pin Keeps Files Online: Replication and Proofs - the content-addressing property that makes CID-referenced registration files tamper-evident
- How to Mint NFTs with Persistent Metadata on AIOZ Pin - the same pin-then-reference workflow applied to a different identity token
References
Related Content
How IPFS Splits Files: Fixed vs. Content-Defined Chunking
IPFS defaults to 256 KiB fixed-size chunks, but also ships Rabin and Buzhash content-defined chunkers. Here is why the choice affects deduplication.
Anatomy of a CID: Decoding an IPFS Identifier
An IPFS CID is not a random string. It encodes a version, a codec, and a hash algorithm plus digest. Here is how to decode a real CID piece by piece.
How IPFS Shards Large Directories: The HAMT, Not a B-Tree
IPFS does not use a B-tree for large directories. It uses a HAMT, a Hash Array Mapped Trie. Here is exactly how it shards a folder once it outgrows one block.
How to Resize Images on AIOZ Pin Using URL Parameters
AIOZ Pin image resizing happens straight in the gateway URL, no upload step or separate service. Here is every img- parameter, with real srcset examples.
How x402 Payments Weight AI Agent Reputation on ERC-8004
x402 payments let ERC-8004 weight a paid AI agent interaction more heavily than free work in its reputation score. Here is exactly how that link works.
How to Automate NFT Pinning with the AIOZ Pin NFT API
AIOZ Pin NFT API calls pin an asset and its metadata as two tracked pins under one record. Here is how to automate it directly over REST, no SDK needed.