Custom Wallet Adapter

TokenFlight widgets don’t bundle a wallet — they talk to wallets through an adapter interface. Official adapters exist for AppKit, wagmi, and ethers, but you can build your own for any provider.

Using a Built-in Adapter

app.js

import { TokenFlightWidget } from '@tokenflight/swap';
import { AppKitWalletAdapter } from '@tokenflight/adapter-appkit';

const widget = new TokenFlightWidget({
  container: '#widget',
  config: {
    toToken: { chainId: 8453, address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' },
    tradeType: 'EXACT_OUTPUT',
    amount: '100',
    theme: 'dark',
  },
  walletAdapter: new AppKitWalletAdapter(appkitInstance),
});
widget.initialize();

Package	Provider
@tokenflight/adapter-appkit	WalletConnect / AppKit
@tokenflight/adapter-wagmi	wagmi
@tokenflight/adapter-ethers	ethers

Example Projects

• AppKit example docs
• wagmi example docs
• ethers example docs

The IWalletAdapter Interface

Implement this interface to connect any wallet:

my-adapter.ts

import type {
  IWalletAdapter,
  WalletAction,
  WalletActionResult,
  WalletActionType,
  WalletEvent,
  WalletEventType,
  ChainType,
} from '@tokenflight/swap';

class MyAdapter implements IWalletAdapter {
  readonly name = 'My Wallet';
  readonly icon = 'https://example.com/icon.svg'; // optional
  readonly supportedActionTypes: WalletActionType[] = [
    'eip1193_request',                  // EVM JSON-RPC
    'solana_signAndSendTransaction',    // Solana
  ];
  // Optional: restrict the widget to only show tokens on these chains
  readonly supportedChainIds = [1, 8453, 42161]; // Ethereum, Base, Arbitrum

  async connect(chainType?: ChainType): Promise<void> { /* ... */ }
  async disconnect(): Promise<void> { /* ... */ }
  isConnected(chainType?: ChainType): boolean { /* ... */ }
  async getAddress(chainType?: ChainType): Promise<string | null> { /* ... */ }
  async executeWalletAction(action: WalletAction): Promise<WalletActionResult> { /* ... */ }

  // Optional
  async signMessage?(message: string, chainType?: ChainType): Promise<string> { /* ... */ }

  on(event: WalletEventType, handler: (e: WalletEvent) => void): void { /* ... */ }
  off(event: WalletEventType, handler: (e: WalletEvent) => void): void { /* ... */ }
}

Key Concepts

Chain Types

types.ts

type ChainType = 'evm' | 'solana';

The widget tells the adapter which chain family it needs. If your wallet only supports one chain type, ignore the parameter and throw on unsupported types.

Supported Chain IDs

Set supportedChainIds to restrict which chains the widget operates on. When set, the widget filters:

• Token list — only tokens on the specified chains are shown
• Token balances — balance queries are scoped to the specified chains
• Token search — search results are limited to the specified chains
• Chain selector — only the specified chains appear in the filter

When omitted, all chains from the API are shown.

// Only show tokens on Ethereum, Base, and Arbitrum
readonly supportedChainIds = [1, 8453, 42161];

wagmi and AppKit adapters derive supportedChainIds automatically from their config — no extra setup needed:

import { WagmiWalletAdapter } from '@tokenflight/adapter-wagmi';

// supportedChainIds is automatically [1, 8453] from wagmiConfig.chains
const adapter = new WagmiWalletAdapter(wagmiConfig);

import { AppKitWalletAdapter } from '@tokenflight/adapter-appkit';

// supportedChainIds is automatically derived from appkit.getCaipNetworks()
// Solana networks are mapped to the internal Solana chain ID
const adapter = new AppKitWalletAdapter(appkitInstance);

ethers adapter requires explicit chain IDs since an EIP-1193 provider has no configured chain list:

import { EthersWalletAdapter } from '@tokenflight/adapter-ethers';

const adapter = new EthersWalletAdapter(window.ethereum, {
  supportedChainIds: [1, 8453, 42161],
});

All adapters accept an explicit supportedChainIds option to override auto-detection.

Common pitfall: If the widget shows zero balance on a chain that the API supports, the chain is likely missing from your wallet library’s network configuration. The auto-derived supportedChainIds only includes chains your wallet is configured for. Add the missing chain to your AppKit/wagmi config, or pass supportedChainIds explicitly. See Troubleshooting → Wallet shows zero balance.

Wallet Actions

The widget sends transaction requests as typed actions:

types.ts

// EVM — a standard JSON-RPC request
interface EvmWalletAction {
  type: 'eip1193_request';
  chainId: number;
  method: string;       // e.g. 'eth_sendTransaction'
  params: unknown[];
}

// Solana — sign a base64-encoded transaction
interface SolanaSignAndSendAction {
  type: 'solana_signAndSendTransaction';
  transaction: string;  // base64
}

Action Results

Return a standardized result:

types.ts

interface WalletActionResult {
  success: boolean;
  data?: unknown;     // provider-specific payload
  error?: string;     // human-readable error
  txHash?: string;    // if a transaction was sent
}

Events

Emit lifecycle events so the widget reacts to wallet state changes:

types.ts

type WalletEventType = 'connect' | 'disconnect' | 'chainChanged' | 'accountsChanged';

Full Example: EVM-Only Adapter

ethers-adapter.ts

import type {
  IWalletAdapter,
  WalletAction,
  WalletActionResult,
  WalletActionType,
  WalletEvent,
  WalletEventType,
  ChainType,
} from '@tokenflight/swap';

interface EIP1193Provider {
  request(args: { method: string; params?: unknown[] }): Promise<unknown>;
}

export class EthersAdapter implements IWalletAdapter {
  readonly name = 'Ethers.js';
  readonly supportedActionTypes: WalletActionType[] = ['eip1193_request'];

  private provider: import('ethers').BrowserProvider | null = null;
  private signer: import('ethers').Signer | null = null;
  private address: string | null = null;
  private listeners = new Map<WalletEventType, Set<(e: WalletEvent) => void>>();

  constructor(private ethereum: EIP1193Provider) {}

  async connect(): Promise<void> {
    const { BrowserProvider } = await import('ethers');
    this.provider = new BrowserProvider(this.ethereum);
    this.signer = await this.provider.getSigner();
    this.address = await this.signer.getAddress();
    this.emit('connect', { address: this.address });
  }

  async disconnect(): Promise<void> {
    this.address = null;
    this.signer = null;
    this.emit('disconnect');
  }

  isConnected(): boolean {
    return this.address !== null;
  }

  async getAddress(): Promise<string | null> {
    return this.address;
  }

  async executeWalletAction(action: WalletAction): Promise<WalletActionResult> {
    if (action.type !== 'eip1193_request') {
      return { success: false, error: 'Unsupported action type' };
    }

    try {
      const result = await this.ethereum.request({
        method: action.method,
        params: action.params,
      });
      return { success: true, data: result, txHash: typeof result === 'string' ? result : undefined };
    } catch (err: unknown) {
      return { success: false, error: (err as Error).message };
    }
  }

  on(event: WalletEventType, handler: (e: WalletEvent) => void): void {
    if (!this.listeners.has(event)) this.listeners.set(event, new Set());
    this.listeners.get(event)!.add(handler);
  }

  off(event: WalletEventType, handler: (e: WalletEvent) => void): void {
    this.listeners.get(event)?.delete(handler);
  }

  private emit(type: WalletEventType, data?: unknown): void {
    for (const h of this.listeners.get(type) ?? []) h({ type, data });
  }
}

Usage:

app.js

import { TokenFlightWidget } from '@tokenflight/swap';
import { EthersAdapter } from './ethers-adapter';

const widget = new TokenFlightWidget({
  container: '#widget',
  config: {
    toToken: { chainId: 8453, address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' },
    tradeType: 'EXACT_OUTPUT',
    amount: '100',
    theme: 'dark',
  },
  walletAdapter: new EthersAdapter(window.ethereum),
});
widget.initialize();