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

Installation

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

Install

Note — @erc8004/ui is a placeholder name — the package is not yet published to npm. Until publication, install directly from GitHub:

npm install github:p4nthera115/erc8004-ui

All other code examples on this page use the final import path and will work unchanged once the package is published.

npm install @erc8004/ui

pnpm add @erc8004/ui
yarn add @erc8004/ui

Peer Dependencies

The library requires React and TanStack Query as peer dependencies:

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, a blockchain indexing service. Sign up at 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

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:

// 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) — 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.

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.

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 — understand what agentRegistry and agentId mean
Components — browse all available components with live previews

←Introduction Concepts→