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

# useSettlements

> Fetch a paginated list of settlements with optional state filter.

## Import

```tsx theme={null}
import { useSettlements } from '@keystoneos/react';
```

## Usage

```tsx theme={null}
function SettlementList() {
  const { settlements, total, isLoading, error } = useSettlements({
    state: 'AWAITING_DEPOSITS',
    limit: 20,
    offset: 0,
  });

  if (isLoading) return <Spinner />;

  return (
    <div>
      <p>{total} settlements</p>
      {settlements.map(s => (
        <div key={s.id}>
          {s.external_reference} - {s.state}
        </div>
      ))}
    </div>
  );
}
```

## Parameters

| Parameter | Type                    | Required | Description                    |
| --------- | ----------------------- | -------- | ------------------------------ |
| `options` | `UseSettlementsOptions` | No       | Filter and pagination options. |

### UseSettlementsOptions

| Property | Type     | Default | Description                                       |
| -------- | -------- | ------- | ------------------------------------------------- |
| `state`  | `string` | -       | Filter by settlement state (e.g., `"FINALIZED"`). |
| `limit`  | `number` | `50`    | Maximum items per page.                           |
| `offset` | `number` | `0`     | Number of items to skip.                          |

## Return Type

```typescript theme={null}
interface UseSettlementsResult {
  settlements: Settlement[];
  total: number;
  isLoading: boolean;
  error: string | null;
  refetch: () => Promise<void>;
}
```

| Property      | Type                  | Description                                            |
| ------------- | --------------------- | ------------------------------------------------------ |
| `settlements` | `Settlement[]`        | Array of settlements for the current page.             |
| `total`       | `number`              | Total number of matching settlements (for pagination). |
| `isLoading`   | `boolean`             | `true` during fetch.                                   |
| `error`       | `string \| null`      | Error message if the fetch failed.                     |
| `refetch`     | `() => Promise<void>` | Manually trigger a re-fetch.                           |

## Behavior

* Fetches on mount and whenever options change.
* Re-fetches automatically when `state`, `limit`, or `offset` changes.
* Returns settlements scoped to the platform and environment in the session token.

## Pagination Example

```tsx theme={null}
function PaginatedList() {
  const [page, setPage] = useState(0);
  const pageSize = 20;

  const { settlements, total } = useSettlements({
    limit: pageSize,
    offset: page * pageSize,
  });

  const totalPages = Math.ceil(total / pageSize);

  return (
    <div>
      {settlements.map(s => <SettlementRow key={s.id} settlement={s} />)}
      <div>
        <button onClick={() => setPage(p => p - 1)} disabled={page === 0}>Previous</button>
        <span>Page {page + 1} of {totalPages}</span>
        <button onClick={() => setPage(p => p + 1)} disabled={page >= totalPages - 1}>Next</button>
      </div>
    </div>
  );
}
```