# useOperations

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

Fetch a paginated list of Stellar operations in your React app using the Blux SDK.

The `useOperations` hook returns a paginated list of Stellar operations. All parameters are optional — called with no arguments it returns the latest operations from the network.

`forAccount` accepts `G…`, `M…`, SEP-2 federation, or `.xlm`. See
[address resolution](/javascript/core/address-resolution).

## Import
```tsx
```

## Usage

Called with no arguments:

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

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

Combine with `useBlux` to fetch operations only when the user is authenticated:

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

function App() {
  const { user, isAuthenticated } = useBlux();
  const { data } = useOperations(
    { forAccount: user?.address },
    { enabled: isAuthenticated }
  );
}
```
</Tab>
<Tab value="config.ts">
```tsx
root.render(
  <BluxProvider
    config={{
      appName: "MyApp",
      networks: [networks.testnet, networks.mainnet],
    }}
  >
    <App />
  </BluxProvider>
);
```
</Tab>
</Tabs>

With filters and TanStack Query options:

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

function App() {
  const { data, isStale } = useOperations(
    { forLedger: 60221517 },
    { retry: 2, staleTime: 60000 }
  );
}
```
</Tab>
<Tab value="config.ts">
```tsx
root.render(
  <BluxProvider
    config={{
      appName: "MyApp",
      networks: [networks.testnet, networks.mainnet],
    }}
  >
    <App />
  </BluxProvider>
);
```
</Tab>
</Tabs>

<Callout type="info">
  Always pass core parameters first, then TanStack Query options. The hook relies on this order to work correctly.
</Callout>

## Parameters

### `forAccount`
`string | undefined`

Fetch operations for a specific Stellar account ID.

### `forClaimableBalance`
`string | undefined`

Fetch operations related to a specific claimable balance ID.

### `forLedger`
`number | string | undefined`

Fetch operations included in a specific ledger sequence.

### `forTransaction`
`string | undefined`

Fetch operations related to a specific transaction hash.

### `forLiquidityPool`
`string | undefined`

Fetch operations related to a specific liquidity pool ID.

### `includeFailed`
`boolean | undefined`

When `true`, includes failed operations in the results.

### `cursor`
`string | undefined`

Pagination cursor for fetching the next or previous page.

### `limit`
`number | undefined`

Number of records to return per page.

### `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` | `GetOperationsResult \| function` | — | Placeholder data shown while query is pending (not persisted to cache) |
| `initialData` | `GetOperationsResult \| 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`
`GetOperationsResult | undefined`
```tsx
type GetOperationsResult = {
  builder: OperationCallBuilder; // .next() and .prev() for pagination
  response: Horizon.ServerApi.CollectionPage<Horizon.ServerApi.OperationRecord>;
};
```

### 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 |