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
`recipient`	`string`	—	Custom recipient address
`recipientEditable`	`boolean`	`false`	Allow the user to edit a preset recipient address
`refundTo`	`string`	—	Address the filler 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

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 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.

JavaScript API ​

TokenFlightWidget ​

Constructor ​

Config Properties ​

HTML Attributes ​

Instance Methods ​

Callbacks ​

Callback Payload Types ​

Custom Colors ​

Token Identifiers ​