Skip to main content
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.

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:

Configuration

TrustwareConfigOptions

The shape passed to TrustwareProvider and Trustware.init. It is a discriminated union on mode: routes is required in deposit mode and optional in swap mode.
RoutesConfig is exported and importable. CommonConfigOptions, which holds apiKey and every non-routes field, is internal to the declaration and is not exported, so import TrustwareConfigOptions itself rather than composing from its parts. Expanded for deposit mode, which is what you get when mode is omitted. In swap mode the same shape applies except that mode: "swap" is required and routes becomes optional:

RoutesConfig

The routes object, exported as a named type since SDK 1.1.9. Required in deposit mode; optional and partial in swap mode.
See route configuration for what each field does.

ResolvedTrustwareConfig

The config object returned by Trustware.getConfig(). All optional fields have defaults applied.
Config resolution carries routes.fromChain through to the resolved object at runtime, but the exported ResolvedTrustwareConfig declaration above does not list it. Do not rely on reading fromChain back off Trustware.getConfig() in typed code until the declaration is updated.

RetryConfig

Controls how the SDK handles 429 Too Many Requests responses.

RateLimitInfo

Passed to RetryConfig callbacks when rate limit headers are present in a response.

WalletConnectConfig

Optional WalletConnect overrides. The SDK includes built-in defaults for all fields.

SwapTokenRef

A token identified by its contract address and chain ID. Used by the swap-mode fields in FeatureFlags.
chainId is numeric, so SwapTokenRef can only express EVM destinations. Cosmos chains are identified by named strings such as cataclysm-1 and cannot be set through swapDefaultDestToken or swapAllowedDestTokens.

FeatureFlags

Controls optional SDK behaviours. Pass as features in TrustwareConfigOptions.
Example: disable GA4 while leaving the other flags at their defaults.

Widget

TrustwareWidgetRef

The type of the imperative handle returned when you pass a ref to TrustwareWidget.

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.
Event reference:

Errors

TrustwareError

Extends the native Error class. All SDK errors are instances of this class.

TrustwareErrorCode

Enum of all error codes that can appear on a TrustwareError.

SDKRPCError

Trustware.sendRouteTransaction() polls the approval transaction status while it handles source token approvals. If that lookup fails, it throws an error whose name is "SDKRPCError". A failed allowance read does not throw; the SDK submits the approval anyway. This class is not exported, so identify it by name rather than with instanceof.
It is not a TrustwareError, so it carries no TrustwareErrorCode.

Routes & Transactions

BuildRouteResult

Returned by Trustware.buildRoute.
txReq is the transaction to sign and broadcast. Its type is not currently exported under its own name, so refer to it as BuildRouteResult["txReq"] in your own code rather than importing a named type. sponsorship is present when the route is gas sponsored.

PostHookRequest

An optional contract call executed on the destination chain once routed funds arrive. Pass it as hooks.postHook on Trustware.buildRoute or Trustware.buildDepositAddress. Omit hooks entirely and route behavior is unchanged. Destination calls are EVM only.
buildRoute rejects the request before it is sent when target or callData is missing, when fullAmount is true without amountInputPos, or when neither fundAmount nor fullAmount is supplied. These rejections are thrown as a plain Error, not a TrustwareError, so they carry no code.
Requires SDK 1.1.10 or later. Destination posthooks are available through the headless core and the REST API. The widget and Trustware.runTopUp() do not accept a hooks field. See vault destinations.

RouteApproval

An ERC-20 allowance on the source chain that must be granted before route.execution.transaction can succeed. Appears on RoutePlan.execution.approvals.
Every field is optional, so an entry can arrive incomplete. Trustware.sendRouteTransaction() skips any entry without a spender, a tokenAddress, and a non-zero amount, and your own signing code should do the same.
When execution.approvals is present, treat it as authoritative rather than assuming the spender is execution.transaction.to. See token approvals. This is a source-chain allowance and is unrelated to PostHookRequest.toApprovalAddress, which controls a destination-chain allowance.

RoutePlan

The resolved route on BuildRouteResult.route. Every field is optional.
execution.transaction is typed as TxRequest in the SDK declaration, but that name is not exported from a package entry point. Refer to the shape as BuildRouteResult["txReq"] in your own code rather than importing it.

RouteSponsorship

Present on BuildRouteResult.sponsorship and RoutePlan.sponsorship when the route is gas sponsored. Exported from @trustware/sdk.
When a route carries a sponsorship whose callDataHash does not match the route calldata, the SDK ignores the sponsorship and falls back to the ordinary path, including the source token approval.

RouteEstimate

Amount and fee estimates for a resolved route, on RoutePlan.estimate. Every field is optional.
The USD fields here use lowercase Usd. The separate BuildRouteResult.finalExchangeRate object uses uppercase USD (fromAmountUSD, toAmountMinUSD). Both spellings are correct for their own object.

Transaction

Returned by Trustware.getStatus and Trustware.pollStatus. Also passed to config.onSuccess.
origin_eoa is the connected EOA that originated the payment when the sender is a smart account. It is optional, EVM and smart-account relevant, and distinct from fromAddress. toAmountWei is a pre-trade quote estimate copied in when the transaction was submitted. It is exact only once landed_amount_verified is true, which indicates Trustware confirmed the destination amount by reading the destination chain. Check the flag before you use the amount to drive anything automatic.

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.

Balances

BalanceRow

A single token balance entry returned by Trustware.getBalances.
Cosmos balances arrive with category: "bank", including the chain’s native token. The union above is the type as the SDK currently declares it and does not enumerate that value, so widen your own narrowing if you switch on category. Do not assume "native" identifies the native row on a Cosmos chain.

WalletAddressBalanceWrapper

Wraps a set of BalanceRow entries for a specific chain, returned by Trustware.getBalancesByAddress.

BalanceStreamOptions

Options accepted by Trustware.getBalancesByAddress and Trustware.getBalancesByAddressStream.