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 as ipfs://{cid}, register the agent's token
• ERC-8004 is currently a Draft EIP, not a finalized standard, so build against it carefully

Updated Oct 22, 2026: merged our separate post How to Pin an ERC-8004 Registration File on AIOZ Pin into this guide.

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:

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.

How do you pin an ERC-8004 registration file?

Pinning the file is the off-chain half of registering an agent, and you can do it before you touch a contract. The steps below follow the ERC-8004 draft as it reads on Oct 22, 2026. Our docs don't cover ERC-8004, so treat this as general IPFS practice, not an AIOZ Pin feature.

1. Build the file. The EIP requires a JSON document with type, name, description and image at the top, which keeps it readable by ordinary ERC-721 apps. Each entry in services uses name and endpoint, and version is recommended but optional. A minimal file looks like this:

{
  "type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
  "name": "research-assistant",
  "description": "Summarizes and cross-references academic papers.",
  "image": "https://example.com/agent.png",
  "services": [
    { "name": "A2A", "endpoint": "https://agent.example/.well-known/agent-card.json", "version": "0.3.0" }
  ],
  "x402Support": false,
  "active": true,
  "registrations": []
}

2. Validate it before you pin it. A pinning service stores bytes and never checks them against the ERC-8004 schema, so a file with services as a string pins just as happily as a correct one. A one-line check catches that before the CID goes on-chain. We ran this against the file above with jaq 3.1.1, a jq-compatible tool:

$ jq -e '(.type == "https://eips.ethereum.org/EIPS/eip-8004#registration-v1") and (.name|type=="string") and (.services|type=="array") and (.active|type=="boolean")' registration.json
true

With services set to a plain string, the same kind of check prints false and exits with status 1, so you can use it to stop a script.

3. Pin it and fetch it back. Pin the file like any other JSON, then load the CID through a gateway and confirm the bytes match before you spend gas. A pin that is still queued or failed is far cheaper to catch here than after the registration transaction.

4. Register, then fill in registrations. The registry exposes three versions of register, and the one with no arguments matters most for pinning:

function register(string agentURI, MetadataEntry[] calldata metadata) external returns (uint256 agentId)
function register(string agentURI) external returns (uint256 agentId)
function register() external returns (uint256 agentId)  // agentURI is added later with setAgentURI()
function setAgentURI(uint256 agentId, string calldata newURI) external

The EIP says an agent SHOULD list at least one registration, made of its agentId and an agentRegistry string such as eip155:1:0x742.... You only learn the agentId after registering, and editing the file changes its CID. So if you register with a URI first, you will pin twice and call setAgentURI once. Calling register() with no URI, then writing the complete file, pinning it once and calling setAgentURI, gets you the same result with a single pin.

The agentURI may also use https:// or a base64 data: URI. An ipfs:// CID is the option where anyone can check that the file they fetched is the file you registered, which is why it has to stay pinned for as long as the agent exists.

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.

How do I pin an ERC-8004 registration file? Build the JSON the EIP defines, validate it locally, pin it, fetch it back through a gateway, and only then reference ipfs://<CID> as the agent's URI in register() or setAgentURI().

Can I update a registration file after it is pinned? Not in place. Any change produces a new CID, so you pin the new version and call setAgentURI() with the new ipfs:// URI.

Related Reading

• How AIOZ Pin Works: Pinning, Gateways, and NFT Tools - the pinNft() and gateway mechanics this pillar builds on
• How to Mint NFTs with Persistent Metadata on AIOZ Pin - the same pin-then-reference workflow applied to a different identity token
• AIOZ Pin AI Agent Setup: MCP Server and llms.txt Guide - the other AI-agent entry point on AIOZ Pin: reference docs for assistants to read, and an MCP server for them to call

References

• ERC-8004: Trustless Agents (official EIP)
• Pinata: What Is ERC-8004?