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

# useSettlementEvents

> Fetch the event timeline for a settlement.

## Import

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

## Usage

```tsx theme={null}
function EventTimeline({ settlementId }) {
  const { events, isLoading } = useSettlementEvents(settlementId);

  if (isLoading) return <Spinner />;

  return (
    <ul>
      {events.map(event => (
        <li key={event.id}>
          <strong>{event.to_state}</strong>
          {event.from_state && <span> (from {event.from_state})</span>}
          <time>{new Date(event.created_at).toLocaleString()}</time>
          <span>{event.triggered_by}</span>
        </li>
      ))}
    </ul>
  );
}
```

## Parameters

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

## Return Type

```typescript theme={null}
interface UseSettlementEventsResult {
  events: SettlementEvent[];
  isLoading: boolean;
  error: string | null;
  refetch: () => Promise<void>;
}
```

| Property    | Type                  | Description                               |
| ----------- | --------------------- | ----------------------------------------- |
| `events`    | `SettlementEvent[]`   | Array of events, ordered chronologically. |
| `isLoading` | `boolean`             | `true` during fetch.                      |
| `error`     | `string \| null`      | Error message if fetch failed.            |
| `refetch`   | `() => Promise<void>` | Manually re-fetch events.                 |

### SettlementEvent

| Property        | Type                  | Description                                                                |
| --------------- | --------------------- | -------------------------------------------------------------------------- |
| `id`            | `string`              | Event UUID.                                                                |
| `settlement_id` | `string`              | The settlement this event belongs to.                                      |
| `from_state`    | `string \| undefined` | Previous state (undefined for the initial event).                          |
| `to_state`      | `string`              | The state after this transition.                                           |
| `triggered_by`  | `string`              | What triggered the transition (e.g., `"system:engine"`, `"m2m:platform"`). |
| `evidence_hash` | `string \| undefined` | SHA-256 hash of the transition evidence (on-chain).                        |
| `created_at`    | `string`              | ISO 8601 timestamp.                                                        |