Swap Mode

Use <tokenflight-widget> with the default EXACT_INPUT behavior when users should choose the amount they pay and preview the routed output.

Widget demo without wallet connection

Should you read this?

Read this page if you are building a token swap, bridge-like flow, or power-user page where the user controls the payment amount.

If your app needs a fixed amount to arrive, read Receive Mode instead.

Imperative API

import { TokenFlightWidget } from '@tokenflight/swap';

const widget = new TokenFlightWidget({
  container: '#widget',
  config: {
    fromToken: 'eip155:1:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
    toToken: 'eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
    theme: 'dark',
    locale: 'en-US',
  },
  callbacks: {
    onSwapSuccess: (data) => console.log('Success:', data),
    onSwapError: (data) => console.log('Error:', data),
    onQuoteReceived: (data) => console.log('Quote:', data),
    onAmountChanged: (data) => console.log('Amount:', data),
  },
});

widget.initialize();

Declarative (HTML)

<tokenflight-widget
  theme="dark"
  locale="en-US"
  from-token="eip155:1:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
  to-token="eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
></tokenflight-widget>

<script type="module">
  import { registerWidgetElement } from '@tokenflight/swap/widget';

  registerWidgetElement();
</script>

Cross-Chain Swaps (EVM ↔ Solana)

Swap mode supports cross-chain swaps between EVM chains and Solana. When swapping to a different chain type than your connected wallet, you must provide a recipient address.

Scenario	Connected Wallet	Target Chain	Recipient Required
EVM → EVM	MetaMask	Base, Arbitrum, etc.	Optional
EVM → Solana	MetaMask	Solana	Required
Solana → EVM	Phantom	Ethereum, Base, etc.	Required
Solana → Solana	Phantom	Solana	Optional

import { TokenFlightWidget } from '@tokenflight/swap';

const widget = new TokenFlightWidget({
  container: '#widget',
  config: {
    theme: 'dark',
    fromToken: 'eip155:1:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
    toToken: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
    recipient: 'HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH',
  },
});

widget.initialize();

When a cross-chain recipient is required, the widget will:

1. Show a recipient input below the output panel.
2. Prevent execution until a valid address is entered.
3. Validate the address format against the target chain.

Runtime Methods

widget.setTheme('light');
widget.setCustomColors({ '--tf-primary': '#ff6600', '--tf-bg': '#1a1a2e' });
widget.destroy();

Next step

• Need wallet signing? Read AppKit, wagmi, or ethers.
• Need callbacks? Read Events & Callbacks.
• Need fixed checkout instead? Read Receive Mode.