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

import { useOrderbook, Asset } from "@bluxcc/react";

Usage

Basic usage with required arguments:

import { useOrderbook, Asset } from "@bluxcc/react";

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

  const { data } = useOrderbook([selling, buying]);
}

root.render(
  <BluxProvider
    config={{
      appName: "MyApp",
      networks: [networks.testnet, networks.mainnet],
    }}
  >
    <App />
  </BluxProvider>
);

With call-builder options and TanStack Query options:

import { useOrderbook, Asset } from "@bluxcc/react";

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
  );
}

root.render(
  <BluxProvider
    config={{
      appName: "MyApp",
      networks: [networks.testnet, networks.mainnet],
    }}
  >
    <App />
  </BluxProvider>
);

Pass required arguments first, then core call-builder options, then TanStack Query options. The hook relies on this order to work correctly.

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

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

useOrderbook

On this page