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
errorAny SDK error (includes API key validation, tx failures, etc.)error: TrustwareError
transaction_startedWallet opens with the transaction promptnone
transaction_successTx confirmed on-chain; carries txHash and optional Transaction recordtxHash: string, transaction?: Transaction
wallet_connectedWallet attached; carries addressaddress: string
token_page_loadedToken list page fetched (with pagination metadata)chainRef: string, count: number, hasNextPage: boolean, query?: string, cursor?: string
token_page_errorToken list fetch failedchainRef: string, message: string, query?: string, cursor?: string
balance_stream_chunkWallet balance scan chunk receivedaddress: string, chunkSize: number
balance_stream_fallbackBalance scan fell back to a slower methodaddress: 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;
  }
},