> ## Documentation Index
> Fetch the complete documentation index at: https://krono.fabianpiper.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# useAssetPairs

> A reactive hook for accessing asset pairs.
Provides a synchronized state of Kraken trading pairs with liquidity-based filtering (top N), loading status, and management methods.


<Note>
  This hook requires the `OrderbookProvider` or `AssetPairsProvider` to be present in your component tree to provide the underlying `AssetPairs` instance.
</Note>

## Import

```ts theme={null}
import { useAssetPairs } from '@krono/hooks'
```

## Usage

```ts theme={null}
import { useAssetPairs } from '@krono/hooks'

function App() {
  const { symbols, loading } = useAssetPairs();

  if (loading) return <div>loading...</div>;

  return (
    <ul>
      {symbols.map((symbol) => (
        <li key={symbol.value}>{symbol.displayLabel}</li>
      ))}
    </ul>
  );
}
```

***

## Parameters

```ts theme={null}
import { type UseAssetPairsParameters } from '@krono/hooks'
```

<ResponseField name="initialData" type="AssetPairsData">
  Initial data to hydrate the state immediately. Useful for SSR or restoring data from a persistent cache.
</ResponseField>

```tsx theme={null}
import { useAssetPairs } from '@krono/hooks';

function App() {
  const result = useAssetPairs({
    initialData: {
      symbols: cache.symbols,
      symbolMap: cache.symbolMap,
    },
  });
}
```

***

## Return Type

```ts theme={null}
import { type UseAssetPairsReturnType } from '@krono/hooks'
```

### State

<ResponseField name="symbols" type="SymbolOption[]">
  The list of available trading pairs, filtered by `topN` (liquidity) and sorted alphabetically by label.
</ResponseField>

<ResponseField name="symbolMap" type="Map<string, SymbolOption>">
  A lookup map for O(1) access to symbol data.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` whenever a fetch request is in flight.
</ResponseField>

<ResponseField name="loaded" type="boolean">
  `true` once the first successful fetch has completed.
</ResponseField>

<ResponseField name="error" type="Error | null">
  Contains the error object if the last fetch attempt failed.
</ResponseField>

<ResponseField name="topN" type="number" default={100}>
  The current number of high-liquidity pairs being tracked.
</ResponseField>

### Actions

<ResponseField name="refresh" type="() => Promise<AssetPairsData>">
  Manually triggers a new fetch request from the Kraken API.
</ResponseField>

<ResponseField name="findSymbol" type="(search: string) => SymbolOption | undefined">
  Case-insensitive search. Matches against `wsname` (BTC/USD), `altname` (XBTUSD), `displayLabel`, and internal Kraken keys.
</ResponseField>

<ResponseField name="setTopN" type="(n: number) => void">
  Updates the liquidity filter. **Note:** If the state is already `loaded`, changing this value triggers an automatic re-fetch.
</ResponseField>

<ResponseField name="clear" type="() => void">
  Wipes the current local state and resets status to `idle`.
</ResponseField>

## Examples

### Symbol Search

Use `findSymbol` for efficient lookups across multiple identifier types.

```tsx theme={null}
function SearchComponent() {
  const { findSymbol } = useAssetPairs()
  const [query, setQuery] = useState('')

  // This will match "BTC/USD", "XBTUSD", or "XXBTZUSD"
  const pair = findSymbol(query)

  return (
    <div>
      <input
        type="text"
        placeholder="Search pairs..."
        onChange={(e) => setQuery(e.target.value)}
      />
      {pair && <div>Found: {pair.displayLabel}</div>}
    </div>
  )
}
```

### Dynamic Liquidity Filtering

Change the number of tracked pairs on the fly using the `setTopN` action.

```tsx theme={null}
import { useAssetPairs } from '@krono/hooks';

function App() {
  const { topN, setTopN } = useAssetPairs();

  return (
    <select value={topN} onChange={(e) => setTopN(Number(e.target.value))}>
      <option value={10}>Top 10</option>
      <option value={100}>Top 100</option>
      <option value={500}>Top 500</option>
    </select>
  );
}
```

### SSR Hydration

If you are using Next.js or another SSR framework, you can pass data from the server to prevent layout shifts.

```tsx theme={null}
export function Page({ prefetchedPairs }) {
  const { symbols } = useAssetPairs({ initialData: cache });
  // ...
}
```

***

## Related

<CardGroup cols={2}>
  <Card title="AssetPairs Core" icon="toy-brick" href="core/api/classes/AssetPairs">
    Explore the underlying class logic and event emitters.
  </Card>

  <Card title="useOrderbookConfig" icon="cog" href="hooks/api/useOrderbookConfig">
    Use symbols from this hook to open a WebSocket orderbook feed.
  </Card>

  <Card title="useOrderbookPlayback" icon="square-play" href="hooks/api/useOrderbookPlayback">
    Use historical orderbook data to travel in time.
  </Card>

  <Card title="Kraken API" icon="link" href="https://docs.kraken.com/api/docs/rest-api/get-asset-info/">
    Explore the `GetAssetInfo` endpoint in the Kraken API docs.
  </Card>
</CardGroup>