# Introduction

> **NOTE — unofficial library.** `@p4n/erc8004-ui` is an independent, community-built project. It is not affiliated with, maintained by, or endorsed by the authors of ERC-8004. It reads the standard's on-chain data through public subgraphs; it does not speak for the standard.

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.
- **The Validation Registry isn't deployed anywhere yet** — The subgraph's `Protocol` entity records the registry addresses per chain, 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 on every chain today. Verified 2026-09-04 across Ethereum, Base, Polygon, BNB Smart Chain, BNB Chapel and Base Sepolia.
- **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.

## Reference

- Live page: https://erc8004-ui.vercel.app/docs/introduction
- Markdown source: https://erc8004-ui.vercel.app/docs/introduction.md