HTML Attributes

Reference for the <tokenflight-widget> custom element. For the programmatic (class-based) API, see JavaScript API.

<tokenflight-widget> 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
recipient-editable	boolean	false	No	Allow the user to edit the recipient address in the UI
refund-to	string	--	No	Address to refund failed swaps to (defaults to sender)
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
methods	string	'["crypto"]'	No	JSON array of payment methods to enable, e.g. '["crypto","card"]'
default-pay-method	string	--	No	"crypto" or "card" — in EXACT_INPUT swap mode, skip the method picker and open this tab first
fiat-currency	string	--	No	Default fiat currency for card payments (e.g. "USD")
api-endpoint	string	https://api.hyperstream.dev	No	Hyperstream API base URL
fiat-api-endpoint	string	https://fiat.hyperstream.dev when omitted	No	Override URL for the fiat on-ramp API
rpc-overrides	string	--	No	JSON object mapping decimal chain IDs to custom RPC URLs
referrer	string	--	No	Referrer address for fee attribution; use with referrer-fee-bps
referrer-fee-bps	string / number	--	No	Referrer fee in basis points; use with referrer
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
hide-provider	boolean	false	No	Hide the provider name in order tracking
quote-card	string	"hidden" in EXACT_INPUT, otherwise visible	No	"hidden" or "visible" — controls the inline quote card in swap mode
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

methods vs default-pay-method

These two attributes do different things — you usually need both:

• methods decides which payment tabs are offered at all.
• In EXACT_INPUT swap mode, default-pay-method decides which tab is open first when you want to skip the picker.
• In mixed EXACT_OUTPUT receive/card checkout, the widget opens with the method picker.

Want crypto and card with the card tab active by default?

<tokenflight-widget
  methods='["crypto","card"]'
  default-pay-method="card"
/>

The order of items in methods does not decide the default — you must set default-pay-method explicitly.

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: { ... },
});

The effective fiat API default is https://fiat.hyperstream.dev when fiat-api-endpoint and registerWidgetElement({ fiatApiEndpoint }) are both omitted.

Instance Methods

Method	Description
initialize()	Mount the widget to the container. Creates a Shadow DOM root.
destroy()	Unmount the widget and clean up widget DOM/resources. Destroy your wallet adapter separately if it exposes destroy().
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() when they want explicit registration without the main package's auto-registration side effect.

interface RegisterElementsOptions {
  walletAdapter?: IWalletAdapter;
  callbacks?: Callbacks;
  customColors?: CustomColors;
  apiEndpoint?: string;
  fiatApiEndpoint?: string;
  theme?: Theme;
  locale?: SupportedLocale;
  textOverrides?: TextOverrides;
  hideTitle?: boolean;
  hidePoweredBy?: boolean;
  hideProvider?: boolean;
  noBackground?: boolean;
  noBorder?: boolean;
  methods?: SwapPayMethod[];
  rpcOverrides?: Record<string, string>;
  supportedChainIds?: number[];
  referrer?: string;
  referrerFeeBps?: number;
}

Set chain filtering on the wallet adapter itself, for example new EthersWalletAdapter(provider, { supportedChainIds: [1, 8453] }). Do not rely on a global supportedChainIds registration default for current widgets.

Programmatic Callbacks on Web Component Elements

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

widgetEl.__walletAdapter = myAdapter;
widgetEl.__callbacks = {
  onDepositSuccess: (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();