Transaction Lifecycle

The TokenFlight widget follows this phase model. Understanding this lifecycle helps you build appropriate UI feedback and handle edge cases.

State Machine Diagram

idle → quoting → quoted → building → awaiting-wallet → submitting → tracking → success
  ↑       ↑                                                                       │
  ├───────┴──────────────────── error ←───────────────────────────────────────────┘
  └─────────────────────────── success

From error, the widget can return to idle (fresh start) or quoting (retry with same inputs).

Phase Details

Phase	What Happens	Cancel?	Duration
idle	Widget ready; user selecting tokens/amounts	—	—
quoting	POST /v1/quotes — fetching routes	Yes	1–5 s
quoted	Routes displayed; user reviews and selects	Yes	User action
building	POST /v1/deposit/build — constructing wallet actions	No	< 2 s
awaiting-wallet	Wallet popup; waiting for signature	Yes	User action
submitting	PUT /v1/deposit/submit — submitting tx hash	No	< 2 s
tracking	GET /v1/orders/:address — polling for completion	No	10 s – 10 min
success	Order filled; funds arrived	Reset	—

API Lifecycle

Each swap follows a four-step API lifecycle:

1. Quote

POST /v1/quotes

Requests cross-chain swap quotes. The API returns one or more route options from providers like Across, DeBridge, Glacis, or Hyperstream’s native router.

2. Build

POST /v1/deposit/build

Takes the selected route and returns a sequence of wallet actions to execute (token approvals, contract calls, etc.). Each action includes the chain ID, method, and parameters needed for the wallet.

3. Submit

PUT /v1/deposit/submit

After the user signs the transaction in their wallet, the SDK submits the transaction hash to the API. This creates an order and begins tracking.

4. Track

GET /v1/orders/:address

Polls for order status. Uses progressive polling intervals to balance responsiveness with API load:

Time Since Submit	Poll Interval
0–10 seconds	Every 1 second
10–30 seconds	Every 2 seconds
30–60 seconds	Every 3 seconds
60–120 seconds	Every 5 seconds
120+ seconds	Every 10 seconds

Error Recovery

Errors can occur at any phase. Most execution/configuration failures transition the widget to error and invoke onSwapError.

Before Wallet Signature

If an error occurs before the user signs (phases: quoting, quoted, building), no funds have left the wallet. The widget can safely return to idle for a retry.

After Wallet Signature

If the transaction was signed and broadcast but the order fails (phases: submitting, tracking), funds may have been sent. The SwapErrorData includes details you can use to investigate:

• Use the txHash from the onSwapSuccess callback to check the transaction on the source chain’s block explorer.
• Query GET /v1/orders/:address from your backend to check the order status.

Phase Transitions from Error

From the error phase, the widget can transition to:

• idle — reset and start over
• quoting — retry with a new quote
• quoted — return to route selection (if the quote is still valid)

Wallet Rejection

When the user rejects the wallet signature prompt, the widget transitions from awaiting-wallet to error. In current adapters, this is commonly surfaced as TF2003 (WALLET_ACTION_FAILED) with a rejection message from the wallet.

Timeouts

• API requests: 15-second timeout. If the API does not respond, the widget transitions to error with code TF3002 (API_TIMEOUT).
• No automatic retry: The SDK uses retry: 0 for API requests. Users must manually retry by interacting with the widget.