> ## 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` | One chain's balances arrived from the streamed address scan; fires once per chain | `address: string`, `chunkSize: number` |
| `balance_stream_fallback` | The streamed scan was refused, aborted or failed, and the SDK re-ran it against the buffered endpoint | `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. `tokensPagination` is enabled by default, so set it to `false` in `features` to suppress its events. `balanceStreaming` is enabled by default from SDK 1.1.12 (off by default on 1.1.11 and earlier), but it permits streaming rather than forcing it: `balance_stream_chunk` fires only for scans that actually stream, so the widget's balance fetches and `Trustware.getBalancesByAddressStream` emit chunks while a buffered `Trustware.getBalancesByAddress` call emits none. Set the flag to `false` to suppress both events and use the buffered request everywhere. `swap_route_changed` fires only when the widget runs in swap mode.
</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;
  }
},
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.