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`	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`

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 disabled by default, so balance_stream_chunk and balance_stream_fallback do not fire until you set it to true. 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