> ## 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. # TypeScript types exported from @trustware/sdk > All public TypeScript types and enums exported by @trustware/sdk: config shapes, error classes, event types, and wallet interfaces. All types below are exported from `@trustware/sdk` and are available as named imports. You can use them to type your own integration code without importing runtime values. ```ts theme={null} import type { TrustwareConfigOptions, TrustwareEvent, TrustwareError, WalletInterFaceAPI, } from "@trustware/sdk"; ``` ### Public import paths The package exposes its public surface through the root entry plus four scoped sub-paths. Pick whichever import keeps your bundle smallest: | Import path | Contents | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `@trustware/sdk` | Everything — `Trustware`, `TrustwareProvider`, `TrustwareWidget`, types, constants, wallet helpers. Most integrations use only this. | | `@trustware/sdk/wallet` | Wallet adapters and detection — `useWagmi`, `useEIP1193`, `connectDetectedWallet`, related helpers. | | `@trustware/sdk/core` | The `Trustware` facade and core REST methods, without widget code. | | `@trustware/sdk/react` | The `TrustwareWidget` component bundle. | | `@trustware/sdk/constants` | `SDK_VERSION`, `API_ROOT`, `WALLETCONNECT_PROJECT_ID`, and other constants. | *** ## Configuration ### `TrustwareConfigOptions` The shape passed to `TrustwareProvider` and `Trustware.init`. ```ts theme={null} type TrustwareConfigOptions = { apiKey: string; routes: { toChain: string; toToken: string; fromToken?: string; fromAddress?: string; toAddress?: string; defaultSlippage?: number; options?: { routeRefreshMs?: number; fixedFromAmount?: string | number; minAmountOut?: string | number; maxAmountOut?: string | number; }; }; autoDetectProvider?: boolean; theme?: TrustwareWidgetTheme; messages?: Partial; retry?: RetryConfig; walletConnect?: WalletConnectConfig; features?: FeatureFlags; onError?: (error: TrustwareError) => void; onSuccess?: (transaction: Transaction) => void; onEvent?: (event: TrustwareEvent) => void; }; ``` | Field | Required | Description | | ------------------------- | -------- | ---------------------------------------------------------------------------------- | | `apiKey` | Yes | Your Trustware API key. | | `routes.toChain` | Yes | Default destination chain ID (e.g. `"8453"` for Base). | | `routes.toToken` | Yes | Default destination token address or symbol. | | `routes.toAddress` | No | Recipient address. Can be set later via `Trustware.setDestinationAddress`. | | `routes.defaultSlippage` | No | Slippage percentage. Defaults to `1`. | | `autoDetectProvider` | No | Whether to auto-detect the wallet provider. Defaults to `false`. | | `features.shouldAllowGA4` | No | Set to `false` to disable SDK GA4 analytics tracking. Defaults to `true`. | | `theme` | No | Widget color and radius overrides. See `TrustwareWidgetTheme`. | | `messages` | No | Widget title and description overrides. See `TrustwareWidgetMessages`. | | `retry` | No | Retry and rate-limit callback configuration. See `RetryConfig`. | | `walletConnect` | No | WalletConnect connector overrides. See `WalletConnectConfig`. | | `onError` | No | Callback fired on any `TrustwareError`. | | `onSuccess` | No | Callback fired when a transaction is confirmed. Receives the `Transaction` object. | | `onEvent` | No | Callback fired for all SDK lifecycle events. Receives a `TrustwareEvent`. | *** ### `ResolvedTrustwareConfig` The config object returned by `Trustware.getConfig()`. All optional fields have defaults applied. ```ts theme={null} type ResolvedTrustwareConfig = { apiKey: string; routes: { toChain: string; toToken: string; fromToken?: string; fromAddress?: string; toAddress?: string; defaultSlippage: number; options: { routeRefreshMs?: number; fixedFromAmount?: string | number; minAmountOut?: string | number; maxAmountOut?: string | number; }; }; autoDetectProvider: boolean; theme: TrustwareWidgetTheme; messages: TrustwareWidgetMessages; retry: ResolvedRetryConfig; walletConnect?: ResolvedWalletConnectConfig; features: ResolvedFeatureFlags; onError?: (error: TrustwareError) => void; onSuccess?: (transaction: Transaction) => void; onEvent?: (event: TrustwareEvent) => void; }; ``` *** ### `RetryConfig` Controls how the SDK handles `429 Too Many Requests` responses. ```ts theme={null} type RetryConfig = { autoRetry?: boolean; maxRetries?: number; baseDelayMs?: number; onRateLimitInfo?: (info: RateLimitInfo) => void; onRateLimited?: (info: RateLimitInfo, retryCount: number) => void; onRateLimitApproaching?: (info: RateLimitInfo, threshold: number) => void; approachingThreshold?: number; }; ``` | Field | Default | Description | | ---------------------- | ------- | --------------------------------------------------------------- | | `autoRetry` | `true` | Retry automatically on 429 responses. | | `maxRetries` | `3` | Maximum retry attempts. | | `baseDelayMs` | `1000` | Base delay for exponential backoff in milliseconds. | | `approachingThreshold` | `5` | Remaining-request count that triggers `onRateLimitApproaching`. | *** ### `RateLimitInfo` Passed to `RetryConfig` callbacks when rate limit headers are present in a response. ```ts theme={null} type RateLimitInfo = { limit: number; remaining: number; reset: number; retryAfter?: number; }; ``` *** ### `WalletConnectConfig` Optional WalletConnect overrides. The SDK includes built-in defaults for all fields. ```ts theme={null} type WalletConnectConfig = { projectId?: string; chains?: number[]; optionalChains?: number[]; metadata?: { name: string; description?: string; url: string; icons?: string[]; }; relayUrl?: string; showQrModal?: boolean; disabled?: boolean; }; ``` *** ### `SwapTokenRef` A token identified by its contract address and chain ID. Used by the swap-mode fields in `FeatureFlags`. ```ts theme={null} type SwapTokenRef = { address: string; chainId: number; }; ``` *** ### `FeatureFlags` Controls optional SDK behaviours. Pass as `features` in `TrustwareConfigOptions`. ```ts theme={null} type FeatureFlags = { tokensPagination?: boolean; balanceStreaming?: boolean; shouldAllowGA4?: boolean; swapMode?: boolean; swapDefaultDestToken?: SwapTokenRef; swapLockDestToken?: boolean; swapAllowedDestTokens?: SwapTokenRef[]; }; ``` | Field | Default | Description | | ----------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tokensPagination` | `true` | Paginated token list fetching in the widget's token picker. Emits `token_page_loaded` and `token_page_error` events. Set to `false` to fetch the full token list in a single request. | | `balanceStreaming` | `true` | Streaming balance fetches across chains. Emits `balance_stream_chunk` and `balance_stream_fallback` events. Set to `false` to wait for all chains before rendering balances. | | `shouldAllowGA4` | `true` | When `false`, disables the SDK's built-in Google Analytics 4 (GA4) tracking. Set this to `false` if your app has its own analytics pipeline, your users have opted out of tracking, or you need to comply with privacy regulations such as GDPR or CCPA. | | `swapMode` | `false` | Enables swap mode, turning the widget into a standalone swap experience that settles to the user's own connected wallet. See [swap mode](/guides/swap-mode). | | `swapDefaultDestToken` | none | Pre-selects the destination token (`SwapTokenRef`) shown when the widget opens in swap mode. | | `swapLockDestToken` | `false` | Locks the swap destination so the user cannot change it. Use with `swapDefaultDestToken`. | | `swapAllowedDestTokens` | none | Restricts the swap destination-token picker to this list of `SwapTokenRef` entries. Everything else is locked out. | **Example — disable GA4 while keeping pagination and streaming on:** ```ts theme={null} const config = { apiKey: process.env.NEXT_PUBLIC_TRUSTWARE_API_KEY!, routes: { toChain: "8453", toToken: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", }, features: { shouldAllowGA4: false, }, } satisfies TrustwareConfigOptions; ``` *** ## Widget ### `TrustwareWidgetRef` The type of the imperative handle returned when you pass a `ref` to `TrustwareWidget`. ```ts theme={null} interface TrustwareWidgetRef { open: () => void; close: () => void; isOpen: () => boolean; } ``` *** ## Events ### `TrustwareEvent` A discriminated union of all events emitted via `config.onEvent`. Each variant has a `type` field you can use to narrow the type. ```ts theme={null} type TrustwareEvent = | { type: "error"; error: TrustwareError } | { type: "transaction_started" } | { type: "transaction_success"; txHash: string; transaction?: Transaction } | { type: "wallet_connected"; address: string } | { type: "token_page_loaded"; chainRef: string; query?: string; count: number; hasNextPage: boolean; cursor?: string; } | { type: "token_page_error"; chainRef: string; query?: string; cursor?: string; message: string; } | { type: "balance_stream_chunk"; address: string; chunkSize: number; } | { type: "balance_stream_fallback"; address: string; message: string; } | { type: "swap_route_changed"; fromChain: string; fromToken: string; toChain: string; toToken: string; amount?: string; }; ``` **Event reference:** | `type` | When it fires | | ------------------------- | ----------------------------------------------------------------------------------------- | | `error` | Any SDK error, including API failures and invalid config. | | `transaction_started` | A transaction has been initiated. | | `transaction_success` | A transaction completed successfully. | | `wallet_connected` | A wallet was attached to the SDK. | | `token_page_loaded` | A page of tokens was fetched (pagination). | | `token_page_error` | A token page fetch failed. | | `balance_stream_chunk` | A chunk of balances arrived from the streaming endpoint. | | `balance_stream_fallback` | Streaming failed and the SDK fell back to a single request. | | `swap_route_changed` | In swap mode, the resolved route changed (source or destination chain, token, or amount). | *** ## Errors ### `TrustwareError` Extends the native `Error` class. All SDK errors are instances of this class. ```ts theme={null} class TrustwareError extends Error { code: TrustwareErrorCode; userMessage?: string; cause?: unknown; } ``` | Field | Description | | ------------- | -------------------------------------------------------- | | `code` | Machine-readable error code (`TrustwareErrorCode` enum). | | `message` | Developer-facing error message. | | `userMessage` | Optional user-facing message suitable for display in UI. | | `cause` | The underlying error that triggered this one, if any. | *** ### `TrustwareErrorCode` Enum of all error codes that can appear on a `TrustwareError`. ```ts theme={null} enum TrustwareErrorCode { INVALID_CONFIG = "INVALID_CONFIG", INVALID_API_KEY = "INVALID_API_KEY", WALLET_NOT_CONNECTED = "WALLET_NOT_CONNECTED", BRIDGE_FAILED = "BRIDGE_FAILED", NETWORK_ERROR = "NETWORK_ERROR", UNKNOWN_ERROR = "UNKNOWN_ERROR", INPUT_ERROR = "INPUT_ERROR", } ``` | Code | Description | | ---------------------- | ---------------------------------------------------------------------- | | `INVALID_CONFIG` | The config object is missing required fields or has invalid values. | | `INVALID_API_KEY` | API key validation against the Trustware backend failed. | | `WALLET_NOT_CONNECTED` | A wallet operation was attempted before a wallet was attached. | | `BRIDGE_FAILED` | The bridge transaction failed on-chain or was rejected by the backend. | | `NETWORK_ERROR` | A network request failed (timeout, DNS failure, etc.). | | `UNKNOWN_ERROR` | An unexpected error with no specific classification. | | `INPUT_ERROR` | Invalid user input, such as a malformed address or unsupported chain. | *** ## Routes & Transactions ### `BuildRouteResult` Returned by `Trustware.buildRoute`. ```ts theme={null} type BuildRouteResult = { intentId: string; txReq: TxRequest; actions: unknown[]; finalExchangeRate: { fromAmountUSD?: string; toAmountMinUSD?: string; }; route: RoutePlan | undefined; }; ``` *** ### `Transaction` Returned by `Trustware.getStatus` and `Trustware.pollStatus`. Also passed to `config.onSuccess`. ```ts theme={null} type Transaction = { id: string; intentId: string; fromAddress: string; toAddress: string; fromChainId: string | number; toChainId: string | number; sourceTxHash: string; destTxHash: string; requestId: string; transactionRequest: unknown; status: "submitted" | "bridging" | "success" | "failed"; statusRaw?: unknown; routePath?: unknown; routeStatus?: unknown; toAmountWei?: string | number; fromChainBlock: number; toChainBlock: number; fromChainTxUrl?: string; toChainTxUrl?: string; gasStatus?: string; isGMPTransaction?: boolean; axelarTransactionUrl?: string; createdDate: Date | string; updatedDate: Date | string; timeSpentMs?: number; }; ``` *** ## Wallet ### `WalletInterFaceAPI` The union type accepted by `Trustware.useWallet` and the `wallet` prop on `TrustwareProvider`. It is either an EVM wallet interface or a Solana wallet interface. ```ts theme={null} type WalletInterFaceAPI = EvmWalletInterface | SolanaWalletInterface; type EvmWalletInterface = { ecosystem: "evm"; getAddress(): Promise; getChainId(): Promise; switchChain(chainId: number): Promise; disconnect?(): Promise; } & ( | { type: "eip1193"; request(args: { method: string; params?: unknown[] | object }): Promise; } | { type: "wagmi"; sendTransaction(tx: { to: `0x${string}`; data: `0x${string}`; value?: bigint; chainId?: number; }): Promise<{ hash: `0x${string}` }>; } ); type SolanaWalletInterface = { ecosystem: "solana"; type: "solana"; getAddress(): Promise; getChainKey(): Promise; sendSerializedTransaction( serializedTransactionBase64: string, chainId?: string ): Promise; disconnect?(): Promise; }; ``` *** ## Balances ### `BalanceRow` A single token balance entry returned by `Trustware.getBalances`. ```ts theme={null} type BalanceRow = { chain_key: string; category: "native" | "erc20" | "spl" | "btc"; contract?: string; address?: string; symbol?: string; decimals: number; balance: string; name?: string; logoURI?: string; usdPrice?: number; }; ``` *** ### `WalletAddressBalanceWrapper` Wraps a set of `BalanceRow` entries for a specific chain, returned by `Trustware.getBalancesByAddress`. ```ts theme={null} type WalletAddressBalanceWrapper = { chain_id: string; balances: BalanceRow[]; count: number; error: string | null; source: string; }; ``` *** ### `BalanceStreamOptions` Options accepted by `Trustware.getBalancesByAddress` and `Trustware.getBalancesByAddressStream`. ```ts theme={null} type BalanceStreamOptions = { stream?: boolean; signal?: AbortSignal; strict?: boolean; }; ```