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.
Introduction
Drop-in React components for displaying verified AI agent data from the ERC-8004 standard — built for developers who don't want to become Subgraph experts.
Why this exists
ERC-8004 is spreading across chains faster than the tooling around it. Teams building on the standard end up writing the same plumbing over and over — subgraph queries, chain-prefixed identifiers, three different URI formats, revoked-feedback filtering — before they can render a single agent name on screen.
This library is the layer in between. You pass an agent's on-chain ID, you get a component that works. The point is to make ERC-8004 feel like any other API a frontend developer already knows how to consume.
Why use this library?
Displaying ERC-8004 agent data looks straightforward — fetch some fields, render them. In practice, the Subgraph has enough quirks that AI-generated components will silently get things wrong. Not because the AI is bad at React, but because the domain-specific rules aren't in any training data.
Feedback value has no universal scale
Different agents receive scores on different ranges. You can't treat it like a standard 1–5 star rating without knowing the context.
Tags aren't pre-aggregated
tag1 and tag2 on each feedback entry aren't counted anywhere. You have to fetch all feedback and compute frequencies client-side.
The deployed schema drifts from the docs
The schema reference used in this library was captured from an actual Subgraph introspection query — not the SDK docs or the GitHub README.
agentURI needs three resolution paths
The registration file URI can be IPFS, HTTPS, or a base64 data URI. Each requires different handling.
Revoked feedback must be filtered
isRevoked: false needs to be in every feedback query. A component that omits it will silently include retracted reviews.
Pagination is offset-based, not cursor-based
The Subgraph uses first/skip, not a cursor. Deep pagination gets expensive and has known limitations.
Chain ID → Subgraph endpoint mapping
Each chain has a different Subgraph deployment ID, and every request needs your API key injected into the URL.
Validation Registry isn't on mainnet yet
The smart contracts are only deployed on testnets (Sepolia confirmed). The subgraph schema supports validation entities across all deployments, so 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 isn't present on every subgraph
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.
Four states per component
Every component needs loading, error, empty, and not-found states handled — not just the happy path.
Every component in this library handles all of this internally. You pass two identifiers and get a working UI backed by verified on-chain data. Queries are minimal per-component — ReputationScore fetches 2 fields, not 20+. Caching and request deduplication are automatic via TanStack Query, so multiple components targeting the same agent share a single network request.