> ## 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`. It is a discriminated union on `mode`: `routes` is required in deposit mode and optional in swap mode.

```ts theme={null}
type TrustwareConfigOptions = CommonConfigOptions &
  (
    | { mode?: "deposit"; routes: RoutesConfig }
    | { mode: "swap"; routes?: Partial<RoutesConfig> }
  );
```

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

```ts theme={null}
// Deposit mode (mode omitted or "deposit")
type TrustwareConfigOptions = {
  apiKey: string;
  mode?: "deposit" | "swap";
  routes: { // optional when mode is "swap"
    toChain: string;
    toToken: string;
    fromToken?: string;
    fromChain?: string;
    fromAddress?: string;
    toAddress?: string;
    defaultSlippage?: number;
    options?: {
      routeRefreshMs?: number;
      fixedFromAmount?: string | number;
      minAmountOut?: string | number;
      maxAmountOut?: string | number;
    };
  };
  autoDetectProvider?: boolean;
  theme?: TrustwareTheme;
  messages?: Partial<TrustwareWidgetMessages>;
  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. |
| `mode` | No | `"deposit"` (default) or `"swap"`. Requires SDK 1.1.9 or later. |
| `routes.toChain` | In deposit mode | Default destination chain ID (e.g. `"8453"` for Base). |
| `routes.toToken` | In deposit mode | Default destination token identifier: contract address on EVM, mint address on Solana, native denom on Cosmos. |
| `routes.fromToken` | No | Preferred source token, pre-selected on the source side. |
| `routes.fromChain` | No | Preferred source chain, pre-selected on the source side. Also the chain `routes.fromAddress` is validated against; falls back to `routes.toChain`. |
| `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 scheme: `"light"`, `"dark"`, or `"system"`. Defaults to `"system"`. See `TrustwareTheme`. |
| `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`. |

***

### `RoutesConfig`

The `routes` object, exported as a named type since SDK 1.1.9. Required in deposit mode; optional and partial in swap mode.

```ts theme={null}
type RoutesConfig = {
  toChain: string;
  toToken: string;
  fromToken?: string;
  fromChain?: string;
  fromAddress?: string;
  toAddress?: string;
  defaultSlippage?: number;
  options?: {
    routeRefreshMs?: number;
    fixedFromAmount?: string | number;
    minAmountOut?: string | number;
    maxAmountOut?: string | number;
  };
};
```

See [route configuration](/configuration/routes) for what each field does.

***

### `ResolvedTrustwareConfig`

The config object returned by `Trustware.getConfig()`. All optional fields have defaults applied.

```ts theme={null}
type ResolvedTrustwareConfig = {
  apiKey: string;
  mode: "deposit" | "swap";
  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: TrustwareTheme;
  messages: TrustwareWidgetMessages;
  retry: ResolvedRetryConfig;
  walletConnect?: ResolvedWalletConnectConfig;
  features: ResolvedFeatureFlags;
  onError?: (error: TrustwareError) => void;
  onSuccess?: (transaction: Transaction) => void;
  onEvent?: (event: TrustwareEvent) => void;
};
```

<Note>
  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.
</Note>

***

### `RetryConfig`

Observability for `429 Too Many Requests` responses. Retry timing itself is not configurable: the SDK waits as long as the server's `Retry-After`, or `X-RateLimit-Reset`, states, up to a total of 10 seconds, then throws `RateLimitError`. See [Rate limiting and retry configuration](/configuration/retry).

```ts theme={null}
type RetryConfig = {
  approachingThreshold?: number;
  onRateLimitInfo?: (info: RateLimitInfo) => void;
  onRateLimited?: (info: RateLimitInfo, retryCount: number) => void;
  onRateLimitApproaching?: (info: RateLimitInfo, threshold: number) => void;
};
```

| Field | Default | Description |
| - | - | - |
| `approachingThreshold` | `5` | Remaining-request count that triggers `onRateLimitApproaching`. |

<Warning>
  `autoRetry`, `maxRetries`, and `baseDelayMs` were accepted through
  `@trustware/sdk` 1.1.10 and are removed in 1.1.11. Remove them when you
  upgrade.
</Warning>

***

### `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;
};
```

<Note>
  `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`.
</Note>

***

### `FeatureFlags`

Controls optional SDK behaviours. Pass as `features` in `TrustwareConfigOptions`.

```ts theme={null}
type FeatureFlags = {
  tokensPagination?: boolean;
  balanceStreaming?: boolean;
  shouldAllowGA4?: boolean;
  /** @deprecated Use the top-level `mode: "swap"` instead. */
  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, so the widget renders each chain's balances as they arrive instead of waiting for the slowest one. Emits `balance_stream_chunk` and `balance_stream_fallback` events. Defaulted to `true` in SDK 1.1.12; earlier versions default to `false`. Set it to `false` to force the buffered request. |
| `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` | Deprecated in SDK 1.1.9. Enables swap mode and is treated as equivalent to the top-level `mode: "swap"`, which is the preferred field. Setting it logs a deprecation warning. 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 leaving the other flags at their defaults.**

```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` | One chain's balances arrived from a streamed address scan. |
| `balance_stream_fallback` | The streamed scan was refused, aborted or failed, and the SDK re-ran it against the buffered endpoint. |
| `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. |

***

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

```ts theme={null}
try {
  await Trustware.sendRouteTransaction(route, 42161);
} catch (error) {
  if (error instanceof Error && error.name === "SDKRPCError") {
    // An approval transaction-status lookup failed. Retryable.
  }
}
```

It is not a `TrustwareError`, so it carries no `TrustwareErrorCode`.

***

## 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;
  sponsorship?: RouteSponsorship;
};
```

`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 and provider dependent.

```ts theme={null}
type PostHookRequest = {
  target: string;
  callData: string;
  value?: string;
  fundToken?: string;
  fundAmount?: string;
  fullAmount?: boolean;
  amountInputPos?: number;
  estimatedGas?: string;
  toApprovalAddress?: string;
  toFallbackAddress?: string;
  description?: string;
};
```

| Field | Required | Description |
| - | - | - |
| `target` | Yes | Contract address to call on the destination chain. Must be a valid EVM address. |
| `callData` | Yes | ABI-encoded calldata for the call. |
| `value` | Native-value calls only | Native value to send with the call, in destination base units. |
| `fundToken` | No | Token the call acts on. Defaults to the route's `toToken`. |
| `fundAmount` | Yes unless `fullAmount` is set | Predetermined destination-token amount the call is funded with, in destination base units. |
| `estimatedGas` | Recommended | Gas limit hint for the destination call. Some providers require it, so omitting it narrows which providers can serve the route. |
| `toApprovalAddress` | ERC-20 destination calls | Address allowed to pull `fundToken` when the destination contract uses `transferFrom`, normally the contract itself. Must not be set for native-value calls. |
| `fullAmount` | No | **Provider dependent.** Patch the amount argument in `callData` instead of using a predetermined `fundAmount`. Requires `amountInputPos`. See [amount patching](/guides/destination-call-options#dynamic-landed-balance-mode). |
| `amountInputPos` | With `fullAmount` | **Provider dependent**, and required whenever `fullAmount` is set. The zero-based index of the ABI argument to patch, which must be a static type such as `uint256`. Index `0` is valid. |
| `toFallbackAddress` | No | **Provider dependent.** Recipient if the destination call fails, when the resolving provider implements a fallback. Not a guarantee. |
| `description` | No | Optional free-text label for the call. Not forwarded by every provider, so do not depend on it appearing downstream. |

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

<Note>
  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](/guides/vault-destinations).
</Note>

***

### `RouteApproval`

An ERC-20 allowance on the source chain that must be granted before `route.execution.transaction` can succeed. Appears on `RoutePlan.execution.approvals`.

```ts theme={null}
type RouteApproval = {
  chainId?: string;
  tokenAddress?: string;
  spender?: string;
  amount?: string;
};
```

| Field | Description |
| - | - |
| `chainId` | Chain the allowance belongs on. Optional. The SDK falls back to the route transaction's chain, and skips the entry if neither is available. |
| `tokenAddress` | Token to approve. |
| `spender` | Address to approve the token for. Always a provider contract, never a Trustware contract. |
| `amount` | Exact amount to approve, in the token's base units. |

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.

<Warning>
  When `execution.approvals` is present, treat it as authoritative rather than
  assuming the spender is `execution.transaction.to`. See
  [token approvals](/api-reference/route#token-approvals). This is a source-chain
  allowance and is unrelated to `PostHookRequest.toApprovalAddress`, which
  controls a destination-chain allowance.
</Warning>

***

### `RoutePlan`

The resolved route on `BuildRouteResult.route`. Every field is optional.

```ts theme={null}
type RoutePlan = {
  estimate?: RouteEstimate;
  execution?: { transaction?: TxRequest; approvals?: RouteApproval[] };
  steps?: unknown[];
  provider?: string;
  requestId?: string;
  reliabilityScore?: number;
  diagnostics?: { rawPayload?: unknown };
  sponsorship?: RouteSponsorship;
};
```

| Field | Description |
| - | - |
| `estimate` | Amount and fee estimates for this route. |
| `execution.transaction` | The transaction to sign and broadcast. |
| `execution.approvals` | Source-chain ERC-20 allowances required before the route transaction can succeed. |
| `steps` | Provider-level route steps. Opaque; for debugging only. |
| `provider` | The liquidity provider selected for this route. |
| `requestId` | The routing provider's own request ID, not Trustware's. It is the value that reaches the status payload as `provider_request_id`. |
| `reliabilityScore` | Provider reliability score for this route. |
| `diagnostics` | Raw provider payload, for debugging. |
| `sponsorship` | Present when the route is gas sponsored. |

<Note>
  `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.
</Note>

***

### `RouteSponsorship`

Present on `BuildRouteResult.sponsorship` and `RoutePlan.sponsorship` when the route is gas sponsored. Exported from `@trustware/sdk`. See [Paymasters](/guides/paymasters) for how sponsorship is configured and when it applies.

```ts theme={null}
type RouteSponsorship = {
  requestId: string;
  paymaster: string;
  entryPoint: string;
  chainId: string;
  callDataHash: string;
  maxCost: string;
  paymasterAndData: string;
  signature: string;
  signer: string;
  typedDataHash: string;
  approval: SponsorshipApproval;
};
```

| Field | Description |
| - | - |
| `requestId` | Sponsorship request identifier, useful for support. |
| `paymaster` | Paymaster contract address for this sponsorship. |
| `entryPoint` | EntryPoint contract the sponsored operation targets. |
| `chainId` | Chain the sponsorship applies to. |
| `callDataHash` | Hash of the route calldata this sponsorship was issued for. `Trustware.sendRouteTransaction()` checks the route calldata against this before relying on the sponsorship. |
| `maxCost` | Maximum sponsored cost, in base units. |
| `paymasterAndData` | The paymaster payload a smart-account wallet forwards when sending. |
| `signature` | Sponsorship signature. |
| `signer` | Address that signed the sponsorship. |
| `typedDataHash` | Hash of the signed typed data. |
| `approval` | The underlying approval record. |

<Note>
  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.
</Note>

***

### `RouteEstimate`

Amount and fee estimates for a resolved route, on `RoutePlan.estimate`. Every field is optional.

```ts theme={null}
type RouteEstimate = {
  fromAmount?: string;
  toAmount?: string;
  toAmountMin?: string;
  fromAmountUsd?: string;
  toAmountUsd?: string;
  totalFeesUsd?: string;
  toAmountMinUsd?: string;
  fees?: unknown[];
};
```

| Field | Description |
| - | - |
| `fromAmount` | Source amount, in the source token's base units. |
| `toAmount` | Expected destination amount, in the destination token's base units. |
| `toAmountMin` | Guaranteed minimum destination amount after slippage. Use this when you need to know what the route will definitely deliver. |
| `fromAmountUsd` | USD value of the source amount. |
| `toAmountUsd` | USD value of the expected destination amount. |
| `toAmountMinUsd` | USD value of the guaranteed minimum. |
| `totalFeesUsd` | Total fees for the route, in USD. |
| `fees` | Per-fee breakdown. Opaque; provider shaped. |

<Note>
  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.
</Note>

***

### `Transaction`

Returned by `Trustware.getStatus` and `Trustware.pollStatus`. Also passed to `config.onSuccess`.

Only `status` is guaranteed. A `"pending"` payload is a stub: the intent exists but no receipt has landed, so there is no transaction to describe yet. Check `status` before reading anything else, and treat the few fields still typed as required, `fromChainBlock`, `toChainBlock`, `createdDate`, and `updatedDate`, as absent while the status is `"pending"`.

```ts theme={null}
type Transaction = {
  id?: string;
  intentId?: string;
  fromAddress?: string;
  toAddress?: string;
  origin_eoa?: string;
  fromChainId?: string | number;
  toChainId?: string | number;
  sourceTxHash?: string;
  destTxHash?: string;
  requestId?: string;
  providerRequestId?: string;
  transactionRequest?: unknown;
  status: "pending" | "submitted" | "bridging" | "success" | "failed";
  statusRaw?: unknown;
  routePath?: unknown;
  routeStatus?: unknown;
  toAmountWei?: string | number;
  landed_amount_verified?: boolean;
  fromChainBlock: number;
  toChainBlock: number;
  fromChainTxUrl?: string;
  toChainTxUrl?: string;
  gasStatus?: string;
  isGMPTransaction?: boolean;
  axelarTransactionUrl?: string;
  createdDate: Date | string;
  updatedDate: Date | string;
  timeSpentMs?: number;
};
```

A `"pending"` payload carries only `intentId`, `status`, `intent_status`, `create_date`, and, once the intent has an execution plan, `steps`. Everything else arrives when a receipt lands. See [GET /status](/api-reference/status#the-pending-response) for the wire payload.

`requestId` is Trustware's own ID for the call that created the intent, a UUID, and the one to quote in a support request. `providerRequestId` is the routing provider's own correlation ID. Either can be absent, so check before you log them.

<Warning>
  The status payload is snake\_case on the wire (`source_tx_hash`, `intent_id`)
  while this type is camelCase. `getStatus` maps the whole payload onto these
  camelCase names from `@trustware/sdk` 1.1.11 on, and keeps the raw wire keys
  alongside them.

  Through 1.1.10 it returned the payload unmapped, so every camelCase property
  here reads `undefined`. If you are pinned below 1.1.11, read the snake\_case
  wire names instead.
</Warning>

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

```ts theme={null}
type WalletInterFaceAPI = EvmWalletInterface | SolanaWalletInterface;

type EvmWalletInterface = {
  ecosystem: "evm";
  getAddress(): Promise<string>;
  getChainId(): Promise<number>;
  switchChain(chainId: number): Promise<void>;
  disconnect?(): Promise<void>;
} & (
  | {
      type: "eip1193";
      request(args: { method: string; params?: unknown[] | object }): Promise<unknown>;
    }
  | {
      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<string>;
  getChainKey(): Promise<string>;
  sendSerializedTransaction(
    serializedTransactionBase64: string,
    chainId?: string
  ): Promise<string>;
  disconnect?(): Promise<void>;
};
```

***

## 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;
};
```

<Warning>
  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.
</Warning>

***

### `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;
  onSummary?: (summary: BalanceStreamSummary) => void;
};
```

| Field | Default | Description |
| - | - | - |
| `stream` | `false` | On `getBalancesByAddress`, request the streamed scan and merge the chunks before resolving. `getBalancesByAddressStream` streams without it. Both read `features.balanceStreaming` first: with the flag off, each falls back to one buffered request. |
| `signal` | none | `AbortSignal` for the streamed request. Aborting does not end the operation: the abort is caught as a stream failure, so the SDK emits `balance_stream_fallback` and re-runs the scan against the buffered endpoint, which does not read the signal. Do not rely on it to stop a scan outright. |
| `strict` | `false` | Throw on a malformed frame instead of skipping it. A throw here is caught by the fallback, so the call still resolves from the buffered endpoint. |
| `onSummary` | none | Called with the scan's terminal state once that state is available. Requires SDK 1.1.12 or later. |

***

### `BalanceStreamSummary`

The terminal state of an address scan, delivered to `onSummary`. Requires SDK 1.1.12 or later.

```ts theme={null}
type BalanceStreamSummary = {
  address: string;
  partial: boolean;
  completed: number;
  total: number;
  elapsedMs?: number;
};
```

| Field | Description |
| - | - |
| `address` | The address that was scanned. |
| `partial` | `true` if any chain failed or timed out, so the balances you received are incomplete. |
| `completed` | Chains that reported a result. A chain that failed still reports, so this equals `total` on an ordinary partial scan and is a progress figure, not a count of successes. |
| `total` | Chains in the scan. |
| `elapsedMs` | Server-side scan duration. Absent on the buffered path, which does not report it. |

`partial` is the cheapest way to tell an empty wallet from an unreachable chain, which produce the same empty rows. You can derive the same thing from the wrappers themselves, since each carries `error`, but `partial` also covers a scan that ended early.

The callback fires on the streamed and buffered paths alike, including when a stream falls back. It fires when a terminal summary is available, so treat it as the summary arriving rather than as a guarantee that it always will: a stream truncated before its `summary` frame completes without it.

```ts theme={null}
const balances = await Trustware.getBalancesByAddress(address, {
  stream: true,
  onSummary: ({ partial }) => {
    if (partial) {
      setNotice("Some chains did not report. Balances may be incomplete.");
    }
  },
});
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.