Skip to main content

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.

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

typeWhen it firesAdditional fields
errorAn SDK error occurserror: TrustwareError
transaction_startedA transaction is submitted to the wallet—
transaction_successThe transaction is confirmedtxHash: string, transaction?: Transaction
wallet_connectedA wallet is connectedaddress: string
token_page_loadedA paginated token list loads successfullychainRef: string, count: number, hasNextPage: boolean, query?: string, cursor?: string
token_page_errorA paginated token list fails to loadchainRef: string, message: string, query?: string, cursor?: string
balance_stream_chunkA streaming balance response delivers a chunkaddress: string, chunkSize: number
balance_stream_fallbackThe balance stream falls back to a non-streaming pathaddress: string, message: string
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.

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