Getting Started

Installation

npm install @tokenflight/swap

Or with other package managers:

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

Register Custom Elements

Before using the HTML tags, register the custom elements once in your application entry point:

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

registerElements();

This registers <tokenflight-swap> and <tokenflight-receive> as custom elements.

You can also set a default wallet adapter (and optional callbacks) for declarative usage:

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

registerElements({
  walletAdapter: myWalletAdapter,
});

Swap Widget

The swap widget lets users exchange tokens across chains.

Declarative (HTML)

<tokenflight-swap theme="dark" default-slippage="50"></tokenflight-swap>

Imperative (JavaScript)

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

const swap = new TokenFlightSwap({
  container: '#swap-widget',
  config: {
    theme: 'dark',
    locale: 'en-US',
    slippage: 50,
  },
  callbacks: {
    onSwapSuccess: (data) => console.log('Swap success:', data),
    onSwapError: (data) => console.log('Swap error:', data),
  },
});

swap.initialize();

Receive Widget

The receive widget accepts a fixed-amount purchase of a specific token.

Declarative (HTML)

<tokenflight-receive
  theme="dark"
  target="eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  amount="100"
  default-slippage="50"
></tokenflight-receive>

Imperative (JavaScript)

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

const receive = new TokenFlightReceive({
  container: '#receive-widget',
  config: {
    target: {
      chainId: 8453,
      address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
    },
    amount: '100',
    theme: 'dark',
    locale: 'en-US',
    slippage: 50,
  },
  callbacks: {
    onSwapSuccess: (data) => console.log('Purchase success:', data),
    onSwapError: (data) => console.log('Purchase error:', data),
  },
});

receive.initialize();

Wallet Adapters

To enable wallet connections, install and configure an adapter:

Adapter	Package
Privy	@tokenflight/adapter-privy
AppKit (WalletConnect)	@tokenflight/adapter-appkit
Thirdweb	@tokenflight/adapter-thirdweb
wagmi	@tokenflight/adapter-wagmi
ethers	@tokenflight/adapter-ethers

Pass the adapter when creating a widget:

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

const swap = new TokenFlightSwap({
  container: '#swap-widget',
  config: { theme: 'dark' },
  walletAdapter: myWalletAdapter,
});

swap.initialize();

Next Steps

• Vanilla JS demo — Full working example with theme and locale controls
• Swap widget reference — Configuration options and callbacks
• Receive widget reference — Target token setup and payment options
• Privy example — Use Privy auth and embedded wallets
• AppKit example — Use Reown AppKit / WalletConnect
• Thirdweb example — Use thirdweb wallet flows
• wagmi example — Use wagmi connectors
• ethers example — Use ethers with injected wallets