Upgrade from 0.2 to 0.3

This guide is for apps upgrading from 0.2.x to 0.3.x.

For most integrations already using <tokenflight-widget>, the upgrade is a package bump plus UI regression testing. The main visible default change is the quote card in EXACT_INPUT swap mode: it is now hidden unless you opt back in with quote-card="visible".

0.3.x is not only a quote-card/style release, though. It also cleans up legacy component exports, adds iframe embedding, expands the API client, improves wallet chain switching, and changes a few edge-case runtime behaviors.

Upgrade packages

Keep the widget and adapter packages on the same minor version.

pnpm

pnpm add @tokenflight/[email protected] @tokenflight/[email protected]

npm

npm install @tokenflight/[email protected] @tokenflight/[email protected]

yarn

yarn add @tokenflight/[email protected] @tokenflight/[email protected]

bun

bun add @tokenflight/[email protected] @tokenflight/[email protected]

Install the adapter package you actually use. For example, replace @tokenflight/adapter-appkit with @tokenflight/adapter-wagmi or @tokenflight/adapter-ethers if that is your wallet stack.

Quick checklist

1. Bump @tokenflight/swap and any @tokenflight/adapter-* packages together.
2. If you use <tokenflight-widget>, keep the tag. No rename is required.
3. If you used legacy <tokenflight-swap> or <tokenflight-deposit>, migrate to <tokenflight-widget>.
4. If you want the old inline swap quote details, add quote-card="visible".
5. If you import direct API types from @tokenflight/api, update type imports to the HyperstreamApi namespace.
6. Retest custom wallet adapters, especially chain switching on Coinbase Wallet or custom EVM chains.
7. Retest card checkout if you use recipient, refund-to, referrer, or referrer-fee-bps.

Quote card default

In 0.2.x, swap quotes were shown inline as a larger card. In 0.3.x, EXACT_INPUT swap mode defaults to a more compact surface and hides the quote card. The details remain available in the UI.

To preserve the old visible card behavior, set quote-card="visible".

<tokenflight-widget
  quote-card="visible"
  trade-type="EXACT_INPUT"
  amount="100"
  from-token="eip155:1:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
  to-token="eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
></tokenflight-widget>

For the imperative API, use the matching quoteCard config field.

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

const widget = new TokenFlightWidget({
  container: "#tokenflight",
  config: {
    quoteCard: "visible",
    tradeType: "EXACT_INPUT",
    amount: "100",
    fromToken: "eip155:1:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    toToken: "eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  },
});

widget.initialize();

EXACT_OUTPUT receive mode keeps its quote card visible because the fixed-output payment-token comparison flow depends on it.

Legacy component cleanup

0.3.x standardizes the public widget surface around <tokenflight-widget> and TokenFlightWidget.

Use this for all swap, receive, and card flows:

<tokenflight-widget
  trade-type="EXACT_OUTPUT"
  amount="100"
  methods='["crypto","card"]'
  to-token="eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
></tokenflight-widget>

If you still have legacy deposit markup, migrate attribute names and method values:

0.2 legacy deposit	0.3 widget
<tokenflight-deposit>	<tokenflight-widget>
target	to-token
target-icon	icon
methods='["wallet","card"]'	methods='["crypto","card"]'
fixed deposit amount	trade-type="EXACT_OUTPUT" plus amount

Before:

<tokenflight-deposit
  target="eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  amount="100"
  methods='["wallet","card"]'
></tokenflight-deposit>

After:

<tokenflight-widget
  to-token="eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  trade-type="EXACT_OUTPUT"
  amount="100"
  methods='["crypto","card"]'
></tokenflight-widget>

If you imported legacy helpers or classes, switch to the widget equivalents.

Removed or legacy import	Use instead
TokenFlightSwap	TokenFlightWidget
registerSwapElement()	registerWidgetElement()
registerDepositElement()	registerWidgetElement()
TokenFlightSwapOptions	TokenFlightWidgetOptions
TokenFlightDepositConfig	TokenFlightWidgetConfig

import { registerWidgetElement } from "@tokenflight/swap/widget";

registerWidgetElement();

Iframe embedding

0.3.x adds an iframe integration path for teams that need stronger isolation or a stricter CSP.

• @tokenflight/swap/iframe registers <tokenflight-iframe-widget>.
• @tokenflight/swap/bridge exposes the imperative bridge API.
• The hosted receiver is https://embed.tokenflight.ai/widget.

Normal integrations can stay on <tokenflight-widget>. Move to iframe mode only when you need frame isolation, self-hosted receiver pages, or host-owned card popups. See Iframe Embedding.

API client changes

If you use only the widget, you can skip this section.

The standalone @tokenflight/api package now keeps Hyperstream response types on the HyperstreamApi namespace. Root-level aliases such as QuoteRequest and QuoteRoute were removed from @tokenflight/api.

Before:

import type { QuoteRequest } from "@tokenflight/api";

After:

import type { HyperstreamApi } from "@tokenflight/api";

type QuoteRequest = HyperstreamApi.QuoteRequest;

Request methods now use an options object for cancellation.

import { DEFAULT_API_ENDPOINT, HyperstreamApi } from "@tokenflight/api";

const api = new HyperstreamApi({ baseUrl: DEFAULT_API_ENDPOINT });
const controller = new AbortController();

const quote = await api.getQuotes(
  {
    tradeType: "EXACT_INPUT",
    fromChainId: 1,
    fromToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    toChainId: 8453,
    toToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    amount: "1000000",
    fromAddress: "0x1111111111111111111111111111111111111111",
  },
  { signal: controller.signal },
);

console.log(quote.quoteId);

New API client capabilities include streaming quotes, direct order lookup, order tracking, token autocomplete, Arcadia config, vault/mToken reads, intent lookup, typed backend errors, and fiat checkout helpers. See API Client.

Wallet adapter changes

Official AppKit, wagmi, and ethers adapters gained safer chain-switch behavior:

• no-op wallet_switchEthereumChain calls are skipped when the wallet is already on the target chain;
• Coinbase Wallet's unrecognized-chain response can fall back to wallet_addEthereumChain;
• structured provider error fields are preserved as errorCode and errorData.

Custom adapters still work without changes because the new adapter members are optional. To get the better chain-switch behavior, add these optional methods when your adapter can implement them safely:

Optional member	Purpose
getCurrentChainId()	Read the current EVM chain without switching or prompting
getAddEthereumChainParams(chainId)	Provide EIP-3085 chain metadata for add-chain fallback

If your custom adapter returns failed wallet actions, preserve provider code as errorCode when possible. This lets the widget distinguish user rejection from chain metadata errors.

Runtime behavior changes

Several smaller changes can affect integration tests or edge cases:

• Attribute updates on <tokenflight-widget> are more reactive. If you change attributes such as amount, theme, or methods after mount, the custom element path now re-reads them instead of snapshotting the initial values.
• Imperative TokenFlightWidget config is still constructor-time config. Destroy and recreate the widget when changing flow configuration after initialize().
• referrer and referrer-fee-bps are validated as a pair. If one is set without the other, both are ignored and a developer-facing error is logged.
• refund-to is now forwarded through card settlement as well as crypto quotes. Use it when recipient is a contract, hook, or merchant settlement address and failed settlements should return funds to the user wallet.
• Fiat provider failure details are surfaced in the widget instead of collapsing into a generic error.
• Card checkout popup handoff and Safari drawer behavior were tightened, so popup and drawer tests may need updated expectations.

Styling and DOM expectations

The widget surface, quote details, method pages, token selector, provider selector, drawers, order progress, and success views were restyled in 0.3.x. Motion and height transitions were also rebuilt.

If your app only themes through documented CSS variables, no migration should be needed. If your tests or styles depend on internal DOM shape, internal class names, or exact screenshot layout, expect updates.

New font-size CSS variables are available for custom colors/style systems:

CSS variable
--tf-font-sm
--tf-font-base
--tf-font-md
--tf-font-lg
--tf-font-xl
--tf-font-heading
--tf-font-amount
--tf-font-amount-lg
--tf-font-amount-sm

What changed besides quote card and styles

Here is the short version of the confirmed non-style work between 0.2.3 and 0.3.x:

Area	Change
Public widget surface	Standardized on <tokenflight-widget> and TokenFlightWidget
Iframe	Added hosted receiver, iframe custom element, and bridge API
API package	Reorganized exports, typed errors, options-object cancellation, streaming quotes, order tracking, and more endpoints
Wallets	Safer chain switching, add-chain fallback, account-change handling
Fiat/card	Improved popup handoff, failure messages, order status data, and refund-to forwarding
Referrer fees	referrer and referrerFeeBps must be provided together
Runtime config	Custom-element attributes are read reactively after mount
Docs	Site structure moved from broad guides into Start, Wallet Setup, Build Flows, Integrate, Concepts, Reference, and Release pages
Tests	Expanded unit and E2E coverage for iframe, drawers, motion, amount inputs, fiat checkout, and widget card states

Verification

After upgrading, test the flows you expose:

• EXACT_INPUT swap with quote-card hidden and, if you opt in, visible.
• EXACT_OUTPUT receive with crypto payment.
• Mixed methods='["crypto","card"]' checkout.
• Card-only checkout when no wallet adapter is configured.
• Wallet chain switching on every chain your app supports.
• Custom recipient plus refund-to behavior.
• Success and error callbacks: onSwapSuccess, onSwapError, onDepositSuccess, onDepositError, onFiatOrderCreated, and onFiatOrderCompleted.

For production checks, continue with Backend Verification and Testing.