TokenFlightSDK

Appearance

Architecture ​

This page shows how the widget, API, wallet adapter, and settlement layers fit together.

System Overview ​

Data Flow ​

1. User Interaction → Quote ​

  1. User selects tokens and amount
  2. SDK sends POST /v1/quotes to the API
  3. API returns route options from available providers
  4. SDK displays routes in the UI
  5. onQuoteReceived callback fires

2. Route Selection → Build ​

  1. User selects a route
  2. SDK sends POST /v1/deposit/build
  3. API returns wallet actions (approve + transfer)
  4. SDK prepares transaction for wallet signing

3. Wallet Signing → Submit ​

  1. SDK passes transaction to the Wallet Adapter
  2. Adapter calls the wallet (MetaMask, Phantom, etc.)
  3. User signs in the wallet popup
  4. SDK receives txHash
  5. SDK sends PUT /v1/deposit/submit with txHash
  6. API creates the order and begins tracking

4. Order Tracking → Completion ​

  1. SDK polls GET /v1/orders/:address
  2. Progressive polling — 1s → 2s → 3s → 5s → 10s intervals
  3. API returns order status updates
  4. SDK updates the UI (tracking progress bar)
  5. Order reaches filled status
  6. The matching success callback fires (onSwapSuccess for EXACT_INPUT, onDepositSuccess for EXACT_OUTPUT)

Wallet Adapter Layer ​

Shadow DOM Isolation ​

Each widget instance creates its own Shadow DOM:

Styles inside the Shadow DOM don't leak out, and page styles don't leak in. The supported customization paths are CSS custom properties (--tf-*) and the setCustomColors() runtime method.

Caching Architecture ​

A single TanStack Solid Query QueryClient backs the SDK. It caches:

  • Chain list (GET /v1/chains)
  • Token metadata
  • Wallet balances
  • Quote responses

The QueryClient is shared across widget instances for the lifetime of the page. destroy() unmounts the widget instance and clears its DOM, but it does not clear the shared query cache. Multiple widget instances on the same page deduplicate API requests automatically.