# useOrderbook

URL: https://docs.blux.cc/react/hooks/use-orderbook

Fetch orderbook data for an asset pair in your React app using the Blux SDK.

The `useOrderbook` hook returns orderbook data for a given asset pair. Both `selling` and `buying` are required — the hook will not run without them. Import `Asset` from `@bluxcc/react`.

## Import
```tsx
```

## Usage

Basic usage with required arguments:

<Tabs items={['index.tsx', 'config.ts']} defaultIndex={0}>
<Tab value="index.tsx">
```tsx

function App() {
  const selling = Asset.native();
  const buying = new Asset("USDC", "GA5Z....KZVN");

  const { data } = useOrderbook([selling, buying]);
}
```
</Tab>
<Tab value="config.ts">
```tsx
root.render(
  <BluxProvider
    config={{
      appName: "MyApp",
      networks: [networks.testnet, networks.mainnet],
    }}
  >
    <App />
  </BluxProvider>
);
```
</Tab>
</Tabs>

With call-builder options and TanStack Query options:

<Tabs items={['index.tsx', 'config.ts']} defaultIndex={0}>
<Tab value="index.tsx">
```tsx

function App() {
  const selling = Asset.native();
  const buying = new Asset("USDC", "GA5Z....KZVN");

  const { data, isStale } = useOrderbook(
    [selling, buying],              // Required arguments
    { limit: 20, order: "asc" },    // Core parameters
    { retry: 3, staleTime: 5000 },  // TanStack parameters
  );
}
```
</Tab>
<Tab value="config.ts">
```tsx
root.render(
  <BluxProvider
    config={{
      appName: "MyApp",
      networks: [networks.testnet, networks.mainnet],
    }}
  >
    <App />
  </BluxProvider>
);
```
</Tab>
</Tabs>

<Callout type="info">
  Pass required arguments first, then core call-builder options, then TanStack Query options. The hook relies on this order to work correctly.
</Callout>

## Parameters

### `selling` (required)
`Asset`

The asset being sold in the orderbook.

### `buying` (required)
`Asset`

The asset being bought in the orderbook.

### `limit`
`number | undefined`

Number of records to return.

### `network`
`string | undefined`

The network to query. Omit to use the active network.

### `order`
`'asc' | 'desc' | undefined`

Sort order for the results.

## Query Options

| Option | Type | Default | Description |
|---|---|---|---|
| `enabled` | `boolean` | `true` | Set to `false` to disable automatic fetching |
| `staleTime` | `number \| Infinity` | `0` | Time in ms before data is considered stale |
| `gcTime` | `number \| Infinity` | `300000` | Time in ms before inactive cache data is garbage collected |
| `retry` | `boolean \| number` | `3` | How many times to retry on failure |
| `retryDelay` | `number \| function` | — | Delay in ms between retry attempts |
| `refetchInterval` | `number \| false \| function` | — | Continuously refetch at this interval in ms |
| `refetchOnMount` | `boolean \| 'always'` | `true` | Refetch on component mount if data is stale |
| `refetchOnWindowFocus` | `boolean \| 'always'` | `true` | Refetch when the window regains focus |
| `refetchOnReconnect` | `boolean \| 'always'` | `true` | Refetch when network reconnects |
| `refetchIntervalInBackground` | `boolean` | — | Keep refetching even when tab is in background |
| `placeholderData` | `GetOrderbookResult \| function` | — | Placeholder data shown while query is pending (not persisted to cache) |
| `initialData` | `GetOrderbookResult \| function` | — | Initial data for the cache (persisted) |
| `initialDataUpdatedAt` | `number \| function` | — | Timestamp of when `initialData` was last updated |
| `select` | `function` | — | Transform or select a subset of the returned data |
| `notifyOnChangeProps` | `string[] \| 'all'` | — | Limit re-renders to specific property changes |
| `structuralSharing` | `boolean \| function` | `true` | Retain references from old data for performance |
| `networkMode` | `'online' \| 'always' \| 'offlineFirst'` | `'online'` | Controls when queries can run relative to network status |
| `meta` | `Record<string, unknown>` | — | Attach arbitrary metadata to the query cache entry |
| `queryClient` | `QueryClient` | — | Use a custom QueryClient instead of the nearest context one |

## Return Type

### `data`
`GetOrderbookResult | undefined`
```tsx
type GetOrderbookResult = {
  builder: OrderbookCallBuilder;
  response: Horizon.ServerApi.OrderbookRecord;
};
```

### Status Booleans

| Property | Type | Description |
|---|---|---|
| `isPending` | `boolean` | No cached data and no completed fetch yet |
| `isSuccess` | `boolean` | Query resolved successfully |
| `isError` | `boolean` | Query failed |
| `isLoading` | `boolean` | First fetch in-flight (`isFetching && isPending`) |
| `isFetching` | `boolean` | Query function is currently executing |
| `isRefetching` | `boolean` | Background refetch in progress |
| `isFetched` | `boolean` | Query has been fetched at least once |
| `isFetchedAfterMount` | `boolean` | Query fetched after component mounted |
| `isStale` | `boolean` | Cached data is stale or older than `staleTime` |
| `isPlaceholderData` | `boolean` | Currently showing placeholder data |
| `isLoadingError` | `boolean` | Failed on the first fetch |
| `isRefetchError` | `boolean` | Failed during a background refetch |
| `isPaused` | `boolean` | Query wanted to fetch but was paused |

### Other Returns

| Property | Type | Description |
|---|---|---|
| `status` | `'pending' \| 'success' \| 'error'` | Current query status |
| `fetchStatus` | `'fetching' \| 'idle' \| 'paused'` | Current fetch status |
| `error` | `null \| Error` | Error object if the query failed |
| `dataUpdatedAt` | `number` | Timestamp of last successful fetch |
| `errorUpdatedAt` | `number` | Timestamp of last error |
| `errorUpdateCount` | `number` | Total number of errors |
| `failureCount` | `number` | Failures since last success |
| `failureReason` | `null \| Error` | Reason for last retry failure |
| `refetch` | `function` | Manually trigger a refetch |