Trustware SDK lifecycle events reference

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.

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`

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.

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

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.

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.

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;
  }
},

Get Started

Integration

Configuration

Events & Errors

Guides

SDK Reference

Trustware SDK lifecycle events reference

The `TrustwareEvent` type

Event types

The `onSuccess` shortcut

Example: tracking deposit completion

​The TrustwareEvent type

​Event types

​How to subscribe

​The onSuccess shortcut

​Example: tracking deposit completion

The `TrustwareEvent` type

Event types

How to subscribe

The `onSuccess` shortcut

Example: tracking deposit completion