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.

This quickstart covers the React SDK integration path. For server-side or backend integrations, start with the API Overview.
This guide walks you through installing the SDK, obtaining an API key, configuring your route, and rendering the deposit widget. By the end you’ll have a working deposit flow embedded in your React app.
1

Install the package

Add @trustware/sdk to your project using your preferred package manager:
npm install @trustware/sdk
The SDK requires React 18.2+ or React 19. Install the peer dependencies if you haven’t already:
npm install react react-dom viem
react and react-dom are marked as optional peer dependencies — if your app already has them installed, no extra step is needed. viem is required.
2

Get an API key

apiKey is a required field in TrustwareConfigOptions. Contact Trustware to obtain your API key, then store it as an environment variable:
NEXT_PUBLIC_TRUSTWARE_API_KEY=your-api-key-here
Never commit your API key to source control. Use your framework’s environment variable support — NEXT_PUBLIC_ prefix for Next.js, VITE_ for Vite.
3

Configure TrustwareConfigOptions

Create a config object that satisfies TrustwareConfigOptions. The routes.toChain and routes.toToken fields are required — everything else is optional:
import { type TrustwareConfigOptions } from "@trustware/sdk";

const trustwareConfig = {
  apiKey: process.env.NEXT_PUBLIC_TRUSTWARE_API_KEY!,
  routes: {
    toChain: "8453",       // destination chain ID (Base)
    toToken: "0xEeee...",  // destination token address
    defaultSlippage: 1,    // slippage percentage, defaults to 1
    options: {
      routeRefreshMs: 15000, // route preview refresh interval
    },
  },
  autoDetectProvider: true, // let the SDK discover injected wallets
  messages: {
    title: "Deposit",
    description: "Move funds into the destination asset and chain.",
  },
} satisfies TrustwareConfigOptions;
FieldRequiredDescription
apiKeyYesYour Trustware API key
routes.toChainYesDestination chain ID as a string
routes.toTokenYesDestination token address
routes.toAddressNoRecipient address. Can be updated at runtime via Trustware.setDestinationAddress
routes.defaultSlippageNoSlippage percentage. Defaults to 1
routes.routeTypeNo"swap", "deposit", "withdraw", or "cross". Defaults to "swap"
routes.optionsNoRefresh and amount-constraint settings — routeRefreshMs, fixedFromAmount, minAmountOut, maxAmountOut
autoDetectProviderNoEnable SDK-managed wallet discovery. Defaults to false
messagesNoOverride widget title and description copy
themeNoWidget color and radius overrides
walletConnectNoWalletConnect connector overrides
retryNoRate-limit retry behavior
featuresNoFeature flags — tokensPagination, balanceStreaming, shouldAllowGA4
onError, onSuccess, onEventNoLifecycle callbacks
See configuration overview for the full reference of every field.
4

Wrap your app with TrustwareProvider

Mount TrustwareProvider once near the root of your component tree and pass in your config:
import { TrustwareProvider } from "@trustware/sdk";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <TrustwareProvider config={trustwareConfig}>
      {children}
    </TrustwareProvider>
  );
}
All TrustwareWidget instances and useTrustware calls within the tree share this config and wallet state.
5

Render TrustwareWidget

Drop <TrustwareWidget /> anywhere inside the provider tree:
import { TrustwareWidget } from "@trustware/sdk";

export function DepositPage() {
  return (
    <div>
      <h1>Top up your balance</h1>
      <TrustwareWidget />
    </div>
  );
}
The widget handles the full deposit flow: wallet connection, token selection, amount entry, and transaction confirmation.

​
Full working example

Here’s the complete setup in a single file, copied directly from the SDK README: 
import {
  TrustwareProvider,
  TrustwareWidget,
  type TrustwareConfigOptions,
} from "@trustware/sdk";

const trustwareConfig = {
  apiKey: process.env.NEXT_PUBLIC_TRUSTWARE_API_KEY!,
  routes: {
    toChain: "8453",
    toToken: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
    defaultSlippage: 1,
    options: {
      routeRefreshMs: 15000,
    },
  },
  autoDetectProvider: true,
  messages: {
    title: "Deposit",
    description: "Move funds into the destination asset and chain.",
  },
} satisfies TrustwareConfigOptions;

export function App() {
  return (
    <TrustwareProvider config={trustwareConfig}>
      <TrustwareWidget />
    </TrustwareProvider>
  );
}

​
Next steps

  • Bring your own wallet — if your app already manages wallet connection through Wagmi or viem, see Host wallet bridge.
  • Control the widget programmatically — open and close the widget from your own UI with Controlled widget.
  • Build a custom UI — skip the widget entirely and use the Headless core API.
  • Customize appearance — adjust colors, radius, and copy in Configuration.