> ## Documentation Index
> Fetch the complete documentation index at: https://core.anylayer.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Hooks Overview

> React hooks for integrating ZKScore into your application

## Overview

The ZKScore React SDK provides a comprehensive set of hooks that make it easy to integrate reputation scores, identities, achievements, and more into your React applications.

## Installation

```bash theme={null}
npm install @zkscore/react
```

## Provider Setup

Wrap your app with the ZKScoreProvider:

```tsx theme={null}
import { ZKScoreProvider } from '@zkscore/react';

function App() {
  return (
    <ZKScoreProvider
      apiKey={process.env.REACT_APP_ZKSCORE_API_KEY}
      network="mainnet"
    >
      <YourApp />
    </ZKScoreProvider>
  );
}
```

### Provider Props

<ParamField path="apiKey" type="string" required>
  Your ZKScore API key
</ParamField>

<ParamField path="network" type="string">
  Network to use: `'mainnet'` or `'testnet'` (default: `'mainnet'`)
</ParamField>

<ParamField path="cacheTime" type="number">
  Cache duration in milliseconds (default: 300000 - 5 minutes)
</ParamField>

<ParamField path="retryAttempts" type="number">
  Number of retry attempts for failed requests (default: 3)
</ParamField>

## Available Hooks

### Identity Hooks

<CardGroup cols={2}>
  <Card title="useIdentity" href="/sdk/react/use-identity">
    Get identity information for an address
  </Card>

  <Card title="useMintIdentity" href="/sdk/react/use-identity#mint-identity">
    Mint a new ZKScore identity
  </Card>

  <Card title="useCheckUsername" href="/sdk/react/use-identity#check-username">
    Check username availability
  </Card>
</CardGroup>

### Score Hooks

<CardGroup cols={2}>
  <Card title="useScore" href="/sdk/react/use-score">
    Get reputation score for an address
  </Card>

  <Card title="useScoreBreakdown" href="/sdk/react/use-score#score-breakdown">
    Get detailed score breakdown
  </Card>

  <Card title="useScoreHistory" href="/sdk/react/use-score#score-history">
    Get historical score data
  </Card>

  <Card title="useLeaderboard" href="/sdk/react/use-score#leaderboard">
    Get score leaderboard
  </Card>
</CardGroup>

### Achievement Hooks

<CardGroup cols={2}>
  <Card title="useAchievements" href="/sdk/react/use-achievements">
    List all available achievements
  </Card>

  <Card title="useUserAchievements" href="/sdk/react/use-achievements#user-achievements">
    Get user's earned achievements
  </Card>

  <Card title="useAchievementProgress" href="/sdk/react/use-achievements#progress">
    Track achievement progress
  </Card>

  <Card title="useClaimAchievement" href="/sdk/react/use-achievements#claim">
    Claim an achievement
  </Card>
</CardGroup>

### Trading Hooks

<CardGroup cols={2}>
  <Card title="useTradingStats" href="/sdk/react/use-trading">
    Get trading statistics
  </Card>

  <Card title="useTradingHistory" href="/sdk/react/use-trading#history">
    Get trading history
  </Card>

  <Card title="useTradingLeaderboard" href="/sdk/react/use-trading#leaderboard">
    Get trading leaderboard
  </Card>
</CardGroup>

### Trust Layer Hooks

<CardGroup cols={2}>
  <Card title="useAttestations" href="/sdk/react/hooks-reference#attestations">
    Get attestations for an address
  </Card>

  <Card title="useCreateAttestation" href="/sdk/react/hooks-reference#create-attestation">
    Create new attestations
  </Card>

  <Card title="useTrustPolicy" href="/sdk/react/hooks-reference#trust-policy">
    Evaluate trust policies
  </Card>
</CardGroup>

## Hook Patterns

### Basic Usage

```tsx theme={null}
import { useScore } from '@zkscore/react';

function ScoreDisplay({ address }: { address: string }) {
  const { score, loading, error } = useScore(address);

  if (loading) return <div>Loading score...</div>;
  if (error) return <div>Error: {error.message}</div>;
  if (!score) return <div>No score available</div>;

  return (
    <div>
      <h2>Score: {score.overall}/1000</h2>
      <p>Rank: #{score.rank}</p>
    </div>
  );
}
```

### With Auto-Refresh

```tsx theme={null}
import { useScore } from '@zkscore/react';

function LiveScore({ address }: { address: string }) {
  const { score, loading, refetch } = useScore(address, {
    refreshInterval: 30000, // Refresh every 30 seconds
  });

  return (
    <div>
      <h2>Score: {score?.overall || 0}</h2>
      <button onClick={() => refetch()}>Refresh Now</button>
    </div>
  );
}
```

### Conditional Fetching

```tsx theme={null}
import { useScore } from '@zkscore/react';

function ConditionalScore({ address, enabled }: { address: string; enabled: boolean }) {
  const { score, loading } = useScore(address, {
    enabled, // Only fetch when enabled is true
  });

  if (!enabled) return <div>Score fetching disabled</div>;
  if (loading) return <div>Loading...</div>;

  return <div>Score: {score?.overall}</div>;
}
```

### Error Handling

```tsx theme={null}
import { useScore } from '@zkscore/react';

function ScoreWithErrorHandling({ address }: { address: string }) {
  const { score, loading, error, refetch } = useScore(address, {
    retry: 3,
    retryDelay: 1000,
  });

  if (loading) return <Spinner />;

  if (error) {
    return (
      <ErrorCard>
        <p>{error.message}</p>
        <button onClick={() => refetch()}>Try Again</button>
      </ErrorCard>
    );
  }

  return <ScoreCard score={score} />;
}
```

### Multiple Hooks

```tsx theme={null}
import { useIdentity, useScore, useUserAchievements } from '@zkscore/react';

function UserProfile({ address }: { address: string }) {
  const { identity } = useIdentity(address);
  const { score } = useScore(address);
  const { achievements } = useUserAchievements(address);

  return (
    <div>
      <h1>{identity?.username || 'Anonymous'}</h1>
      <p>Score: {score?.overall}/1000</p>
      <p>Achievements: {achievements?.length || 0}</p>
    </div>
  );
}
```

## Common Hook Options

Most hooks accept these common options:

<ParamField path="enabled" type="boolean">
  Enable/disable the query (default: `true`)
</ParamField>

<ParamField path="refreshInterval" type="number">
  Auto-refresh interval in milliseconds
</ParamField>

<ParamField path="retry" type="number">
  Number of retry attempts (default: 3)
</ParamField>

<ParamField path="retryDelay" type="number">
  Delay between retries in milliseconds (default: 1000)
</ParamField>

<ParamField path="cacheTime" type="number">
  How long to cache data in milliseconds
</ParamField>

<ParamField path="staleTime" type="number">
  Time until data is considered stale in milliseconds
</ParamField>

<ParamField path="onSuccess" type="function">
  Callback when query succeeds
</ParamField>

<ParamField path="onError" type="function">
  Callback when query fails
</ParamField>

## Common Return Values

All hooks return an object with these common properties:

<ResponseField name="data" type="any">
  The fetched data (e.g., `score`, `identity`, `achievements`)
</ResponseField>

<ResponseField name="loading" type="boolean">
  Whether the data is currently being fetched
</ResponseField>

<ResponseField name="error" type="Error | null">
  Error object if the request failed
</ResponseField>

<ResponseField name="refetch" type="function">
  Function to manually refetch the data
</ResponseField>

<ResponseField name="isStale" type="boolean">
  Whether the cached data is stale
</ResponseField>

## Advanced Patterns

### Prefetching Data

```tsx theme={null}
import { useZKScore } from '@zkscore/react';

function PrefetchExample() {
  const { prefetch } = useZKScore();

  const handleMouseEnter = (address: string) => {
    // Prefetch data on hover
    prefetch.score(address);
    prefetch.achievements(address);
  };

  return (
    <div onMouseEnter={() => handleMouseEnter('0x123...')}>
      <UserCard address="0x123..." />
    </div>
  );
}
```

### Mutations

```tsx theme={null}
import { useMintIdentity } from '@zkscore/react';

function MintIdentityForm() {
  const { mutate, loading, error } = useMintIdentity({
    onSuccess: (identity) => {
      console.log('Identity minted:', identity);
    },
    onError: (error) => {
      console.error('Failed to mint:', error);
    },
  });

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    mutate({
      address: '0x123...',
      username: 'alice',
    });
  };

  return (
    <form onSubmit={handleSubmit}>
      <input name="username" required />
      <button type="submit" disabled={loading}>
        {loading ? 'Minting...' : 'Mint Identity'}
      </button>
      {error && <p className="error">{error.message}</p>}
    </form>
  );
}
```

### Optimistic Updates

```tsx theme={null}
import { useClaimAchievement, useUserAchievements } from '@zkscore/react';

function ClaimButton({ address, achievementId }: Props) {
  const { achievements, refetch } = useUserAchievements(address);
  const { mutate } = useClaimAchievement({
    onMutate: () => {
      // Optimistically update UI
      // This runs before the API call
    },
    onSuccess: () => {
      // Refetch to get updated data
      refetch();
    },
  });

  return (
    <button onClick={() => mutate({ achievementId })}>
      Claim Achievement
    </button>
  );
}
```

### Dependent Queries

```tsx theme={null}
import { useIdentity, useScore } from '@zkscore/react';

function DependentQueries({ address }: { address: string }) {
  // First query
  const { identity } = useIdentity(address);

  // Second query only runs if first succeeds
  const { score } = useScore(address, {
    enabled: !!identity,
  });

  return (
    <div>
      {identity && <h1>{identity.username}</h1>}
      {score && <p>Score: {score.overall}</p>}
    </div>
  );
}
```

### Pagination

```tsx theme={null}
import { useTradingHistory } from '@zkscore/react';
import { useState } from 'react';

function TradingHistoryTable({ address }: { address: string }) {
  const [page, setPage] = useState(0);
  const { history, loading, pagination } = useTradingHistory(address, {
    limit: 20,
    offset: page * 20,
  });

  return (
    <div>
      {loading ? (
        <Spinner />
      ) : (
        <table>
          {history?.trades.map((trade) => (
            <tr key={trade.txHash}>
              <td>{trade.tokenIn.symbol}</td>
              <td>{trade.tokenOut.symbol}</td>
              <td>{trade.timestamp}</td>
            </tr>
          ))}
        </table>
      )}
      
      <Pagination
        page={page}
        hasMore={pagination?.hasMore}
        onNext={() => setPage(p => p + 1)}
        onPrev={() => setPage(p => Math.max(0, p - 1))}
      />
    </div>
  );
}
```

## TypeScript Support

All hooks are fully typed for TypeScript:

```typescript theme={null}
import { useScore } from '@zkscore/react';
import type { Score, ScoreBreakdown } from '@zkscore/types';

function TypedScore({ address }: { address: string }) {
  // Type is inferred automatically
  const { score, loading, error } = useScore(address);
  
  // score is typed as Score | undefined
  // error is typed as Error | null
  // loading is typed as boolean
  
  return <div>{score?.overall}</div>;
}
```

## Performance Tips

1. **Use Appropriate Cache Times**: Set longer cache times for rarely-changing data
2. **Disable Auto-Refetch**: For static data, set `refreshInterval: 0`
3. **Enable Suspense**: Use React Suspense for better loading states
4. **Prefetch**: Prefetch data on hover or route changes
5. **Batch Requests**: Use multiple hooks to fetch related data in parallel

## Next Steps

<CardGroup cols={2}>
  <Card title="useIdentity" icon="fingerprint" href="/sdk/react/use-identity">
    Learn about identity hooks
  </Card>

  <Card title="useScore" icon="chart-line" href="/sdk/react/use-score">
    Learn about score hooks
  </Card>

  <Card title="useAchievements" icon="trophy" href="/sdk/react/use-achievements">
    Learn about achievement hooks
  </Card>

  <Card title="Components" icon="cube" href="/sdk/react/components">
    Pre-built React components
  </Card>
</CardGroup>