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.mdto its URL, or by requesting it withAccept: 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:
VerificationBadge, ValidationScore, and ValidationList will build and test end-to-end on Sepolia. On mainnet, validation queries return empty by design, not because something is broken. Components must render an informative empty state rather than an error.AgentStats is a pre-computed summary entity (totals, averages, last activity) that the subgraph maintains as events come in. It's confirmed on Ethereum Sepolia but may be absent on other deployments. Four components rely on it exclusively — ReputationScore, VerificationBadge, ValidationScore, and LastActivity. These components treat a missing entity as an empty state rather than an error, so they'll fall back gracefully on chains without it.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
Agent Identity: agentRegistry + agentId
Every component takes two props that together uniquely identify an agent across any chain:
A string in the format eip155:{chainId}:{contractAddress}. Breaking it down:
eip155— namespace meaning it's an Ethereum-compatible chainchainId— identifies which blockchain (1 = Ethereum, 8453 = Base, etc.)contractAddress— where the Identity Registry smart contract is deployed
The ERC-721 token ID — the unique number assigned to this agent when it registered.
Example: agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" + agentId={2290} means "agent #2290 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={2290} />Via AgentProvider — cleaner when rendering multiple components for the same agent:
<AgentProvider agentRegistry="eip155:8453:0x..." agentId={2290}>
<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
Note: AgentStats — the entity that powers ReputationScore, VerificationBadge, ValidationScore, and LastActivity — is not present on every chain's subgraph. It's confirmed on Ethereum Sepolia. Affected components will render their empty state on chains without it.
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.