Token Pre-selection

You can pre-select the source token (fromToken), destination token (toToken), or both, so users land on a ready-to-go screen.

Identifier Formats

Three formats are accepted anywhere a TokenIdentifier is expected:

Object Literal (Imperative API)

config: {
  fromToken: { chainId: 1, address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' },
  toToken: { chainId: 8453, address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' },
}

CAIP-10 String (HTML attributes & imperative)

eip155:<chainId>:<contractAddress>
solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:<mintAddress>

<!-- EVM tokens -->
<tokenflight-widget
  to-token="eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  trade-type="EXACT_OUTPUT"
  amount="100"
  from-token="eip155:1:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
></tokenflight-widget>

<!-- Solana token (USDC on Solana) -->
<tokenflight-widget
  to-token="solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
  trade-type="EXACT_OUTPUT"
  amount="100"
></tokenflight-widget>

JSON String

<tokenflight-widget
  to-token="eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  trade-type="EXACT_OUTPUT"
  amount="100"
  from-token='{"chainId":1,"address":"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"}'
></tokenflight-widget>

Supported Chains

CAIP-10 Prefix	Chain
eip155:1	Ethereum
eip155:137	Polygon
eip155:42161	Arbitrum One
eip155:8453	Base
eip155:10	Optimism
eip155:56	BNB Chain
eip155:43114	Avalanche C-Chain
solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp	Solana

Any EVM eip155:<chainId> reference is accepted — the table above lists chains with built-in shortcuts.

Examples

Receive: USDC on Base from ETH

const widget = new TokenFlightWidget({
  container: '#widget',
  config: {
    toToken: { chainId: 8453, address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' },
    tradeType: 'EXACT_OUTPUT',
    amount: '100',
    theme: 'dark',
    fromToken: { chainId: 1, address: '0x0000000000000000000000000000000000000000' },
  },
});
widget.initialize();

Receive: Pre-fill source token

const widget = new TokenFlightWidget({
  container: '#widget',
  config: {
    toToken: { chainId: 8453, address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' },
    tradeType: 'EXACT_OUTPUT',
    amount: '50',
    fromToken: 'eip155:1:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
    theme: 'dark',
  },
});
widget.initialize();

Declarative: Full Pre-selection

<tokenflight-widget
  to-token="eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  trade-type="EXACT_OUTPUT"
  amount="100"
  theme="dark"
  from-token="eip155:1:0x0000000000000000000000000000000000000000"
></tokenflight-widget>

Receive mode: from-token behavior

In receive mode (trade-type="EXACT_OUTPUT"), the widget picks a payment token from the connected wallet's balances. Setting from-token lets you nominate a preferred default:

• Wallet holds the configured token → it's auto-selected as the payment token. The user can deposit without any token-picker interaction.
• Wallet does not hold it → the widget falls back to its normal balance ranking and picks the best available token automatically. The user can still manually switch from the pay-token selector.
• from-token not set → normal balance ranking applies (unchanged default behavior).

Strict matching, no cross-chain fallback

Matching is strict: the from-token must match both the chain ID and contract address of a token in the user's wallet. For example:

<tokenflight-widget
  to-token="eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  trade-type="EXACT_OUTPUT"
  amount="100"
  from-token="eip155:1:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
></tokenflight-widget>

This configures Ethereum USDC as the default. A user holding only Polygon USDC or Base USDC will not match — even though the symbol is the same — and will fall back to the normal balance list. If you want cross-chain behavior, omit from-token and let the ranking pick.

User choice is sticky

Once a user manually picks a different payment token via the selector, the widget will not override that choice on subsequent balance or amount refreshes. The auto-select only fires during initial selection or after an explicit reset.

Native Token Addresses

Use the zero address to refer to a chain's native token:

Chain	Native Address
EVM	0x0000000000000000000000000000000000000000
Solana	11111111111111111111111111111111