API Reference

<tokenflight-widget> HTML Attributes

The only supported public custom element. It routes into swap and receive flows based on configuration.

Attribute	Type	Default	Required	Description
to-token	string	--	No	Destination token (CAIP-10 or JSON). Pass a JSON array for multi-token selection.
from-token	string	--	No	Source token (CAIP-10 or JSON). In receive mode (trade-type="EXACT_OUTPUT"), used as the default payment token — see Receive-mode behavior.
trade-type	string	"EXACT_INPUT"	No	"EXACT_INPUT" (swap) or "EXACT_OUTPUT" (receive)
amount	string	--	No	Amount value, interpreted as input or output based on trade-type
recipient	string	--	No	Custom recipient address
icon	string	--	No	Custom icon URL for the target token
lock-from-token	boolean	false	No	Lock the source token selector
lock-to-token	boolean	false	No	Lock the destination token selector
from-tokens	string	--	No	JSON array of allowed source tokens
to-tokens	string	--	No	JSON array of allowed destination tokens
api-endpoint	string	https://api.hyperstream.dev	No	Hyperstream API base URL
theme	string	"light"	No	"light", "dark", or "auto"
locale	string	"en-US"	No	Display language
title-text	string	--	No	Custom title text
title-image	string	--	No	Custom title image URL
hide-title	boolean	false	No	Hide the top title bar
hide-powered-by	boolean	false	No	Hide the footer branding
no-background	boolean	false	No	Remove background color
no-border	boolean	false	No	Remove border and shadow
csp-nonce	string	--	No	CSP nonce for injected styles

Boolean Attribute Parsing

Boolean HTML attributes accept these string values:

• Truthy: "" (present), "true", "1", "yes"
• Falsy: "false", "0", "no"

<tokenflight-widget hide-title></tokenflight-widget>
<tokenflight-widget hide-title="true"></tokenflight-widget>
<tokenflight-widget hide-title="1"></tokenflight-widget>
<tokenflight-widget hide-title="yes"></tokenflight-widget>

Imperative API

TokenFlightWidget

Use the imperative class when you need lifecycle control, callbacks, and runtime theme updates.

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

Instance Methods

Method	Description
initialize()	Mount the widget to the container. Creates a Shadow DOM root.
destroy()	Unmount the widget and clean up the DOM.
setTheme(theme)	Change theme at runtime. Accepts "light", "dark", or "auto".
setCustomColors(colors)	Apply CSS variable overrides at runtime.

widget.initialize();
widget.setTheme('dark');
widget.setCustomColors({ '--tf-primary': '#FF6B00' });
widget.destroy();

WARNING

After initialize(), the widget does not respond to config changes. Destroy and recreate it when configuration changes.

Registration Helpers

registerWidgetElement(options?)

Registers <tokenflight-widget> only.

registerWidgetElement();

registerElements(options?)

Legacy convenience facade. New integrations should prefer registerWidgetElement() to avoid pulling in compatibility registrations.

interface RegisterElementsOptions {
  walletAdapter?: IWalletAdapter;
  callbacks?: Callbacks;
  customColors?: CustomColors;
  apiEndpoint?: string;
  theme?: Theme;
  locale?: SupportedLocale;
}

Programmatic Callbacks on Web Component Elements

const widgetEl = document.querySelector('tokenflight-widget');

widgetEl.__walletAdapter = myAdapter;
widgetEl.__callbacks = {
  onSwapSuccess: (data) => console.log('This element completed:', data),
};

Exported Utilities

Amount Conversion

toDisplayAmount('1000000', 6);
toBaseUnits('1', 6);
formatDisplayAmount('1.234567890');

Chain Utilities

isSolanaChain(SOLANA_CHAIN_ID);
isEvmChain(1);
getChainType(1);
isCrossChainSwap(1, SOLANA_CHAIN_ID);

Constants

Export	Value	Description
DEFAULT_API_ENDPOINT	"https://api.hyperstream.dev"	Default API URL
SOLANA_CHAIN_ID	20011000000	Internal chain ID for Solana mainnet

Testing

const mock = new MockWalletAdapter();

Cache Management

clearTokenCache();