JavaScript API

Reference for the TokenFlightWidget class. For the declarative (custom-element) API, see HTML Attributes.

TokenFlightWidget

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

Constructor

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	'https://fiat.hyperstream.dev' when omitted	Fiat API endpoint
integratorId	string	—	Integrator id for fee attribution, sent as the X-Integrator-Id header. Canonical format <slug>-<8 hex>; malformed values are ignored
qrCodeApiUrl	string	'/api/qrcode' from the embed config origin	QR image API base URL. See QRCode API
recipient	string	—	Custom recipient address
recipientEditable	boolean	false	Allow the user to edit a preset recipient address
refundTo	string	—	Address the filler or card settlement should refund to if the fill fails
icon	string	—	Custom icon URL for the target token
fromTokens	TokenIdentifier[]	—	Source token allowlist
toTokens	TokenIdentifier[]	—	Destination token allowlist
methods	Array<'crypto' | 'card'>	['crypto']	Payment methods to offer
defaultPayMethod	'crypto' | 'card'	—	In EXACT_INPUT swap mode, skip the method picker and open this tab first
lockFromToken	boolean	false	Lock the source token selector
lockToToken	boolean	false	Lock the destination token selector
quoteCard	'hidden' | 'visible'	'hidden' in EXACT_INPUT, otherwise visible	Controls the inline quote card in swap mode
rpcOverrides	Record<string, string>	—	Decimal chain ID to RPC URL overrides
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
hideProvider	boolean	false	Hide the provider name in order tracking
noBackground	boolean	false	Remove container background
noBorder	boolean	false	Remove container border and shadow
referrer	string	—	Referrer address for fee attribution
referrerFeeBps	number	—	Referrer fee in basis points

HTML Attributes

<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 widget DOM/resources. Destroy your wallet adapter separately if it exposes destroy()
setTheme(theme)	Switch theme at runtime ('light', 'dark', 'auto')
setCustomColors(colors)	Apply custom CSS color overrides at runtime

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

---

Callbacks

Pass callbacks to widget lifecycle events:

const widget = new TokenFlightWidget({
  container: '#widget',
  config: {
    toToken: { chainId: 8453, address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' },
    tradeType: 'EXACT_OUTPUT',
    amount: '100',
    theme: 'dark',
  },
  callbacks: {
    onDepositSuccess: (data) => console.log('Success:', data),
    onDepositError: (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(),
    onFiatOrderCreated: (data) => console.log('Card order:', data.orderId),
    onFiatOrderCompleted: (data) => console.log('Card status:', data.status),
  },
});

Callback	Payload	Description
onSwapSuccess	SwapSuccessData	Fired after a successful EXACT_INPUT swap
onSwapError	SwapErrorData	Fired when an EXACT_INPUT swap fails
onDepositSuccess	SwapSuccessData	Fired after a successful EXACT_OUTPUT receive or deposit
onDepositError	SwapErrorData	Fired when an EXACT_OUTPUT receive or deposit 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	—	Fallback when the user clicks the connected wallet address and the adapter has no openAccountModal()
onFiatOrderCreated	{ orderId, widgetUrl }	Fired when the fiat provider widget URL is ready
onFiatOrderCompleted	{ orderId, status, txHash? }	Fired when a fiat order reaches a terminal status

Callback Payload Types

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';
}

interface FiatOrderCreatedData {
  orderId: string;
  widgetUrl?: string;
}

interface FiatOrderCompletedData {
  orderId: string;
  status: string;
  txHash?: string;
}

---

Custom Colors

Override any theme color via config or at runtime. Keys must be CSS variable names (--tf-*):

widget.setCustomColors({
  '--tf-primary': '#FF6B00',
  '--tf-bg': '#1A1A2E',
  '--tf-text': '#FFFFFF',
});

The exported CustomColors type from @tokenflight/swap provides autocomplete for supported variables while still allowing custom --tf-* overrides. See Theming & Custom Colors for the common variables and full 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.