# Installation

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

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 @p4n/erc8004-ui
```

or

```bash
pnpm add @p4n/erc8004-ui
yarn add @p4n/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 "@p4n/erc8004-ui"

function App() {
  return (
    <ERC8004Provider apiKey="your-graph-api-key">
      <ReputationScore
        agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432"
        agentId={888}
      />
    </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 "@p4n/erc8004-ui"

const queryClient = new QueryClient()

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <ERC8004Provider apiKey="your-graph-api-key">
        <ReputationScore
          agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432"
          agentId={888}
        />
      </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 "@p4n/erc8004-ui"

<AgentProvider agentRegistry="eip155:8453:0x..." agentId={888}>
  <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