For the complete documentation index, see /llms.txt. A single-fetch full bundle is at /llms-full.txt. Every docs page is also available as Markdown by appending .md to its URL, or by requesting it with Accept: text/markdown.

Concepts

What you need to know about ERC-8004 to use this library — no protocol deep-dive required.

What is ERC-8004?

ERC-8004 is an Ethereum standard for on-chain AI agent identity. It lets agents register themselves on the blockchain with a name, description, image, and service endpoints — and lets users leave feedback and validations. Think of it like a public profile + review system for AI agents, but the data lives on-chain so it can't be faked.

Why use this library?

For the specific Subgraph quirks this library handles on your behalf, see the Introduction. Two gaps in the underlying data are worth flagging up front, since they shape the empty states you'll see:

The Validation Registry isn't deployed anywhere yet
The subgraph records each chain's registry addresses, and validationRegistry is the zero address on every chain checked — testnets included. The schema still exposes validations, so these queries succeed and return nothing: VerificationBadge, ValidationScore, ValidationList and ValidationDisplay render their empty state everywhere. A query root existing is not evidence the registry is live. Components must render an informative empty state rather than an error.

The Three Registries

Identity Registry

Like a business registration. Each agent gets an NFT (ERC-721 token) with a registration file containing its name, description, image, and service endpoints. This is where "who is this agent?" data lives.

Components: AgentName, AgentImage, AgentDescription, AgentCard, EndpointStatus

Reputation Registry

Like a review system. Users who interact with an agent can leave feedback — a score, tags describing what the agent does well, and optional written reviews. This is where "is this agent any good?" data lives.

Components: ReputationScore, ReputationTimeline, ReputationDistribution, FeedbackList, TagCloud

Validation Registry

Like a certification body. Independent third-party verifiers can assess an agent and record a score (0–100). This is where "has this agent been independently verified?" data lives.

Components: VerificationBadge, ValidationScore, ValidationList

Warning
Not deployed on any chain yet — validationRegistry is the zero address everywhere, testnets included. These components render their empty state on every chain.

Agent Identity: agentRegistry + agentId

Every component takes two props that together uniquely identify an agent across any chain:

agentRegistry

A string in the format eip155:{chainId}:{contractAddress}. Breaking it down:

  • eip155 — namespace meaning it's an Ethereum-compatible chain
  • chainId — identifies which blockchain (1 = Ethereum, 8453 = Base, etc.)
  • contractAddress — where the Identity Registry smart contract is deployed
agentId

The ERC-721 token ID — the unique number assigned to this agent when it registered.

Example: agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" + agentId={888} means "agent #888 on the Base blockchain."

Two Ways to Pass Identifiers

Components accept identifiers two ways:

Directly as props — fine for a single component:

<ReputationScore agentRegistry="eip155:8453:0x..." agentId={888} />

Via AgentProvider — cleaner when rendering multiple components for the same agent:

<AgentProvider agentRegistry="eip155:8453:0x..." agentId={888}>
  <AgentCard />
  <ReputationScore />
  <FeedbackList />
</AgentProvider>

Props on individual components override the provider, so you can mix both patterns when needed.

Trustless Data

Components never accept display data as props. You only pass identifiers — the component fetches verified data from the blockchain internally. This means the data you see is guaranteed to be real on-chain data, not something that could be spoofed by a developer passing fake props.

This differs from a typical React component where you'd pass something like <AgentCard name="Alice" score={4.8} /> — those values could be anything the developer types. Here, the component fetches name and score itself from on-chain data, so what's displayed is what's actually registered.

Supported Chains

Ethereum Mainnet1
Base Mainnet8453
Polygon Mainnet137
BSC Mainnet56
Monad Mainnet143
Base Sepolia— testnet84532
BSC Chapel— testnet97
Monad Testnet— testnet10143

Where the Data Comes From

All data is fetched from The Graph — a decentralised indexing service that watches the blockchain, extracts ERC-8004 events, and serves them via fast GraphQL queries. You don't need to understand GraphQL to use this library — components handle all queries internally. You just need a free API key from The Graph.