Getting Started

Get up and running with TokenFlight Embed in minutes. Try the interactive Playground →

1. Install the SDK

   Terminal

   npm install @tokenflight/swap

   Or with other package managers:

   Terminal

   pnpm add @tokenflight/swap
   yarn add @tokenflight/swap

   Note

   @tokenflight/swap is the only required package.

   Optional wallet adapter packages:

   • @tokenflight/adapter-appkit
   • @tokenflight/adapter-wagmi
   • @tokenflight/adapter-ethers

   Tree-shaking

   For new integrations, prefer the widget-only subpath:

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

2. Register the Public Custom Element

   app.js

   import { registerWidgetElement } from '@tokenflight/swap/widget';
   
   registerWidgetElement();

   The supported public custom element is <tokenflight-widget>.

   TypeScript users can add one import for attribute autocomplete:

   import "@tokenflight/swap/custom-elements";

3. Mount a Widget

   <tokenflight-widget> supports all public modes:

   • Swap: default exact-input flow
   • Receive: trade-type="EXACT_OUTPUT" with amount

   Declarative (HTML)

   index.html

   <!-- Swap mode -->
   <tokenflight-widget
     theme="dark"
     from-token="eip155:1:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
     to-token="eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
   ></tokenflight-widget>
   
   <!-- Fixed-amount receive mode -->
   <tokenflight-widget
     theme="dark"
     to-token="eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
     trade-type="EXACT_OUTPUT"
     amount="100"
   ></tokenflight-widget>

   Imperative (JavaScript)

   app.js

   import { TokenFlightWidget } from '@tokenflight/swap';
   
   const widget = new TokenFlightWidget({
     container: '#widget',
     config: {
       toToken: {
         chainId: 8453,
         address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
       },
       tradeType: 'EXACT_OUTPUT',
       amount: '100',
       theme: 'dark',
       locale: 'en-US',
     },
     walletAdapter: myWalletAdapter,
     callbacks: {
       onSwapSuccess: (data) => console.log('Success:', data),
       onSwapError: (data) => console.log('Error:', data),
     },
   });
   
   widget.initialize();

Quick Start

Declarative

index.html

<tokenflight-widget
  theme="dark"
  from-token="eip155:1:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
  to-token="eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
></tokenflight-widget>

<script type="module">
  import { registerWidgetElement } from '@tokenflight/swap/widget';
  registerWidgetElement();
</script>

Imperative

app.js

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

const widget = new TokenFlightWidget({
  container: '#widget',
  config: {
    toToken: {
      chainId: 8453,
      address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
    },
    tradeType: 'EXACT_OUTPUT',
    amount: '100',
    theme: 'dark',
  },
  callbacks: {
    onConnectWallet: () => {
      console.log('Connect wallet requested');
    },
  },
});

widget.initialize();

index.html

<div id="widget" style="min-height: 560px;"></div>

Widget Modes

Use the same component for every public flow:

Goal	Widget configuration
Exact-input swap	Default widget, optionally pre-set from-token and to-token
Fixed-amount receive	trade-type="EXACT_OUTPUT" plus amount

Wallet Adapters

If your app already owns wallet UX, handle onConnectWallet yourself. If you want the widget to drive wallet connection flows, provide a wallet adapter:

• @tokenflight/adapter-appkit
• @tokenflight/adapter-wagmi
• @tokenflight/adapter-ethers

See Examples and Wallet Adapter Guide.