---
title: SDK Widget
description: Accept deposits from any token on any chain with a single integration.
---

# SDK Widget

Accept deposits from any token on any chain. Users send what they have, you receive what you need.

Users can also use the widget to swap any asset they hold into any asset your application requires for use. The new asset/deposit can be routed to the users own EOA, or their embedded wallet within a protocol.

## Overview

The Trustware SDK provides everything you need to add universal deposit acceptance to your application:

- **TrustwareProvider** – React context provider for configuration and wallet management
- **TrustwareWidget** – Prebuilt UI component handling the complete deposit flow
- **Trustware Core** – Imperative API for custom integrations and headless usage

One integration gives your users access to 70+ chains and 6,000+ tokens, with automatic routing to your preferred settlement asset.

## Quick Start

Get deposits working in under 60 seconds.

### 1. Install the SDK

npm install @trustware/sdk

# or
pnpm add @trustware/sdk

# or
yarn add @trustware/sdk

### 2. Get Your API Key

Contact [[e-mail]](mailto:[e-mail]) to receive your API key.

### 3. Add the Widget

import { TrustwareProvider, TrustwareWidget } from "@trustware/sdk";

const config = {
  apiKey: "your-api-key",
  routes: {
    toChain: "8453",  // Base
    toToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
  },
};

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

That's it. Users can now deposit from any chain, and you receive USDC on Base.

---

## Installation

npm install @trustware/sdk

pnpm add @trustware/sdk

yarn add @trustware/sdk

### Requirements

| Requirement | Version |
|-------------|---------|
| React | 18.0+ |
| Node.js | 18.0+ |
| TypeScript | 5.0+ (optional) |

### What's Included

The package exports ESM modules with full TypeScript definitions:

import {
  TrustwareProvider,    // React context provider
  TrustwareWidget,      // Prebuilt deposit UI
  Trustware,            // Core imperative API
} from "@trustware/sdk";

import {
  useWagmi,             // Wagmi wallet adapter
  useEIP1193,           // Raw EIP-1193 adapter
} from "@trustware/sdk/wallet";

---

## Configuration Overview

The Trustware SDK Widget supports three integration patterns depending on where funds should be routed. Each mode uses the same core SDK, the difference is how you configure the destination address.

### How Routing Works

Every transaction has a **source** (where funds come from) and a **destination** (where funds are delivered). The SDK determines routing based on two settings:

| Setting | Purpose |
|---------|---------|
| `routes.toAddress` | Default destination address set in config |
| `Trustware.setDestinationAddress()` | Runtime override: takes precedence over config |

If `toAddress` is omitted and `setDestinationAddress()` is never called, funds route to the connected wallet by default.

### What is an EOA?

An **EOA (Externally Owned Account)** is a standard wallet controlled by a private key: MetaMask, Coinbase Wallet, Rainbow, or any browser extension / mobile wallet. This is distinct from **embedded wallets** (smart accounts created within your application via providers like Privy or Dynamic) and **smart contract wallets** (multisigs, account abstraction wallets).

---

## Available Configuration Modes

### Swap/Bridge Mode

Users convert assets for themselves. Funds are routed back to the user's own wallet.

**Use cases:**
- In-app token swaps
- Cross-chain bridging
- Portfolio rebalancing

**Destination:** User's connected EOA (default behavior)

→ [Swap/Bridge Mode Documentation](https://hackmd.io/@trustware/SkwdA1QB-e)

---

### Embedded Wallet Deposit Mode

Users fund an in-app smart account or embedded wallet. Funds are routed from the user's external wallet to their embedded wallet hosted by your application.

**Use cases:**
- Onboarding users with Privy, Dynamic, or other embedded wallet providers
- Funding in-app balances
- Smart account top-ups

**Destination:** User's embedded wallet (set at runtime via `setDestinationAddress()`)

→ [Embedded Wallet Deposit Mode Documentation](https://hackmd.io/@trustware/HyWWJe7r-e/edit)

---

### Crypto Payment Mode

Users pay your application directly. Funds are routed to your treasury, vault, or merchant wallet.

**Use cases:**
- Checkout flows
- Subscription payments
- NFT purchases
- Service fees

**Destination:** Partner wallet (hardcoded in config)

→ [Crypto Payment Mode Documentation](https://hackmd.io/@trustware/BySa4lmSbx/edit)

---

### Quick Comparison

| Mode | `toAddress` Config | Runtime Override | `autoDetectProvider` |
|------|-------------------|------------------|----------------------|
| Swap/Bridge | Omit (defaults to connected wallet) | Optional | `false` (optional) |
| Embedded Wallet Deposit | Omit | Required - call `setDestinationAddress()` | `true` |
| Crypto Payment | Set to partner wallet | Not needed | `true` |

### Understanding `autoDetectProvider`

The `autoDetectProvider` setting controls whether the widget automatically discovers the user's external wallet via EIP-6963/EIP-1193.

- **`false`** - The widget relies on a wallet you've already connected in your app (e.g., via Wagmi or RainbowKit). Use this for Swap/Bridge Mode where the user is already connected.
- **`true`** - The widget detects and prompts the user to connect their external wallet. Use this for Embedded Wallet Deposit and Crypto Payment modes, where the user pays from an external wallet but funds are routed elsewhere.

### Choosing the Right Mode

┌──────────────────────────────────────────────────┐
│             Where should funds go?               │
└──────────────────────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
    User's own       User's in-app     Your wallet
      wallet           wallet          (merchant)
          │               │               │
          ▼               ▼               ▼
    ┌─────────┐    ┌─────────────┐   ┌─────────┐
    │  Swap/  │    │  Embedded   │   │ Crypto  │
    │ Bridge  │    │   Wallet    │   │ Payment │
    │  Mode   │    │   Deposit   │   │  Mode   │
    └─────────┘    └─────────────┘   └─────────┘

:::info
All three modes support the same 70+ chains and 6,000+ tokens. The only difference is where the output is delivered.
:::

### Root Options

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `apiKey` | `string` | ✅ | — | Your Trustware API key |
| `routes` | `RouteConfig` | ✅ | — | Destination chain and token settings |
| `autoDetectProvider` | `boolean` | ❌ | `true` | Enable EIP-6963/EIP-1193 wallet discovery |
| `theme` | `ThemeConfig` | ❌ | Default theme | Widget styling options |
| `messages` | `MessagesConfig` | ❌ | Default messages | Widget text customization |

### Route Configuration

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `toChain` | `string` | ✅ | — | Destination chain ID (e.g., `"8453"` for Base) |
| `toToken` | `string` | ✅ | — | Destination token contract address |
| `defaultSlippage` | `number` | ❌ | `1` | Slippage tolerance as percentage (0-100) |
| `fromAddress` | `string` | ❌ | Connected wallet | Source wallet address |
| `toAddress` | `string` | ❌ | `fromAddress` | Destination wallet address |
| `options` | `RouteOptions` | ❌ | — | Advanced routing constraints |

### Route Options

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `fixedFromAmount` | `string` | ❌ | Lock deposit amount (disables user input) |
| `minAmountOut` | `string` | ❌ | Minimum acceptable output amount |
| `maxAmountOut` | `string` | ❌ | Maximum output amount cap |

---

## Theme Configuration

Customize the widget appearance to match your brand:

const config = {
  // ...other options
  theme: {
    primaryColor: "#FCB514",      // Buttons, accents
    secondaryColor: "#FFFFFF",    // Secondary elements
    backgroundColor: "#000000",   // Widget background
    borderColor: "#FCB514",       // Border color
    textColor: "#FFFFFF",         // Primary text
    radius: 16,                   // Border radius in pixels
  },
};

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `primaryColor` | `string` | `"#FCB514"` | Primary brand color (hex) |
| `secondaryColor` | `string` | `"#FFFFFF"` | Secondary color (hex) |
| `backgroundColor` | `string` | `"#000000"` | Widget background (hex) |
| `borderColor` | `string` | `"#FCB514"` | Border color (hex) |
| `textColor` | `string` | `"#FFFFFF"` | Text color (hex) |
| `radius` | `number` | `16` | Border radius in pixels |

---

## Messages Configuration

Customize widget copy:

const config = {
  // ...other options
  messages: {
    title: "Fund Your Account",
    description: "Deposit from any chain using any token.",
  },
};

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `title` | `string` | `"Top up"` | Widget header text |
| `description` | `string` | `""` | Subheader description |

---

## Supported Chains

The Trustware SDK supports 70+ chains through Axelar GMP and Squid Router infrastructure.

### EVM Chains

| Chain | Chain ID | Native Token |
|-------|----------|--------------|
| Ethereum | `1` | ETH |
| Arbitrum | `42161` | ETH |
| Optimism | `10` | ETH |
| Base | `8453` | ETH |
| Polygon | `137` | MATIC |
| Avalanche | `43114` | AVAX |
| BNB Chain | `56` | BNB |
| Fantom | `250` | FTM |
| Gnosis | `100` | xDAI |
| Celo | `42220` | CELO |
| Moonbeam | `1284` | GLMR |

### Non-EVM Chains

| Chain | Identifier | Native Token |
|-------|------------|--------------|
| Solana | `solana` | SOL |
| Cosmos Hub | `cosmoshub-4` | ATOM |
| Osmosis | `osmosis-1` | OSMO |
| Axelar | `axelar` | AXL |

---

## Common Token Addresses

### USDC

| Chain | Address |
|-------|---------|
| Ethereum | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` |
| Base | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
| Arbitrum | `0xaf88d065e77c8cC2239327C5EDb3A432268e5831` |
| Polygon | `0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359` |

:::info
For native tokens (ETH, MATIC, etc.), use the placeholder address: `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`
:::