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

# useSettlement

> Subscribe to a single settlement with real-time state updates.

## Import

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

## Usage

```tsx theme={null}
function SettlementView({ settlementId }) {
  const { settlement, isLoading, error, refetch } = useSettlement(settlementId);

  if (isLoading) return <Spinner />;
  if (error) return <Error message={error} />;
  if (!settlement) return <NotFound />;

  return (
    <div>
      <h2>{settlement.external_reference}</h2>
      <p>State: {settlement.state}</p>
      <p>Parties: {settlement.parties.length}</p>
      <p>Legs: {settlement.legs.length}</p>
    </div>
  );
}
```

## Parameters

| Parameter      | Type             | Required | Description                                        |
| -------------- | ---------------- | -------- | -------------------------------------------------- |
| `settlementId` | `string \| null` | Yes      | The settlement UUID. Pass `null` to skip fetching. |

## Return Type

```typescript theme={null}
interface UseSettlementResult {
  settlement: Settlement | null;
  isLoading: boolean;
  error: string | null;
  refetch: () => Promise<void>;
}
```

| Property     | Type                  | Description                                   |
| ------------ | --------------------- | --------------------------------------------- |
| `settlement` | `Settlement \| null`  | The settlement data, or `null` if not loaded. |
| `isLoading`  | `boolean`             | `true` during the initial fetch.              |
| `error`      | `string \| null`      | Error message if the fetch failed.            |
| `refetch`    | `() => Promise<void>` | Manually trigger a re-fetch.                  |

## Behavior

* Fetches the settlement on mount and whenever `settlementId` changes.
* Subscribes to real-time updates via the event bus (polling in Phase 1, SSE in Phase 2).
* When a `state_changed` event is received, the settlement object updates automatically.
* Passing `null` as `settlementId` clears the settlement and stops subscriptions.

## Settlement Object

The returned `settlement` includes parties and legs:

```typescript theme={null}
interface Settlement {
  id: string;
  state: string;
  template_slug?: string;
  external_reference?: string;
  idempotency_key: string;
  timeout_at: string;
  created_at: string;
  updated_at: string;
  parties: SettlementParty[];
  legs: SettlementLeg[];
}
```

The full type definitions ship with the package's TypeScript declarations.