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

# Trustware SDK lifecycle events reference

> Subscribe to typed lifecycle events from the Trustware SDK using the onEvent callback in your config.

The Trustware SDK emits typed events as users move through the deposit flow. You can subscribe to these events to track progress, update your own UI state, or send analytics without polling or manual state management.

## The `TrustwareEvent` type

All events share a discriminated union type called `TrustwareEvent`. Each variant has a `type` string field you can use to narrow the event in a handler.

```ts theme={null}
import type { TrustwareEvent } from "@trustware/sdk";
```

### Event types

| `type`                    | When it fires                                                                     | Additional fields                                                                                 |
| ------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `error`                   | Any SDK error (includes API key validation, tx failures, etc.)                    | `error: TrustwareError`                                                                           |
| `transaction_started`     | Wallet opens with the transaction prompt                                          | none                                                                                              |
| `transaction_success`     | Tx confirmed on-chain; carries `txHash` and optional `Transaction` record         | `txHash: string`, `transaction?: Transaction`                                                     |
| `wallet_connected`        | Wallet attached; carries `address`                                                | `address: string`                                                                                 |
| `token_page_loaded`       | Token list page fetched (with pagination metadata)                                | `chainRef: string`, `count: number`, `hasNextPage: boolean`, `query?: string`, `cursor?: string`  |
| `token_page_error`        | Token list fetch failed                                                           | `chainRef: string`, `message: string`, `query?: string`, `cursor?: string`                        |
| `balance_stream_chunk`    | Wallet balance scan chunk received                                                | `address: string`, `chunkSize: number`                                                            |
| `balance_stream_fallback` | Balance scan fell back to a slower method                                         | `address: string`, `message: string`                                                              |
| `swap_route_changed`      | Swap-mode route changed (different source or destination chain, token, or amount) | `fromChain: string`, `fromToken: string`, `toChain: string`, `toToken: string`, `amount?: string` |

<Note>
  `token_page_loaded`, `token_page_error`, `balance_stream_chunk`, and `balance_stream_fallback` are gated by the `tokensPagination` and `balanceStreaming` feature flags. Both are enabled by default; set either flag to `false` in `features` to suppress the corresponding events. `swap_route_changed` fires only when the widget runs in swap mode (`swapMode: true`).
</Note>

## How to subscribe

Pass an `onEvent` callback in your `TrustwareConfigOptions`. This works whether you are using `TrustwareProvider` or calling `Trustware.init()` directly in the headless core.

```ts theme={null}
import { TrustwareProvider, type TrustwareConfigOptions } from "@trustware/sdk";

const config = {
  apiKey: process.env.NEXT_PUBLIC_TRUSTWARE_API_KEY!,
  routes: {
    toChain: "8453",
    toToken: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  },
  onEvent: (event) => {
    if (event.type === "transaction_success") {
      console.log("TX hash:", event.txHash);
    }
  },
} satisfies TrustwareConfigOptions;
```

TypeScript narrows `event` to the correct shape inside each `if` branch, so accessing `event.txHash` is fully type-safe.

## The `onSuccess` shortcut

For the common case of reacting to a completed deposit, you can use `onSuccess` instead of filtering inside `onEvent`. It receives the `Transaction` object directly.

```ts theme={null}
const config = {
  apiKey: process.env.NEXT_PUBLIC_TRUSTWARE_API_KEY!,
  routes: {
    toChain: "8453",
    toToken: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  },
  onSuccess: (transaction) => {
    console.log(transaction);
  },
} satisfies TrustwareConfigOptions;
```

`onSuccess` and `onEvent` are independent; you can use both at the same time.

## Example: tracking deposit completion

The following example shows how to use `onEvent` to display a success notification when a deposit completes, and log any errors to an external service.

```ts theme={null}
onEvent: (event) => {
  switch (event.type) {
    case "transaction_success":
      showToast(`Deposit confirmed (tx: ${event.txHash})`);
      break;
    case "wallet_connected":
      analytics.track("wallet_connected", { address: event.address });
      break;
    case "error":
      errorLogger.capture(event.error);
      break;
  }
},
```