Events & Callbacks

TokenFlight communicates with your application through callback functions. There are no DOM CustomEvents.

Available Callbacks

Callback	Trigger	Payload
onSwapSuccess(data)	Order filled successfully	SwapSuccessData
onSwapError(data)	Any execution error occurs	SwapErrorData
onWalletConnected(data)	Wallet connects or address changes	WalletConnectedData
onQuoteReceived(data)	New quote arrives from the API	QuoteResponse
onAmountChanged(data)	User changes an editable amount	AmountChangedData
onConnectWallet()	User clicks "Connect Wallet" and no adapter is provided	—
onAccountModal()	User clicks the wallet address button	—

Callback Payloads

interface SwapSuccessData {
  orderId: string;
  fromToken: string;
  toToken: string;
  fromAmount: string;
  toAmount: string;
  txHash: string;
}

interface SwapErrorData {
  code: string;
  message: string;
  details?: unknown;
}

interface WalletConnectedData {
  address: string;
  chainType: string;
}

interface AmountChangedData {
  amount: string;
  direction: "from" | "to";
}

Three Ways to Pass Callbacks

1. registerWidgetElement() Defaults

registerWidgetElement({
  callbacks: {
    onSwapSuccess: (data) => {
      analytics.track('swap_success', {
        from: data.fromToken,
        to: data.toToken,
        txHash: data.txHash,
      });
    },
    onSwapError: (error) => {
      console.error(`[${error.code}] ${error.message}`);
    },
    onConnectWallet: () => {
      myWalletModal.open();
    },
  },
});

<tokenflight-widget
  to-token="eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  trade-type="EXACT_OUTPUT"
  amount="100"
  theme="dark"
></tokenflight-widget>

2. Element __callbacks

registerWidgetElement();

const widgetEl = document.querySelector('tokenflight-widget');
widgetEl.__callbacks = {
  onSwapSuccess: (data) => showConfirmationDialog(data),
};

3. Imperative Constructor Callbacks

const widget = new TokenFlightWidget({
  container: '#widget',
  config: {
    toToken: { chainId: 8453, address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' },
    tradeType: 'EXACT_OUTPUT',
    amount: '100',
    theme: 'dark',
  },
  callbacks: {
    onSwapSuccess: (data) => console.log('Order:', data.orderId),
    onSwapError: (error) => showErrorToast(error.message),
    onWalletConnected: ({ address, chainType }) => {
      console.log(`Connected: ${address} (${chainType})`);
    },
    onAmountChanged: ({ amount, direction }) => {
      console.log(`Amount changed: ${amount} (${direction})`);
    },
    onQuoteReceived: (quote) => console.log('Quote:', quote),
    onConnectWallet: () => myWalletModal.open(),
    onAccountModal: () => myAccountModal.open(),
  },
});

widget.initialize();

Analytics Example

const widget = new TokenFlightWidget({
  container: '#widget',
  config: {
    toToken: { chainId: 8453, address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' },
    tradeType: 'EXACT_OUTPUT',
    amount: '100',
    theme: 'dark',
  },
  callbacks: {
    onSwapSuccess: (data) => {
      analytics.track('swap_completed', {
        orderId: data.orderId,
        fromToken: data.fromToken,
        toToken: data.toToken,
        txHash: data.txHash,
      });
    },
    onSwapError: (error) => {
      analytics.track('swap_error', {
        code: error.code,
        message: error.message,
      });
    },
  },
});