# @erc8004/ui — Full Documentation Bundle

> Drop-in React components for displaying verified ERC-8004 AI agent identity, reputation, and validation data. Self-contained, trustless, and designed to be consumed by AI coding agents.

**NOTE — provisional package name.** This library is not yet published to npm. `@erc8004/ui` is a placeholder used in code examples — the final package name has not been chosen and will likely differ. Until publication, install directly from GitHub: https://github.com/p4nthera115/erc8004-ui. Once published, this notice will disappear and all code examples will reflect the real package name.

This file contains the complete guides and component reference for @erc8004/ui, generated from the canonical registries. For an indexed version with per-page links, see https://erc8004-ui.vercel.app/llms.txt.

---

## Quick Start

The package is not yet on npm. Install peer dependencies normally and add the library directly from GitHub:

```bash
npm install react react-dom @tanstack/react-query
npm install github:p4nthera115/erc8004-ui
```

The import path `@erc8004/ui` shown below is provisional and will change once the package is published under its real name.

```tsx
import { ERC8004Provider, ReputationScore } from "@erc8004/ui"

function App() {
  return (
    <ERC8004Provider apiKey="your-graph-api-key">
      <ReputationScore
        agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432"
        agentId={2290}
      />
    </ERC8004Provider>
  )
}
```

Get a free Graph API key at https://thegraph.com/studio. It is a read-only query key, safe to use in frontend code.

---

## Guides

# Introduction

> **NOTE — provisional package name.** This library is not yet published to npm. `@erc8004/ui` is a placeholder used in code examples — the final package name has not been chosen and will likely differ. Until publication, install directly from GitHub: https://github.com/p4nthera115/erc8004-ui. Once published, this notice will disappear and all code examples will reflect the real package name.

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.

## Reference

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

---

# Installation

> **NOTE — provisional package name.** This library is not yet published to npm. `@erc8004/ui` is a placeholder used in code examples — the final package name has not been chosen and will likely differ. Until publication, install directly from GitHub: https://github.com/p4nthera115/erc8004-ui. Once published, this notice will disappear and all code examples will reflect the real package name.

Install the package, add peer dependencies, and configure your Graph API key — then drop any component into your app with a single import.

## Install

```bash
npm install @erc8004/ui
```

or

```bash
pnpm add @erc8004/ui
yarn add @erc8004/ui
```

## Peer Dependencies

The library requires React and TanStack Query as peer dependencies:

```bash
npm install react react-dom @tanstack/react-query
```

Requires React 18 or 19, and `@tanstack/react-query` v5.

If you already have React in your project, you only need to add `@tanstack/react-query`. TanStack Query handles caching and deduplication so multiple components on the same page don't make redundant network requests.

## Get a Graph API Key

Components fetch agent data from [The Graph](https://thegraph.com/studio/), a blockchain indexing service. Sign up at [thegraph.com/studio](https://thegraph.com/studio/) to get a free API key. There is a generous free tier — no credit card required for development.

This is a **read-only query key** for usage tracking — it's safe to use in frontend code. It does not grant write access to anything.

## Minimal Working Example

```tsx
import { ERC8004Provider, ReputationScore } from "@erc8004/ui"

function App() {
  return (
    <ERC8004Provider apiKey="your-graph-api-key">
      <ReputationScore
        agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432"
        agentId={2290}
      />
    </ERC8004Provider>
  )
}
```

The component handles all data fetching internally. `ERC8004Provider` auto-creates a TanStack Query client if you haven't set one up.

> In production, load the API key from an environment variable rather than hardcoding it:

```tsx
// Vite
apiKey={import.meta.env.VITE_GRAPH_API_KEY}

// Next.js
apiKey={process.env.NEXT_PUBLIC_GRAPH_API_KEY}
```

Graph API keys are safe in frontend code (see [API Keys](https://erc8004-ui.vercel.app/docs/api-keys)) — env vars are about keeping keys out of your repo and swappable per environment.

## If You Already Use TanStack Query

Wrap with your own `QueryClientProvider`. `ERC8004Provider` detects an existing QueryClient and shares it — no duplicate clients, no wasted cache.

```tsx
import { QueryClient, QueryClientProvider } from "@tanstack/react-query"
import { ERC8004Provider, ReputationScore } from "@erc8004/ui"

const queryClient = new QueryClient()

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <ERC8004Provider apiKey="your-graph-api-key">
        <ReputationScore
          agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432"
          agentId={2290}
        />
      </ERC8004Provider>
    </QueryClientProvider>
  )
}
```

## Using AgentProvider for Profile Pages

When rendering multiple components for the same agent, use `AgentProvider` to avoid repeating `agentRegistry` and `agentId` on every component. Individual components can still override with their own props.

```tsx
import { AgentProvider, AgentCard, ReputationScore, FeedbackList } from "@erc8004/ui"

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

## Troubleshooting

- **Nothing renders, no errors.** Check that components are wrapped in `<ERC8004Provider>`. Verify `agentRegistry` matches the format `eip155:{chainId}:{contractAddress}` exactly.
- **"Failed to fetch" or 401/403 errors.** Your Graph API key is missing, invalid, or rate-limited. Double-check the key in your provider matches the one from the Graph Studio dashboard.
- **Component shows "not found" state.** The `agentId` doesn't exist on the chain specified by `agentRegistry`. Verify the chain ID in the registry string matches where the agent is actually registered.
- **Multiple components re-fetching the same data.** Ensure a single `QueryClient` instance is used (or let `ERC8004Provider` create one). A new `QueryClient` on every render defeats caching.

## Next Steps

- [Concepts](https://erc8004-ui.vercel.app/docs/concepts) — understand what `agentRegistry` and `agentId` mean.
- [Components](https://erc8004-ui.vercel.app/docs/components) — browse all available components with live previews.

## Reference

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

---

# Concepts

> **NOTE — provisional package name.** This library is not yet published to npm. `@erc8004/ui` is a placeholder used in code examples — the final package name has not been chosen and will likely differ. Until publication, install directly from GitHub: https://github.com/p4nthera115/erc8004-ui. Once published, this notice will disappear and all code examples will reflect the real package name.

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](https://erc8004-ui.vercel.app/docs/introduction). Two gaps in the underlying data are worth flagging up front, since they shape the empty states you'll see:

> **Warning — 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.

> **Note — 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.

## 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 yet deployed to any mainnet chain. Testnet (Sepolia) only. Components return empty on mainnet.

## 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={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:

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

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

```tsx
<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

| Chain | ID |
| --- | --- |
| Ethereum Mainnet | 1 |
| Base Mainnet | 8453 |
| Polygon Mainnet | 137 |
| BSC Mainnet | 56 |
| Monad Mainnet | 143 |
| Ethereum Sepolia (testnet) | 11155111 |
| Base Sepolia (testnet) | 84532 |
| BSC Chapel (testnet) | 97 |
| Monad Testnet (testnet) | 10143 |

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](https://thegraph.com) — 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.

## Reference

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

---

# API Keys

> **NOTE — provisional package name.** This library is not yet published to npm. `@erc8004/ui` is a placeholder used in code examples — the final package name has not been chosen and will likely differ. Until publication, install directly from GitHub: https://github.com/p4nthera115/erc8004-ui. Once published, this notice will disappear and all code examples will reflect the real package name.

Components fetch agent data from The Graph, a blockchain indexing service. You need a free API key to authenticate your requests.

## How to Get One

1. Go to [thegraph.com/studio](https://thegraph.com/studio/) and create an account.
2. Create an API key in the dashboard.
3. Copy the key.
4. Pass it to `ERC8004Provider`.

```tsx
<ERC8004Provider apiKey="your-graph-api-key">
  {/* your components */}
</ERC8004Provider>
```

## Is It Safe to Use in Frontend Code?

Yes. Graph API keys are read-only query keys — they only authorise GraphQL reads against Subgraphs. They cannot modify any on-chain data, they cannot write to any database, and they cannot access anything outside your Subgraph queries. Their only purpose is usage tracking and rate limiting.

This is the same pattern used by every dApp that queries The Graph, including most major DeFi protocols. Exposing the key in frontend code is expected and safe.

## Free Tier

The Graph offers a free tier that's sufficient for development and moderate production use. Sign in to [the Graph Studio dashboard](https://thegraph.com/studio/) to view current limits and usage for your key.

## Custom Subgraph Endpoint

If you run your own Subgraph or use a different indexer, use the `subgraphOverrides` prop on `ERC8004Provider` to override the default endpoint for any chain:

```tsx
<ERC8004Provider
  apiKey="your-key"
  subgraphOverrides={{
    1: "https://your-custom-subgraph.com/ethereum",
    8453: "https://your-custom-subgraph.com/base",
  }}
>
```

Keys are chain IDs. Overrides apply per-chain — chains not listed fall back to the default Graph endpoints.

## Reference

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

---

# Components

> **NOTE — provisional package name.** This library is not yet published to npm. `@erc8004/ui` is a placeholder used in code examples — the final package name has not been chosen and will likely differ. Until publication, install directly from GitHub: https://github.com/p4nthera115/erc8004-ui. Once published, this notice will disappear and all code examples will reflect the real package name.

All components in the library, grouped by registry. Each component fetches its own data — pass two identifiers and it works.

Every data component handles loading, error, empty, and not-found states internally. You pass `agentRegistry` and `agentId` (or rely on an enclosing `AgentProvider`) and the component does the rest.

### Providers

- [ERC8004Provider](https://erc8004-ui.vercel.app/docs/components/erc8004-provider.md): Root context provider that holds infrastructure config — your Graph API key and optional subgraph URL overrides.
- [AgentProvider](https://erc8004-ui.vercel.app/docs/components/agent-provider.md): Optional convenience wrapper that sets a default agentRegistry and agentId for all child components.

### Identity

- [AgentName](https://erc8004-ui.vercel.app/docs/components/agent-name.md): Fetches and renders the agent's registered name from the identity registry.
- [AgentImage](https://erc8004-ui.vercel.app/docs/components/agent-image.md): Renders the agent's registered image.
- [AgentDescription](https://erc8004-ui.vercel.app/docs/components/agent-description.md): Renders the agent's registered description text from the identity registry.
- [AgentCard](https://erc8004-ui.vercel.app/docs/components/agent-card.md): Composed identity card combining avatar, name, description, owner address, and active protocol badges in a single component.
- [EndpointStatus](https://erc8004-ui.vercel.app/docs/components/endpoint-status.md): Lists all registered service endpoints (MCP, A2A, OASF, web, email) with protocol labels and optional live health check indicators.

### Reputation

- [ReputationScore](https://erc8004-ui.vercel.app/docs/components/reputation-score.md): Compact inline badge showing the agent's average feedback score and total review count.
- [ReputationTimeline](https://erc8004-ui.vercel.app/docs/components/reputation-timeline.md): Sparkline chart showing how the agent's feedback scores have trended over time.
- [ReputationDistribution](https://erc8004-ui.vercel.app/docs/components/reputation-distribution.md): Score distribution histogram showing the spread of feedback values across configurable score ranges.
- [FeedbackList](https://erc8004-ui.vercel.app/docs/components/feedback-list.md): Paginated list of individual feedback entries with score, tag pills, reviewer address, timestamp, and optional written review text.
- [TagCloud](https://erc8004-ui.vercel.app/docs/components/tag-cloud.md): Weighted tag pills showing the agent's most frequent feedback tags.

### Validation

- [VerificationBadge](https://erc8004-ui.vercel.app/docs/components/verification-badge.md): Compact inline badge showing the agent's verification tier derived from completed validations and average validation score.
- [ValidationScore](https://erc8004-ui.vercel.app/docs/components/validation-score.md): Average validation score (0-100) with a fill bar and completed/pending counts.
- [ValidationList](https://erc8004-ui.vercel.app/docs/components/validation-list.md): Paginated list of individual validation entries with score, status, tag, validator address, and timestamp.
- [ValidationDisplay](https://erc8004-ui.vercel.app/docs/components/validation-display.md): Composed view combining VerificationBadge, ValidationScore, and ValidationList into a single unified validation panel.

### Activity

- [LastActivity](https://erc8004-ui.vercel.app/docs/components/last-activity.md): Cross-registry relative timestamp showing when the agent was last active (e.g.
- [ActivityLog](https://erc8004-ui.vercel.app/docs/components/activity-log.md): Chronological feed of all on-chain events across all registries — feedback and validations merged and sorted by time.


## Reference

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

---

# Theming

> **NOTE — provisional package name.** This library is not yet published to npm. `@erc8004/ui` is a placeholder used in code examples — the final package name has not been chosen and will likely differ. Until publication, install directly from GitHub: https://github.com/p4nthera115/erc8004-ui. Once published, this notice will disappear and all code examples will reflect the real package name.

`@erc8004/ui` uses CSS variables for theming. This gives you a set of named color and radius tokens that every component references. Override those tokens in your CSS to change the look of the entire library without touching component code.

Out of the box, the library ships with a light theme and a dark theme. No configuration required — just import the stylesheet and go. Colors use OKLCH rather than hex. OKLCH is perceptually uniform — lightening or darkening a value produces a predictable visual shift, which makes themes easier to build and tweak.

```tsx
import "@erc8004/ui/styles.css"
```

## OKLCH Color Format

All color tokens are raw [OKLCH](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklch) values — three space-separated numbers for `lightness chroma hue`:

- **Lightness** — `0` (black) to `1` (white).
- **Chroma** — saturation. `0` is gray, higher values are more vivid.
- **Hue** — color angle in degrees. `260` blue, `145` green, `300` purple, `25` red-orange.

For neutral grays, chroma and hue are both `0` (e.g., `0.556 0 0` is a medium gray). Use [oklch.com](https://oklch.com) to pick values interactively.

## Playground

An interactive playground for previewing presets and seeing live token changes is available on the live site at https://erc8004-ui.vercel.app/docs/theming. The CSS shown there is exactly what you would write to reproduce a theme in your own app.

## How It Works

Every component in the library uses Tailwind classes like `bg-erc8004-card` and `text-erc8004-muted-fg` instead of hardcoded colors. These classes reference CSS variables defined under the `.erc8004` scope — a wrapper that the `ERC8004Provider` renders automatically.

Because the variables are scoped to `.erc8004`, they never conflict with your app's own styles. If your app uses shadcn, Tailwind's default palette, or any other styling system, everything coexists cleanly. Dark and light mode work by swapping the variable values when a `.dark` or `.light` class is present on an ancestor — see [Dark and Light Mode](#dark-and-light-mode) below.

## Three Ways to Customize

Pick the broadest method that does the job. Use CSS variables to retheme everything, provider `className` to scope a theme to a section of your app, or component `className` for one-off tweaks.

### Option 1 — CSS Variable Overrides — retheme everything

Override the variables in your own stylesheet. Every component picks up the changes instantly.

```css
/* your-app.css */
.erc8004 {
  --erc8004-accent: 0.55 0.25 300;   /* purple instead of blue */
  --erc8004-radius: 0.75rem;          /* rounder corners */
}
```

### Option 2 — Provider `className` — scope a theme to a subtree

The provider accepts a `className` prop that gets merged onto the `.erc8004` wrapper. Two common uses:

**Toggle light or dark mode:**

```tsx
<ERC8004Provider apiKey="..." className="dark">
  {/* dark theme active for all components inside */}
</ERC8004Provider>

<ERC8004Provider apiKey="..." className="light">
  {/* forces light theme, even inside a .dark ancestor */}
</ERC8004Provider>
```

**Apply a custom theme class:**

```css
/* Define a custom theme class */
.erc8004.my-brand {
  --erc8004-accent: 0.55 0.25 300;
  --erc8004-radius: 0.75rem;
}
```

```tsx
<ERC8004Provider apiKey="..." className="my-brand">
  {/* all components inside use the custom theme */}
</ERC8004Provider>
```

### Option 3 — Component `className` — one-off tweaks

Every component accepts a `className` prop. Your classes override the component's defaults when they target the same CSS property — padding replaces padding, background replaces background.

```tsx
<ReputationScore
  agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432"
  agentId={2290}
  className="shadow-lg rounded-2xl p-6"
/>
```

## Token Convention

Tokens follow a **background / foreground pair** pattern. The base token controls the surface color, and the `-fg` suffixed token controls the text and icon color that sits on that surface.

For example, given these variables:

```css
.erc8004 {
  --erc8004-card: 1 0 0;          /* white surface */
  --erc8004-card-fg: 0.145 0 0;   /* near-black text */
}
```

A component using `bg-erc8004-card text-erc8004-card-fg` will render dark text on a white card. Override the variables, and the component adapts — you never need to change the component itself.

## Dark and Light Mode

The default theme is light — no setup needed. Adding a `.dark` ancestor class switches components to dark mode. This is the standard Tailwind dark mode convention that most apps already use.

```html
<body class="dark">
  <!-- ERC8004 components automatically use dark colors -->
</body>
```

Adding a `.light` ancestor class explicitly forces light mode, even inside a `.dark` parent. This is useful for embedding components in a light section of an otherwise-dark app.

```html
<body class="dark">
  <!-- dark everywhere... -->

  <div class="light">
    <!-- ...except these components stay light -->
    <ERC8004Provider apiKey="...">
      <ReputationScore agentRegistry="..." agentId={2290} />
    </ERC8004Provider>
  </div>
</body>
```

Either class can go on the `body` tag, a container `div`, or directly on `ERC8004Provider` via the `className` prop. If your app already handles dark mode by toggling a `.dark` class, the library follows along automatically.

**Overriding dark mode colors**

To customize specific colors in dark mode, target `.dark .erc8004`:

```css
.dark .erc8004 {
  --erc8004-accent: 0.7 0.2 260;      /* brighter blue in dark mode */
  --erc8004-card: 0.18 0.01 260;      /* slight blue tint to cards */
}
```

**Overriding light mode colors**

Similarly, to customize colors only in explicit light mode, target `.light .erc8004`:

```css
.light .erc8004 {
  --erc8004-accent: 0.5 0.22 260;     /* deeper blue in light mode */
  --erc8004-card: 0.98 0.005 80;      /* warm white cards */
}
```

## Token Reference

**Surfaces**

| Token | CSS Variable | Default (Light) | What it controls |
| --- | --- | --- | --- |
| Background | `--erc8004-bg` | `1 0 0` | Default component background |
| Foreground | `--erc8004-fg` | `0.145 0 0` | Default text color |
| Card | `--erc8004-card` | `1 0 0` | Elevated surface background (cards, panels) |
| Card foreground | `--erc8004-card-fg` | `0.145 0 0` | Text on elevated surfaces |
| Muted | `--erc8004-muted` | `0.97 0 0` | Subtle backgrounds (tags, skeletons, empty states) |
| Muted foreground | `--erc8004-muted-fg` | `0.556 0 0` | Secondary text (timestamps, descriptions, helper text) |

**Accent**

| Token | CSS Variable | Default (Light) | What it controls |
| --- | --- | --- | --- |
| Accent | `--erc8004-accent` | `0.55 0.2 260` | Brand color, primary actions, active highlights |
| Accent foreground | `--erc8004-accent-fg` | `0.985 0 0` | Text on accent surfaces |

**Semantic**

| Token | CSS Variable | Default (Light) | What it controls |
| --- | --- | --- | --- |
| Positive | `--erc8004-positive` | `0.55 0.17 145` | Positive scores, success indicators |
| Positive foreground | `--erc8004-positive-fg` | `0.985 0 0` | Text on positive surfaces |
| Negative | `--erc8004-negative` | `0.55 0.2 25` | Negative scores, error states |
| Negative foreground | `--erc8004-negative-fg` | `0.985 0 0` | Text on negative surfaces |

**Borders & Focus**

| Token | CSS Variable | Default (Light) | What it controls |
| --- | --- | --- | --- |
| Border | `--erc8004-border` | `0.922 0 0` | All borders and dividers |
| Ring | `--erc8004-ring` | `0.55 0.2 260` | Focus ring on interactive elements |

**Chart Palette**

| Token | CSS Variable | Default (Light) | What it controls |
| --- | --- | --- | --- |
| Chart 1 | `--erc8004-chart-1` | `0.55 0.2 260` | First chart color (blue) |
| Chart 2 | `--erc8004-chart-2` | `0.6 0.18 145` | Second chart color (green) |
| Chart 3 | `--erc8004-chart-3` | `0.6 0.2 25` | Third chart color (red-orange) |
| Chart 4 | `--erc8004-chart-4` | `0.65 0.2 310` | Fourth chart color (purple) |
| Chart 5 | `--erc8004-chart-5` | `0.7 0.15 70` | Fifth chart color (gold) |

**Radius**

| Token | CSS Variable | Default | What it controls |
| --- | --- | --- | --- |
| Radius | `--erc8004-radius` | `0.5rem` | Base corner radius — all sizes derive from this |

## Radius Scale

The library derives a set of radius sizes from the single `--erc8004-radius` base value:

| Class | Size | Formula |
| --- | --- | --- |
| `rounded-erc8004-sm` | 0.3rem | radius × 0.6 |
| `rounded-erc8004-md` | 0.4rem | radius × 0.8 |
| `rounded-erc8004-lg` | 0.5rem | radius × 1.0 (the base) |
| `rounded-erc8004-xl` | 0.7rem | radius × 1.4 |
| `rounded-erc8004-2xl` | 0.9rem | radius × 1.8 |

Change `--erc8004-radius` once, and the entire radius scale updates proportionally:

```css
.erc8004 {
  --erc8004-radius: 0.75rem;  /* everything gets rounder */
}
```

```css
.erc8004 {
  --erc8004-radius: 0;  /* sharp corners everywhere */
}
```

## Examples

**Match your brand color**

```css
.erc8004 {
  --erc8004-accent: 0.55 0.25 300;      /* purple */
  --erc8004-ring: 0.55 0.25 300;        /* focus rings match */
}
```

**Warm neutral palette**

```css
.erc8004 {
  --erc8004-bg: 0.98 0.005 80;          /* warm white */
  --erc8004-card: 0.96 0.008 80;        /* warm off-white */
  --erc8004-muted: 0.94 0.01 80;        /* warm gray */
  --erc8004-border: 0.9 0.01 80;        /* warm border */
}
```

**Compact with sharp corners**

```tsx
<ReputationScore
  agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432"
  agentId={2290}
  className="p-2 text-sm rounded-none"
/>
```

**Full custom theme via CSS class**

```css
/* teal-brand.css */
.erc8004.teal-brand {
  --erc8004-accent: 0.6 0.22 160;       /* teal */
  --erc8004-positive: 0.6 0.22 160;     /* match accent for positive */
  --erc8004-negative: 0.55 0.2 0;       /* warm red */
  --erc8004-border: 0.88 0.01 160;      /* subtle teal borders */
  --erc8004-radius: 1rem;               /* very rounded */
}
```

```tsx
<ERC8004Provider apiKey="your-graph-api-key" className="teal-brand">
  {/* all components use the teal theme */}
</ERC8004Provider>
```

## Provider Props

The only theming-relevant prop on `ERC8004Provider` is `className`, which gets merged onto the `.erc8004` wrapper. See the [ERC8004Provider component page](https://erc8004-ui.vercel.app/docs/components/erc8004-provider) for the full prop reference.

```tsx
<ERC8004Provider apiKey="..." className="dark my-theme">
  {children}
</ERC8004Provider>
```

## FAQ

**Does the library ship its own font?**

No. Components inherit `font-family` from their parent, so they adopt whatever typography your app uses. Set the font on `.erc8004` or any ancestor and components will follow. Some elements like numeric scores and addresses use monospace (`font-mono`) for readability, but no base font is bundled or required.

**Can I force light mode inside a dark app?**

Yes. Add `className="light"` to the provider (or any ancestor of the components you want to stay light). This works even when a higher ancestor has `.dark` set.

**Will this conflict with my app's Tailwind config?**

No. All tokens are namespaced under `erc8004-` and scoped to the `.erc8004` class. They don't touch your app's `--primary`, `--background`, or any other standard Tailwind/shadcn variables.

**Do I need Tailwind in my project to use `className`?**

Not strictly — `className` accepts any CSS class string. But the library is built with Tailwind, so overriding with Tailwind classes gives you the most predictable results since `tailwind-merge` understands the conflict resolution. If your project doesn't use Tailwind, you can still pass regular CSS classes or use the CSS variable overrides instead.

**Can I theme individual components differently?**

Yes. Wrap a subset of components in a `div` with overridden variables:

```tsx
<ERC8004Provider apiKey="...">
  {/* These use the default theme */}
  <ReputationScore agentRegistry="..." agentId={1} />

  {/* These use a custom accent */}
  <div style={{ "--erc8004-accent": "0.55 0.25 300" } as React.CSSProperties}>
    <ReputationScore agentRegistry="..." agentId={2} />
    <FeedbackList agentRegistry="..." agentId={2} />
  </div>
</ERC8004Provider>
```

Since CSS variables inherit downward, any `div` that redefines a variable creates a new scope for its children.

**What color format should I use?**

Raw OKLCH values: three space-separated numbers for lightness, chroma, and hue. For example, `0.55 0.2 260` is a medium-brightness blue. You can use any OKLCH color picker to find values. For grays, set chroma and hue to `0` (e.g., `0.5 0 0` is medium gray).

## Reference

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

---

## Components

## Providers

# ERC8004Provider

**Slug:** `erc8004-provider`  
**Import:** `import { ERC8004Provider } from "@erc8004/ui"`

> **NOTE — provisional package name.** This library is not yet published to npm. `@erc8004/ui` is a placeholder used in code examples — the final package name has not been chosen and will likely differ. Until publication, install directly from GitHub: https://github.com/p4nthera115/erc8004-ui. Once published, this notice will disappear and all code examples will reflect the real package name.

## Description

Root context provider that holds infrastructure config — your Graph API key and optional subgraph URL overrides. Wrap your app once at the top level. Automatically creates an internal QueryClient if TanStack Query is not already set up in your app.

## Usage

```tsx
import { ERC8004Provider } from "@erc8004/ui"
import { ERC8004Provider } from "@erc8004/ui"

// Minimal setup — no TanStack Query knowledge required:
function App() {
  return (
    <ERC8004Provider apiKey="your-graph-api-key">
      {/* your app */}
    </ERC8004Provider>
  )
}

// If you already use TanStack Query, ERC8004Provider detects it
// and shares the existing cache — no duplicate clients:
import { QueryClient, QueryClientProvider } from "@tanstack/react-query"

const queryClient = new QueryClient()

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <ERC8004Provider apiKey="your-graph-api-key">
        {/* your app */}
      </ERC8004Provider>
    </QueryClientProvider>
  )
}
```

## API Reference

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `apiKey` | `string` | yes | — | Your Graph API key. Used to authenticate Subgraph requests. Safe to use in frontend code — read-only. |
| `subgraphOverrides` | `Record<number, string>` | no | — | Optional map of chainId → custom Subgraph URL. Overrides the default endpoint for that chain. |
| `className` | `string` | no | — | Optional CSS classes merged onto the .erc8004 wrapper. Use for scoping dark mode (.dark) or custom layout. |
| `children` | `ReactNode` | yes | — | Your application tree. |

## Reference

- Live preview & full docs: https://erc8004-ui.vercel.app/docs/components/erc8004-provider
- Markdown source: https://erc8004-ui.vercel.app/docs/components/erc8004-provider.md

---

# AgentProvider

**Slug:** `agent-provider`  
**Import:** `import { AgentProvider } from "@erc8004/ui"`

> **NOTE — provisional package name.** This library is not yet published to npm. `@erc8004/ui` is a placeholder used in code examples — the final package name has not been chosen and will likely differ. Until publication, install directly from GitHub: https://github.com/p4nthera115/erc8004-ui. Once published, this notice will disappear and all code examples will reflect the real package name.

## Description

Optional convenience wrapper that sets a default agentRegistry and agentId for all child components. Eliminates prop repetition on profile pages. Components inside can still override with their own props.

## Usage

```tsx
import { AgentProvider } from "@erc8004/ui"
import { AgentProvider, AgentName, ReputationScore, FeedbackList } from "@erc8004/ui"

// Profile page — one agent, many components, no repetition:
<AgentProvider agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" agentId={2290}>
  <AgentName />
  <ReputationScore />
  <FeedbackList />
</AgentProvider>

// Override one component inside the provider:
<AgentProvider agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" agentId={2290}>
  <AgentName />
  <AgentName agentRegistry="eip155:1:0x999..." agentId={12} />
</AgentProvider>
```

## API Reference

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `agentRegistry` | `string` | yes | — | Agent registry identifier in the format "eip155:{chainId}:{contractAddress}". |
| `agentId` | `number` | yes | — | ERC-721 token ID of the agent. |
| `children` | `ReactNode` | yes | — | Components that will inherit this agent identity. |

## Reference

- Live preview & full docs: https://erc8004-ui.vercel.app/docs/components/agent-provider
- Markdown source: https://erc8004-ui.vercel.app/docs/components/agent-provider.md

---

## Identity

# AgentName

**Slug:** `agent-name`  
**Import:** `import { AgentName } from "@erc8004/ui"`

> **NOTE — provisional package name.** This library is not yet published to npm. `@erc8004/ui` is a placeholder used in code examples — the final package name has not been chosen and will likely differ. Until publication, install directly from GitHub: https://github.com/p4nthera115/erc8004-ui. Once published, this notice will disappear and all code examples will reflect the real package name.

## Description

Fetches and renders the agent's registered name from the identity registry. Falls back to a truncated agent ID if no name is registered.

## Preview

```tsx
import { AgentName } from "@erc8004/ui"
<AgentName agentRegistry="eip155:8453:0x8004...a432" agentId={2290} />
```

## Usage

```tsx
import { AgentName } from "@erc8004/ui"
<AgentName agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" agentId={2290} />
```

## Examples

### Inside AgentProvider

Use AgentProvider to avoid repeating props when rendering multiple components for the same agent.

```tsx
<AgentProvider agentRegistry="eip155:8453:0x8004...a432" agentId={2290}>
  <AgentName />
</AgentProvider>
```

### With Custom Styling

Pass className to override typography. Useful for heading-level displays.

```tsx
<AgentName
  agentRegistry="eip155:8453:0x8004...a432"
  agentId={2290}
  className="text-2xl font-semibold tracking-tight"
/>
```

## In Context

AgentName used in a profile header alongside the agent's image, description, and verification status.

```tsx
<AgentProvider agentRegistry="eip155:8453:0x8004...a432" agentId={2290}>
  <div className="flex items-center gap-4 p-4 bg-neutral-900 border border-white/20 rounded-lg">
    <AgentImage className="min-h-24 min-w-24" />
    <div className="flex flex-col gap-2">
      <div className="flex items-center gap-4">
        <AgentName />
        <VerificationBadge />
      </div>
      <AgentDescription />
    </div>
  </div>
</AgentProvider>
```

## API Reference

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `agentRegistry` | `string` | no | — | Agent registry in the format "eip155:{chainId}:{contractAddress}". Required unless inside an <AgentProvider>. |
| `agentId` | `number` | no | — | ERC-721 token ID of the agent. Required unless inside an <AgentProvider>. |
| `className` | `string` | no | — | Optional CSS classes merged onto the component root for layout, spacing, or custom styling (e.g. Tailwind). |

## States

This component handles loading and error states internally with inline placeholders. No configuration needed.

## Reference

- Live preview & full docs: https://erc8004-ui.vercel.app/docs/components/agent-name
- Markdown source: https://erc8004-ui.vercel.app/docs/components/agent-name.md

---

# AgentImage

**Slug:** `agent-image`  
**Import:** `import { AgentImage } from "@erc8004/ui"`

> **NOTE — provisional package name.** This library is not yet published to npm. `@erc8004/ui` is a placeholder used in code examples — the final package name has not been chosen and will likely differ. Until publication, install directly from GitHub: https://github.com/p4nthera115/erc8004-ui. Once published, this notice will disappear and all code examples will reflect the real package name.

## Description

Renders the agent's registered image. Supports IPFS, HTTPS, and base64 sources. Falls back to the deterministic FingerprintBadge when no image is registered.

## Usage

```tsx
import { AgentImage } from "@erc8004/ui"
<AgentImage agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" agentId={2290} />
```

## Examples

### With FingerprintBadge Fallback

When no image is registered, AgentImage automatically renders the deterministic FingerprintBadge as a fallback.

```tsx
// If the agent has no registered image, a FingerprintBadge is shown:
<AgentImage agentRegistry="eip155:8453:0x8004...a432" agentId={2290} />
```

### Circular Avatar

Use className to render as a circular avatar at a fixed size.

```tsx
<AgentImage
  agentRegistry="eip155:8453:0x8004...a432"
  agentId={2290}
  className="h-16 w-16 rounded-full overflow-hidden"
/>
```

## In Context

AgentImage in a profile header alongside name and verification badge.

```tsx
<AgentProvider agentRegistry="eip155:8453:0x8004...a432" agentId={2290}>
  <div className="flex items-center gap-4 p-4 bg-neutral-900 border border-white/20 rounded-lg">
    <AgentImage className="min-h-24 min-w-24" />
    <div className="flex flex-col gap-2">
      <div className="flex items-center gap-4">
        <AgentName />
        <VerificationBadge />
      </div>
      <AgentDescription />
    </div>
  </div>
</AgentProvider>
```

## API Reference

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `agentRegistry` | `string` | no | — | Agent registry in the format "eip155:{chainId}:{contractAddress}". Required unless inside an <AgentProvider>. |
| `agentId` | `number` | no | — | ERC-721 token ID of the agent. Required unless inside an <AgentProvider>. |
| `className` | `string` | no | — | Optional CSS classes merged onto the component root for layout, spacing, or custom styling (e.g. Tailwind). |

## States

This component handles loading and error states internally with inline placeholders. No configuration needed.

## Reference

- Live preview & full docs: https://erc8004-ui.vercel.app/docs/components/agent-image
- Markdown source: https://erc8004-ui.vercel.app/docs/components/agent-image.md

---

# AgentDescription

**Slug:** `agent-description`  
**Import:** `import { AgentDescription } from "@erc8004/ui"`

> **NOTE — provisional package name.** This library is not yet published to npm. `@erc8004/ui` is a placeholder used in code examples — the final package name has not been chosen and will likely differ. Until publication, install directly from GitHub: https://github.com/p4nthera115/erc8004-ui. Once published, this notice will disappear and all code examples will reflect the real package name.

## Description

Renders the agent's registered description text from the identity registry.

## Usage

```tsx
import { AgentDescription } from "@erc8004/ui"
<AgentDescription agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" agentId={2290} />
```

## Examples

### Inside AgentProvider

Renders the description text without repeating agent identity props.

```tsx
<AgentProvider agentRegistry="eip155:8453:0x8004...a432" agentId={2290}>
  <AgentDescription />
</AgentProvider>
```

### Truncated to Two Lines

Use className with line-clamp to constrain long descriptions inside compact cards.

```tsx
<AgentDescription
  agentRegistry="eip155:8453:0x8004...a432"
  agentId={2290}
  className="line-clamp-2 max-w-sm text-sm text-erc8004-muted-fg"
/>
```

## In Context

AgentDescription as part of a profile header composition.

```tsx
<AgentProvider agentRegistry="eip155:8453:0x8004...a432" agentId={2290}>
  <div className="flex items-center gap-4 p-4 bg-neutral-900 border border-white/20 rounded-lg">
    <AgentImage className="min-h-24 min-w-24" />
    <div className="flex flex-col gap-2">
      <div className="flex items-center gap-4">
        <AgentName />
        <VerificationBadge />
      </div>
      <AgentDescription />
    </div>
  </div>
</AgentProvider>
```

## API Reference

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `agentRegistry` | `string` | no | — | Agent registry in the format "eip155:{chainId}:{contractAddress}". Required unless inside an <AgentProvider>. |
| `agentId` | `number` | no | — | ERC-721 token ID of the agent. Required unless inside an <AgentProvider>. |
| `className` | `string` | no | — | Optional CSS classes merged onto the component root for layout, spacing, or custom styling (e.g. Tailwind). |

## States

This component handles loading and error states internally with inline placeholders. No configuration needed.

## Reference

- Live preview & full docs: https://erc8004-ui.vercel.app/docs/components/agent-description
- Markdown source: https://erc8004-ui.vercel.app/docs/components/agent-description.md

---

# AgentCard

**Slug:** `agent-card`  
**Import:** `import { AgentCard } from "@erc8004/ui"`

> **NOTE — provisional package name.** This library is not yet published to npm. `@erc8004/ui` is a placeholder used in code examples — the final package name has not been chosen and will likely differ. Until publication, install directly from GitHub: https://github.com/p4nthera115/erc8004-ui. Once published, this notice will disappear and all code examples will reflect the real package name.

## Description

Composed identity card combining avatar, name, description, owner address, and active protocol badges in a single component.

## Usage

```tsx
import { AgentCard } from "@erc8004/ui"
<AgentCard agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" agentId={2290} />
```

## Examples

### Vertical Layout

Stack the avatar above the name, agent id, and description. Ideal for marketplace grids and directory tiles.

```tsx
<AgentCard agentRegistry="eip155:8453:0x8004...a432" agentId={2290} layout="vertical" />
```

### Without Description

Hide the description to create a more compact card.

```tsx
<AgentCard agentRegistry="eip155:8453:0x8004...a432" agentId={2290} showDescription={false} />
```

### Without Protocol Badges

Hide protocol badges for a cleaner look in contexts where endpoints aren't relevant.

```tsx
<AgentCard agentRegistry="eip155:8453:0x8004...a432" agentId={2290} showProtocolBadges={false} />
```

### Minimal

Show only avatar and name by hiding description, owner, and protocol badges.

```tsx
<AgentCard
  agentRegistry="eip155:8453:0x8004...a432"
  agentId={2290}
  showDescription={false}
  showOwner={false}
  showProtocolBadges={false}
  layout="vertical"
/>
```

## In Context

AgentCard used in a marketplace grid alongside reputation data.

```tsx
<AgentProvider agentRegistry="eip155:8453:0x8004...a432" agentId={2290}>
  <div className="w-full max-w-sm space-y-3">
    <AgentCard />
    <div className="flex items-center gap-4 px-1">
      <ReputationScore />
      <LastActivity />
    </div>
  </div>
</AgentProvider>
```

## API Reference

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `agentRegistry` | `string` | no | — | Agent registry in the format "eip155:{chainId}:{contractAddress}". Required unless inside an <AgentProvider>. |
| `agentId` | `number` | no | — | ERC-721 token ID of the agent. Required unless inside an <AgentProvider>. |
| `className` | `string` | no | — | Optional CSS classes merged onto the component root for layout, spacing, or custom styling (e.g. Tailwind). |
| `layout` | `"horizontal" | "vertical"` | no | `"horizontal"` | Card layout. "horizontal" places the avatar next to name and description. "vertical" stacks the avatar above name, agent id, and description. |
| `showOwner` | `boolean` | no | `true` | Show the owner wallet address. |
| `showProtocolBadges` | `boolean` | no | `true` | Show protocol badges (MCP, A2A, OASF, Web, Email). |
| `showDescription` | `boolean` | no | `true` | Show the agent's description text. |

## States

This component handles loading, error, empty, and not-found states internally. A skeleton placeholder is shown while fetching, an error message with details appears if the Subgraph is unreachable, and a short message is displayed when no data exists for this agent.

## Reference

- Live preview & full docs: https://erc8004-ui.vercel.app/docs/components/agent-card
- Markdown source: https://erc8004-ui.vercel.app/docs/components/agent-card.md

---

# EndpointStatus

**Slug:** `endpoint-status`  
**Import:** `import { EndpointStatus } from "@erc8004/ui"`

> **NOTE — provisional package name.** This library is not yet published to npm. `@erc8004/ui` is a placeholder used in code examples — the final package name has not been chosen and will likely differ. Until publication, install directly from GitHub: https://github.com/p4nthera115/erc8004-ui. Once published, this notice will disappear and all code examples will reflect the real package name.

## Description

Lists all registered service endpoints (MCP, A2A, OASF, web, email) with protocol labels and optional live health check indicators.

## Usage

```tsx
import { EndpointStatus } from "@erc8004/ui"
<EndpointStatus agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" agentId={2290} />
```

## Examples

### With Health Checks

Enable live HTTP health checks to show green/red status dots for each endpoint.

```tsx
<EndpointStatus agentRegistry="eip155:8453:0x8004...a432" agentId={2290} showHealthChecks />
```

### Filtered Protocols

Show only MCP and A2A endpoints.

```tsx
<EndpointStatus agentRegistry="eip155:8453:0x8004...a432" agentId={2290} protocols={["mcp", "a2a"]} />
```

## In Context

EndpointStatus alongside an AgentCard to form a complete identity view.

```tsx
<AgentProvider agentRegistry="eip155:8453:0x8004...a432" agentId={2290}>
  <div className="w-full max-w-md space-y-4">
    <AgentCard />
    <EndpointStatus />
  </div>
</AgentProvider>
```

## API Reference

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `agentRegistry` | `string` | no | — | Agent registry in the format "eip155:{chainId}:{contractAddress}". Required unless inside an <AgentProvider>. |
| `agentId` | `number` | no | — | ERC-721 token ID of the agent. Required unless inside an <AgentProvider>. |
| `className` | `string` | no | — | Optional CSS classes merged onto the component root for layout, spacing, or custom styling (e.g. Tailwind). |
| `showHealthChecks` | `boolean` | no | `false` | Show live HTTP health check dots. Opt-in because pings can be slow. |
| `protocols` | `Array<"mcp" | "a2a" | "oasf" | "web" | "email">` | no | — | Filter which protocols are shown. Default shows all. |

## States

This component handles loading, error, empty, and not-found states internally. A skeleton placeholder is shown while fetching, an error message with details appears if the Subgraph is unreachable, and a short message is displayed when no data exists for this agent.

## Reference

- Live preview & full docs: https://erc8004-ui.vercel.app/docs/components/endpoint-status
- Markdown source: https://erc8004-ui.vercel.app/docs/components/endpoint-status.md

---

## Reputation

# ReputationScore

**Slug:** `reputation-score`  
**Import:** `import { ReputationScore } from "@erc8004/ui"`

> **NOTE — provisional package name.** This library is not yet published to npm. `@erc8004/ui` is a placeholder used in code examples — the final package name has not been chosen and will likely differ. Until publication, install directly from GitHub: https://github.com/p4nthera115/erc8004-ui. Once published, this notice will disappear and all code examples will reflect the real package name.

## Description

Compact inline badge showing the agent's average feedback score and total review count. Colour-coded by score range.

## Caveats

> **Note:** This component reads from the AgentStats entity, which isn't present on every chain's subgraph. On chains where it's missing, the component renders its empty state rather than an error. See [Concepts › Supported Chains](https://erc8004-ui.vercel.app/docs/concepts#supported-chains).

## Usage

```tsx
import { ReputationScore } from "@erc8004/ui"
<ReputationScore agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" agentId={2290} />
```

## Examples

### Without Count

Hide the review count for a more minimal display.

```tsx
<ReputationScore agentRegistry="eip155:8453:0x8004...a432" agentId={2290} showCount={false} />
```

### Higher Precision

Show two decimal places for more precise scores.

```tsx
<ReputationScore agentRegistry="eip155:8453:0x8004...a432" agentId={2290} precision={2} />
```

## In Context

ReputationScore in a marketplace card alongside the agent's image, name, and tag cloud.

```tsx
<AgentProvider agentRegistry="eip155:8453:0x8004...a432" agentId={2290}>
  <div className="flex items-center gap-3">
    <AgentImage />
    <div>
      <AgentName />
      <ReputationScore />
    </div>
  </div>
  <TagCloud />
</AgentProvider>
```

## API Reference

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `agentRegistry` | `string` | no | — | Agent registry in the format "eip155:{chainId}:{contractAddress}". Required unless inside an <AgentProvider>. |
| `agentId` | `number` | no | — | ERC-721 token ID of the agent. Required unless inside an <AgentProvider>. |
| `className` | `string` | no | — | Optional CSS classes merged onto the component root for layout, spacing, or custom styling (e.g. Tailwind). |
| `showCount` | `boolean` | no | `true` | Show/hide the "(N reviews)" count on hover. |
| `precision` | `number` | no | `1` | Decimal places for the score display. |

## States

This component handles loading and error states internally with inline placeholders. No configuration needed.

## Reference

- Live preview & full docs: https://erc8004-ui.vercel.app/docs/components/reputation-score
- Markdown source: https://erc8004-ui.vercel.app/docs/components/reputation-score.md

---

# ReputationTimeline

**Slug:** `reputation-timeline`  
**Import:** `import { ReputationTimeline } from "@erc8004/ui"`

> **NOTE — provisional package name.** This library is not yet published to npm. `@erc8004/ui` is a placeholder used in code examples — the final package name has not been chosen and will likely differ. Until publication, install directly from GitHub: https://github.com/p4nthera115/erc8004-ui. Once published, this notice will disappear and all code examples will reflect the real package name.

## Description

Sparkline chart showing how the agent's feedback scores have trended over time. Pure SVG, no external charting library.

## Usage

```tsx
import { ReputationTimeline } from "@erc8004/ui"
<ReputationTimeline agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" agentId={2290} />
```

## Examples

### Last 30 Days

Filter the timeline to only show feedback from the last 30 days.

```tsx
<ReputationTimeline agentRegistry="eip155:8453:0x8004...a432" agentId={2290} range="30d" />
```

### With Data Points

Show individual score dots on the chart.

```tsx
<ReputationTimeline agentRegistry="eip155:8453:0x8004...a432" agentId={2290} showDataPoints />
```

### Points Only (No Trend Line)

Show only the data point dots without the connecting trend line.

```tsx
<ReputationTimeline agentRegistry="eip155:8453:0x8004...a432" agentId={2290} showTrendLine={false} showDataPoints />
```

## In Context

ReputationTimeline alongside ReputationDistribution for a complete reputation view.

```tsx
<AgentProvider agentRegistry="eip155:8453:0x8004...a432" agentId={2290}>
  <ReputationTimeline />
  <ReputationDistribution />
</AgentProvider>
```

## API Reference

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `agentRegistry` | `string` | no | — | Agent registry in the format "eip155:{chainId}:{contractAddress}". Required unless inside an <AgentProvider>. |
| `agentId` | `number` | no | — | ERC-721 token ID of the agent. Required unless inside an <AgentProvider>. |
| `className` | `string` | no | — | Optional CSS classes merged onto the component root for layout, spacing, or custom styling (e.g. Tailwind). |
| `range` | `"7d" | "30d" | "90d" | "all"` | no | `"all"` | Time range filter for displayed feedback. |
| `showTrendLine` | `boolean` | no | `true` | Show the connecting line between data points. |
| `showDataPoints` | `boolean` | no | `false` | Show individual score dots on the chart. |

## States

This component handles loading, error, empty, and not-found states internally. A skeleton placeholder is shown while fetching, an error message with details appears if the Subgraph is unreachable, and a short message is displayed when no data exists for this agent.

## Reference

- Live preview & full docs: https://erc8004-ui.vercel.app/docs/components/reputation-timeline
- Markdown source: https://erc8004-ui.vercel.app/docs/components/reputation-timeline.md

---

# ReputationDistribution

**Slug:** `reputation-distribution`  
**Import:** `import { ReputationDistribution } from "@erc8004/ui"`

> **NOTE — provisional package name.** This library is not yet published to npm. `@erc8004/ui` is a placeholder used in code examples — the final package name has not been chosen and will likely differ. Until publication, install directly from GitHub: https://github.com/p4nthera115/erc8004-ui. Once published, this notice will disappear and all code examples will reflect the real package name.

## Description

Score distribution histogram showing the spread of feedback values across configurable score ranges.

## Usage

```tsx
import { ReputationDistribution } from "@erc8004/ui"
<ReputationDistribution agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" agentId={2290} />
```

## Examples

### Horizontal Orientation

Render the histogram as vertical bars in a horizontal row instead of horizontal bars in a vertical stack.

```tsx
<ReputationDistribution agentRegistry="eip155:8453:0x8004...a432" agentId={2290} orientation="horizontal" />
```

### Custom Bucket Count

Use 10 buckets for finer-grained distribution.

```tsx
<ReputationDistribution agentRegistry="eip155:8453:0x8004...a432" agentId={2290} bucketCount={10} />
```

### No Axis Labels

Hide the range labels for a more compact chart.

```tsx
<ReputationDistribution agentRegistry="eip155:8453:0x8004...a432" agentId={2290} showAxisLabels={false} />
```

## In Context

ReputationDistribution used alongside a timeline chart to show both trends and spread.

```tsx
<AgentProvider agentRegistry="eip155:8453:0x8004...a432" agentId={2290}>
  <ReputationTimeline />
  <ReputationDistribution />
</AgentProvider>
```

## API Reference

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `agentRegistry` | `string` | no | — | Agent registry in the format "eip155:{chainId}:{contractAddress}". Required unless inside an <AgentProvider>. |
| `agentId` | `number` | no | — | ERC-721 token ID of the agent. Required unless inside an <AgentProvider>. |
| `className` | `string` | no | — | Optional CSS classes merged onto the component root for layout, spacing, or custom styling (e.g. Tailwind). |
| `bucketCount` | `number` | no | `5` | Number of histogram buckets. |
| `orientation` | `"vertical" | "horizontal"` | no | `"vertical"` | Chart layout. "vertical" = horizontal bars stacked vertically. "horizontal" = vertical bars in a row. |
| `showAxisLabels` | `boolean` | no | `true` | Show score range labels on the axis. |
| `colored` | `boolean` | no | `true` | Colour bars by score band (green → gold → red). When false, uses a single accent colour. |

## States

This component handles loading, error, empty, and not-found states internally. A skeleton placeholder is shown while fetching, an error message with details appears if the Subgraph is unreachable, and a short message is displayed when no data exists for this agent.

## Reference

- Live preview & full docs: https://erc8004-ui.vercel.app/docs/components/reputation-distribution
- Markdown source: https://erc8004-ui.vercel.app/docs/components/reputation-distribution.md

---

# FeedbackList

**Slug:** `feedback-list`  
**Import:** `import { FeedbackList } from "@erc8004/ui"`

> **NOTE — provisional package name.** This library is not yet published to npm. `@erc8004/ui` is a placeholder used in code examples — the final package name has not been chosen and will likely differ. Until publication, install directly from GitHub: https://github.com/p4nthera115/erc8004-ui. Once published, this notice will disappear and all code examples will reflect the real package name.

## Description

Paginated list of individual feedback entries with score, tag pills, reviewer address, timestamp, and optional written review text.

## Usage

```tsx
import { FeedbackList } from "@erc8004/ui"
<FeedbackList agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" agentId={2290} />
```

## Examples

### Smaller Page Size

Show 5 items per page instead of the default 10.

```tsx
<FeedbackList agentRegistry="eip155:8453:0x8004...a432" agentId={2290} pageSize={5} />
```

### Minimal (Scores Only)

Hide tags, timestamps, and reviewer addresses for a compact score-only list.

```tsx
<FeedbackList
  agentRegistry="eip155:8453:0x8004...a432"
  agentId={2290}
  showTags={false}
  showTimestamp={false}
  showReviewerAddress={false}
  pageSize={5}
/>
```

### Without Responses

Hide agent responses under each feedback entry.

```tsx
<FeedbackList agentRegistry="eip155:8453:0x8004...a432" agentId={2290} showResponses={false} />
```

## In Context

FeedbackList in a reputation panel alongside the score and tag cloud.

```tsx
<AgentProvider agentRegistry="eip155:8453:0x8004...a432" agentId={2290}>
  <div className="flex items-center gap-4">
    <ReputationScore />
    <TagCloud />
  </div>
  <FeedbackList pageSize={3} />
</AgentProvider>
```

## API Reference

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `agentRegistry` | `string` | no | — | Agent registry in the format "eip155:{chainId}:{contractAddress}". Required unless inside an <AgentProvider>. |
| `agentId` | `number` | no | — | ERC-721 token ID of the agent. Required unless inside an <AgentProvider>. |
| `className` | `string` | no | — | Optional CSS classes merged onto the component root for layout, spacing, or custom styling (e.g. Tailwind). |
| `pageSize` | `number` | no | `10` | Items per page. |
| `showReviewerAddress` | `boolean` | no | `true` | Show the reviewer's wallet address. |
| `showTimestamp` | `boolean` | no | `true` | Show the feedback timestamp. |
| `showTags` | `boolean` | no | `true` | Show tag pills. |
| `showResponses` | `boolean` | no | `true` | Show agent responses under each feedback entry. |
| `coloredScores` | `boolean` | no | `true` | Colour the numeric score by score band (green → gold → red). |
| `emptyMessage` | `string` | no | `"No feedback yet."` | Custom message when there is no feedback. |

## States

This component handles loading, error, empty, and not-found states internally. A skeleton placeholder is shown while fetching, an error message with details appears if the Subgraph is unreachable, and a short message is displayed when no data exists for this agent.

## Reference

- Live preview & full docs: https://erc8004-ui.vercel.app/docs/components/feedback-list
- Markdown source: https://erc8004-ui.vercel.app/docs/components/feedback-list.md

---

# TagCloud

**Slug:** `tag-cloud`  
**Import:** `import { TagCloud } from "@erc8004/ui"`

> **NOTE — provisional package name.** This library is not yet published to npm. `@erc8004/ui` is a placeholder used in code examples — the final package name has not been chosen and will likely differ. Until publication, install directly from GitHub: https://github.com/p4nthera115/erc8004-ui. Once published, this notice will disappear and all code examples will reflect the real package name.

## Description

Weighted tag pills showing the agent's most frequent feedback tags. Pill size reflects mention frequency across all feedback entries.

## Usage

```tsx
import { TagCloud } from "@erc8004/ui"
<TagCloud agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" agentId={2290} />
```

## Examples

### Top 5 Tags

Limit to the 5 most frequent tags.

```tsx
<TagCloud agentRegistry="eip155:8453:0x8004...a432" agentId={2290} maxTags={5} />
```

### Minimum 3 Occurrences

Only show tags mentioned at least 3 times to filter out noise.

```tsx
<TagCloud agentRegistry="eip155:8453:0x8004...a432" agentId={2290} minOccurrences={3} />
```

## In Context

TagCloud in a marketplace card alongside agent identity and score.

```tsx
<AgentProvider agentRegistry="eip155:8453:0x8004...a432" agentId={2290}>
  <div className="flex items-center gap-3">
    <AgentImage />
    <div>
      <AgentName />
      <ReputationScore />
    </div>
  </div>
  <TagCloud maxTags={5} />
</AgentProvider>
```

## API Reference

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `agentRegistry` | `string` | no | — | Agent registry in the format "eip155:{chainId}:{contractAddress}". Required unless inside an <AgentProvider>. |
| `agentId` | `number` | no | — | ERC-721 token ID of the agent. Required unless inside an <AgentProvider>. |
| `className` | `string` | no | — | Optional CSS classes merged onto the component root for layout, spacing, or custom styling (e.g. Tailwind). |
| `maxTags` | `number` | no | `20` | Maximum number of tags shown. |
| `minOccurrences` | `number` | no | `1` | Minimum mention count for a tag to appear. |

## States

This component handles loading, error, empty, and not-found states internally. A skeleton placeholder is shown while fetching, an error message with details appears if the Subgraph is unreachable, and a short message is displayed when no data exists for this agent.

## Reference

- Live preview & full docs: https://erc8004-ui.vercel.app/docs/components/tag-cloud
- Markdown source: https://erc8004-ui.vercel.app/docs/components/tag-cloud.md

---

## Validation

# VerificationBadge

**Slug:** `verification-badge`  
**Import:** `import { VerificationBadge } from "@erc8004/ui"`

> **NOTE — provisional package name.** This library is not yet published to npm. `@erc8004/ui` is a placeholder used in code examples — the final package name has not been chosen and will likely differ. Until publication, install directly from GitHub: https://github.com/p4nthera115/erc8004-ui. Once published, this notice will disappear and all code examples will reflect the real package name.

## Description

Compact inline badge showing the agent's verification tier derived from completed validations and average validation score.

## Caveats

> **Note:** This component reads from the AgentStats entity, which isn't present on every chain's subgraph. On chains where it's missing, the component renders its empty state rather than an error. See [Concepts › Supported Chains](https://erc8004-ui.vercel.app/docs/concepts#supported-chains).

> **Warning:** The Validation Registry contracts aren't deployed on mainnet yet. On mainnet chains this component always renders its empty state. See [Concepts › Validation Registry](https://erc8004-ui.vercel.app/docs/concepts#validation-registry).

## Usage

```tsx
import { VerificationBadge } from "@erc8004/ui"
<VerificationBadge agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" agentId={2290} />
```

## Examples

### Alongside Agent Name

Place next to an agent name for inline trust indication.

```tsx
<AgentProvider agentRegistry="eip155:8453:0x8004...a432" agentId={2290}>
  <div className="flex items-center gap-2">
    <AgentName />
    <VerificationBadge />
  </div>
</AgentProvider>
```

### Standalone

Used alone as a compact trust indicator anywhere in the UI.

```tsx
<VerificationBadge agentRegistry="eip155:8453:0x8004...a432" agentId={2290} />
```

## In Context

VerificationBadge in a trust panel with validation score and recent validations.

```tsx
<AgentProvider agentRegistry="eip155:8453:0x8004...a432" agentId={2290}>
  <div className="flex items-center gap-2">
    <AgentName />
    <VerificationBadge />
  </div>
  <ValidationScore />
  <ValidationList pageSize={3} />
</AgentProvider>
```

## API Reference

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `agentRegistry` | `string` | no | — | Agent registry in the format "eip155:{chainId}:{contractAddress}". Required unless inside an <AgentProvider>. |
| `agentId` | `number` | no | — | ERC-721 token ID of the agent. Required unless inside an <AgentProvider>. |
| `className` | `string` | no | — | Optional CSS classes merged onto the component root for layout, spacing, or custom styling (e.g. Tailwind). |

## States

This component handles loading and error states internally with inline placeholders. No configuration needed.

## Reference

- Live preview & full docs: https://erc8004-ui.vercel.app/docs/components/verification-badge
- Markdown source: https://erc8004-ui.vercel.app/docs/components/verification-badge.md

---

# ValidationScore

**Slug:** `validation-score`  
**Import:** `import { ValidationScore } from "@erc8004/ui"`

> **NOTE — provisional package name.** This library is not yet published to npm. `@erc8004/ui` is a placeholder used in code examples — the final package name has not been chosen and will likely differ. Until publication, install directly from GitHub: https://github.com/p4nthera115/erc8004-ui. Once published, this notice will disappear and all code examples will reflect the real package name.

## Description

Average validation score (0-100) with a fill bar and completed/pending counts.

## Caveats

> **Note:** This component reads from the AgentStats entity, which isn't present on every chain's subgraph. On chains where it's missing, the component renders its empty state rather than an error. See [Concepts › Supported Chains](https://erc8004-ui.vercel.app/docs/concepts#supported-chains).

> **Warning:** The Validation Registry contracts aren't deployed on mainnet yet. On mainnet chains this component always renders its empty state. See [Concepts › Validation Registry](https://erc8004-ui.vercel.app/docs/concepts#validation-registry).

## Usage

```tsx
import { ValidationScore } from "@erc8004/ui"
<ValidationScore agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" agentId={2290} />
```

## Examples

### Without Fill Bar

Hide the score fill bar for a text-only display.

```tsx
<ValidationScore agentRegistry="eip155:8453:0x8004...a432" agentId={2290} showFillBar={false} />
```

### Without Pending Count

Hide the pending validation count.

```tsx
<ValidationScore agentRegistry="eip155:8453:0x8004...a432" agentId={2290} showPendingCount={false} />
```

## In Context

ValidationScore in a trust panel alongside the verification badge and recent validations.

```tsx
<AgentProvider agentRegistry="eip155:8453:0x8004...a432" agentId={2290}>
  <div className="flex items-center gap-2">
    <AgentName />
    <VerificationBadge />
  </div>
  <ValidationScore />
  <ValidationList pageSize={3} />
</AgentProvider>
```

## API Reference

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `agentRegistry` | `string` | no | — | Agent registry in the format "eip155:{chainId}:{contractAddress}". Required unless inside an <AgentProvider>. |
| `agentId` | `number` | no | — | ERC-721 token ID of the agent. Required unless inside an <AgentProvider>. |
| `className` | `string` | no | — | Optional CSS classes merged onto the component root for layout, spacing, or custom styling (e.g. Tailwind). |
| `showFillBar` | `boolean` | no | `true` | Show the score fill bar. |
| `showPendingCount` | `boolean` | no | `true` | Show the pending validation count. |

## States

This component handles loading, error, empty, and not-found states internally. A skeleton placeholder is shown while fetching, an error message with details appears if the Subgraph is unreachable, and a short message is displayed when no data exists for this agent.

## Reference

- Live preview & full docs: https://erc8004-ui.vercel.app/docs/components/validation-score
- Markdown source: https://erc8004-ui.vercel.app/docs/components/validation-score.md

---

# ValidationList

**Slug:** `validation-list`  
**Import:** `import { ValidationList } from "@erc8004/ui"`

> **NOTE — provisional package name.** This library is not yet published to npm. `@erc8004/ui` is a placeholder used in code examples — the final package name has not been chosen and will likely differ. Until publication, install directly from GitHub: https://github.com/p4nthera115/erc8004-ui. Once published, this notice will disappear and all code examples will reflect the real package name.

## Description

Paginated list of individual validation entries with score, status, tag, validator address, and timestamp.

## Caveats

> **Warning:** The Validation Registry contracts aren't deployed on mainnet yet. On mainnet chains this component always renders its empty state. See [Concepts › Validation Registry](https://erc8004-ui.vercel.app/docs/concepts#validation-registry).

## Usage

```tsx
import { ValidationList } from "@erc8004/ui"
<ValidationList agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" agentId={2290} />
```

## Examples

### Completed Only

Filter to show only completed validations.

```tsx
<ValidationList agentRegistry="eip155:8453:0x8004...a432" agentId={2290} statusFilter="completed" />
```

### Smaller Page Size

Show 5 items per page for a compact view.

```tsx
<ValidationList agentRegistry="eip155:8453:0x8004...a432" agentId={2290} pageSize={5} />
```

## In Context

ValidationList in a trust panel alongside the verification badge and validation score.

```tsx
<AgentProvider agentRegistry="eip155:8453:0x8004...a432" agentId={2290}>
  <div className="flex items-center gap-2">
    <AgentName />
    <VerificationBadge />
  </div>
  <ValidationScore />
  <ValidationList pageSize={3} />
</AgentProvider>
```

## API Reference

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `agentRegistry` | `string` | no | — | Agent registry in the format "eip155:{chainId}:{contractAddress}". Required unless inside an <AgentProvider>. |
| `agentId` | `number` | no | — | ERC-721 token ID of the agent. Required unless inside an <AgentProvider>. |
| `className` | `string` | no | — | Optional CSS classes merged onto the component root for layout, spacing, or custom styling (e.g. Tailwind). |
| `pageSize` | `number` | no | `10` | Items per page. |
| `showValidatorAddress` | `boolean` | no | `true` | Show the validator's wallet address. |
| `showTimestamp` | `boolean` | no | `true` | Show the validation timestamp. |
| `statusFilter` | `"all" | "completed" | "pending" | "expired"` | no | `"all"` | Filter validations by status. |
| `emptyMessage` | `string` | no | `"No validations yet."` | Custom message when there are no validations. |

## States

This component handles loading, error, empty, and not-found states internally. A skeleton placeholder is shown while fetching, an error message with details appears if the Subgraph is unreachable, and a short message is displayed when no data exists for this agent.

## Reference

- Live preview & full docs: https://erc8004-ui.vercel.app/docs/components/validation-list
- Markdown source: https://erc8004-ui.vercel.app/docs/components/validation-list.md

---

# ValidationDisplay

**Slug:** `validation-display`  
**Import:** `import { ValidationDisplay } from "@erc8004/ui"`

> **NOTE — provisional package name.** This library is not yet published to npm. `@erc8004/ui` is a placeholder used in code examples — the final package name has not been chosen and will likely differ. Until publication, install directly from GitHub: https://github.com/p4nthera115/erc8004-ui. Once published, this notice will disappear and all code examples will reflect the real package name.

## Description

Composed view combining VerificationBadge, ValidationScore, and ValidationList into a single unified validation panel.

## Caveats

> **Warning:** The Validation Registry contracts aren't deployed on mainnet yet. On mainnet chains this component always renders its empty state. See [Concepts › Validation Registry](https://erc8004-ui.vercel.app/docs/concepts#validation-registry).

## Usage

```tsx
import { ValidationDisplay } from "@erc8004/ui"
<ValidationDisplay agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" agentId={2290} />
```

## Examples

### Inside AgentProvider

Use AgentProvider to avoid repeating identity props.

```tsx
<AgentProvider agentRegistry="eip155:8453:0x8004...a432" agentId={2290}>
  <ValidationDisplay />
</AgentProvider>
```

### Constrained Width

Pass className to fit the composed panel into a sidebar or trust column.

```tsx
<ValidationDisplay
  agentRegistry="eip155:8453:0x8004...a432"
  agentId={2290}
  className="max-w-sm"
/>
```

## In Context

ValidationDisplay as a standalone trust panel on an agent profile page.

```tsx
<AgentProvider agentRegistry="eip155:8453:0x8004...a432" agentId={2290}>
  <AgentCard />
  <ValidationDisplay />
</AgentProvider>
```

## API Reference

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `agentRegistry` | `string` | no | — | Agent registry in the format "eip155:{chainId}:{contractAddress}". Required unless inside an <AgentProvider>. |
| `agentId` | `number` | no | — | ERC-721 token ID of the agent. Required unless inside an <AgentProvider>. |
| `className` | `string` | no | — | Optional CSS classes merged onto the component root for layout, spacing, or custom styling (e.g. Tailwind). |

## States

This component handles loading, error, empty, and not-found states internally. A skeleton placeholder is shown while fetching, an error message with details appears if the Subgraph is unreachable, and a short message is displayed when no data exists for this agent.

## Reference

- Live preview & full docs: https://erc8004-ui.vercel.app/docs/components/validation-display
- Markdown source: https://erc8004-ui.vercel.app/docs/components/validation-display.md

---

## Activity

# LastActivity

**Slug:** `last-activity`  
**Import:** `import { LastActivity } from "@erc8004/ui"`

> **NOTE — provisional package name.** This library is not yet published to npm. `@erc8004/ui` is a placeholder used in code examples — the final package name has not been chosen and will likely differ. Until publication, install directly from GitHub: https://github.com/p4nthera115/erc8004-ui. Once published, this notice will disappear and all code examples will reflect the real package name.

## Description

Cross-registry relative timestamp showing when the agent was last active (e.g. "Active 3 hours ago"). Reflects the most recent event across all registries.

## Caveats

> **Note:** This component reads from the AgentStats entity, which isn't present on every chain's subgraph. On chains where it's missing, the component renders its empty state rather than an error. See [Concepts › Supported Chains](https://erc8004-ui.vercel.app/docs/concepts#supported-chains).

## Usage

```tsx
import { LastActivity } from "@erc8004/ui"
<LastActivity agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" agentId={2290} />
```

## Examples

### Inside AgentProvider

Renders the last activity timestamp without repeating identity props.

```tsx
<AgentProvider agentRegistry="eip155:8453:0x8004...a432" agentId={2290}>
  <LastActivity />
</AgentProvider>
```

### As Status Indicator

Combine with a live dot and muted styling to show agent presence in a header.

```tsx
<div className="flex items-center gap-2 text-xs text-erc8004-muted-fg">
  <span className="h-1.5 w-1.5 rounded-full bg-erc8004-positive" />
  <LastActivity agentRegistry="eip155:8453:0x8004...a432" agentId={2290} />
</div>
```

## In Context

LastActivity in a sidebar showing agent status alongside the activity log.

```tsx
<AgentProvider agentRegistry="eip155:8453:0x8004...a432" agentId={2290}>
  <div className="flex items-center gap-3">
    <AgentName />
    <LastActivity />
  </div>
  <ActivityLog pageSize={5} />
</AgentProvider>
```

## API Reference

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `agentRegistry` | `string` | no | — | Agent registry in the format "eip155:{chainId}:{contractAddress}". Required unless inside an <AgentProvider>. |
| `agentId` | `number` | no | — | ERC-721 token ID of the agent. Required unless inside an <AgentProvider>. |
| `className` | `string` | no | — | Optional CSS classes merged onto the component root for layout, spacing, or custom styling (e.g. Tailwind). |

## States

This component handles loading and error states internally with inline placeholders. No configuration needed.

## Reference

- Live preview & full docs: https://erc8004-ui.vercel.app/docs/components/last-activity
- Markdown source: https://erc8004-ui.vercel.app/docs/components/last-activity.md

---

# ActivityLog

**Slug:** `activity-log`  
**Import:** `import { ActivityLog } from "@erc8004/ui"`

> **NOTE — provisional package name.** This library is not yet published to npm. `@erc8004/ui` is a placeholder used in code examples — the final package name has not been chosen and will likely differ. Until publication, install directly from GitHub: https://github.com/p4nthera115/erc8004-ui. Once published, this notice will disappear and all code examples will reflect the real package name.

## Description

Chronological feed of all on-chain events across all registries — feedback and validations merged and sorted by time.

## Usage

```tsx
import { ActivityLog } from "@erc8004/ui"
<ActivityLog agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" agentId={2290} />
```

## Examples

### Feedback Only

Filter to show only feedback events.

```tsx
<ActivityLog agentRegistry="eip155:8453:0x8004...a432" agentId={2290} eventTypes={["feedback"]} />
```

### Smaller Page Size

Show only the 5 most recent events.

```tsx
<ActivityLog agentRegistry="eip155:8453:0x8004...a432" agentId={2290} pageSize={5} />
```

## In Context

ActivityLog in a sidebar showing recent agent activity alongside last activity timestamp.

```tsx
<AgentProvider agentRegistry="eip155:8453:0x8004...a432" agentId={2290}>
  <div className="flex items-center gap-3">
    <AgentName />
    <LastActivity />
  </div>
  <ActivityLog pageSize={5} />
</AgentProvider>
```

## API Reference

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `agentRegistry` | `string` | no | — | Agent registry in the format "eip155:{chainId}:{contractAddress}". Required unless inside an <AgentProvider>. |
| `agentId` | `number` | no | — | ERC-721 token ID of the agent. Required unless inside an <AgentProvider>. |
| `className` | `string` | no | — | Optional CSS classes merged onto the component root for layout, spacing, or custom styling (e.g. Tailwind). |
| `pageSize` | `number` | no | `20` | Maximum number of events to display. |
| `eventTypes` | `Array<"feedback" | "validation">` | no | — | Filter by event type. Default shows all. |

## States

This component handles loading, error, empty, and not-found states internally. A skeleton placeholder is shown while fetching, an error message with details appears if the Subgraph is unreachable, and a short message is displayed when no data exists for this agent.

## Reference

- Live preview & full docs: https://erc8004-ui.vercel.app/docs/components/activity-log
- Markdown source: https://erc8004-ui.vercel.app/docs/components/activity-log.md

---