API Reference

TokenFlightWidget

The only supported public component. One class and one HTML tag cover swap and receive.

Constructor

app.js

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

const widget = new TokenFlightWidget({
  container: '#widget',
  config: {
    toToken: { chainId: 8453, address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' },
    tradeType: 'EXACT_OUTPUT',
    amount: '100',
    theme: 'dark',
  },
  walletAdapter: myAdapter,
  callbacks: {},
});

Config Properties

Property	Type	Default	Description
toToken	TokenIdentifier | TokenIdentifier[]	—	Destination token or token list
fromToken	TokenIdentifier	—	Optional source token
tradeType	'EXACT_INPUT' | 'EXACT_OUTPUT'	'EXACT_INPUT'	Swap vs fixed-output receive
amount	string	—	Amount value in human-readable units
theme	'dark' | 'light' | 'auto'	'light'	Widget color theme
locale	string	'en-US'	Display locale
apiEndpoint	string	'https://api.hyperstream.dev'	API endpoint
fiatApiEndpoint	string	—	Fiat API endpoint
recipient	string	—	Custom recipient address
icon	string	—	Custom icon URL for the target token
fromTokens	TokenIdentifier[]	—	Source token allowlist
toTokens	TokenIdentifier[]	—	Destination token allowlist
lockFromToken	boolean	false	Lock the source token selector
lockToToken	boolean	false	Lock the destination token selector
customColors	Record<string, string>	—	CSS color variable overrides
titleText	string	—	Custom widget title text
titleImageUrl	string	—	Custom widget title image URL
hideTitle	boolean	false	Hide the top title/header area
hidePoweredBy	boolean	false	Hide the footer
noBackground	boolean	false	Remove container background
noBorder	boolean	false	Remove container border and shadow

HTML Attributes

index.html

<tokenflight-widget
  theme="dark"
  locale="en-US"
  to-token="eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  trade-type="EXACT_OUTPUT"
  amount="100"
  from-token="eip155:1:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
  csp-nonce="abc123"
></tokenflight-widget>

Attribute	Description
to-token	Destination token in CAIP-10 or JSON format
trade-type	EXACT_INPUT or EXACT_OUTPUT
amount	Amount value in human-readable units
theme	'light', 'dark', or 'auto'
locale	Display locale
from-token	Source token in CAIP-10 or JSON format
api-endpoint	Custom Hyperstream API endpoint URL
fiat-api-endpoint	Custom fiat API endpoint URL
csp-nonce	Nonce for CSP-restricted environments

---

Instance Methods

Method	Description
initialize()	Mount and render the widget into the container
destroy()	Unmount the widget and clean up resources
setTheme(theme)	Switch theme at runtime ('light', 'dark', 'auto')
setCustomColors(colors)	Apply custom CSS color overrides at runtime

app.js

widget.initialize();
widget.setTheme('light');
widget.setCustomColors({ primary: '#FF6B00', background: '#1A1A2E' });
widget.destroy();

---

Callbacks

Pass callbacks to widget lifecycle events:

app.js

const widget = new TokenFlightWidget({
  container: '#widget',
  config: {
    toToken: { chainId: 8453, address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' },
    tradeType: 'EXACT_OUTPUT',
    amount: '100',
    theme: 'dark',
  },
  callbacks: {
    onSwapSuccess: (data) => console.log('Success:', data),
    onSwapError: (data) => console.log('Error:', data),
    onQuoteReceived: (quote) => console.log('Quote:', quote),
    onAmountChanged: (data) => console.log('Amount:', data),
    onWalletConnected: (data) => console.log('Wallet:', data),
    onConnectWallet: () => openMyWalletModal(),
    onAccountModal: () => openMyAccountModal(),
  },
});

Callback	Payload	Description
onSwapSuccess	SwapSuccessData	Fired after a successful swap or purchase
onSwapError	SwapErrorData	Fired when execution fails
onQuoteReceived	QuoteResponse	Fired when a new price quote is fetched
onAmountChanged	AmountChangedData	Fired when the user changes an editable amount
onWalletConnected	WalletConnectedData	Fired when a wallet connects
onConnectWallet	—	Called when the user clicks “Connect Wallet” and no walletAdapter is provided
onAccountModal	—	Called when the user clicks the connected wallet address

Callback Payload Types

types.ts

interface SwapSuccessData {
  orderId: string;
  fromToken: string;
  toToken: string;
  fromAmount: string;
  toAmount: string;
  txHash: string;
}

interface SwapErrorData {
  code: string;
  message: string;
  details?: unknown;
}

interface WalletConnectedData {
  address: string;
  chainType: string;
}

interface AmountChangedData {
  amount: string;
  direction: 'from' | 'to';
}

---

Custom Colors

Override any theme color via config or at runtime. Named keys map to internal CSS variables:

Key	CSS Variable	Description
primary	--tf-accent	Buttons, links, active states
background	--tf-bg	Main background
textPrimary	--tf-text	Primary text color
textSecondary	--tf-text-secondary	Labels, hints
border	--tf-border	Borders, dividers
success	--tf-success	Success states
error	--tf-error	Error states
warning	--tf-warning	Warning states

See Theming & Custom Colors for the full CSS variable list and examples.

---

Token Identifiers

Three formats are accepted anywhere a TokenIdentifier is expected:

Format	Example
Object literal	{ chainId: 1, address: '0xA0b8...' }
CAIP-10 string	'eip155:1:0xA0b8...'
JSON string	'{"chainId":1,"address":"0xA0b8..."}'

Use the zero address for native tokens:

• EVM: 0x0000000000000000000000000000000000000000
• Solana: 11111111111111111111111111111111

See Token Preselection for full details on supported chains and examples.