Transaction Lifecycle

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

Should you read this?

Read this page when you need to explain loading states, wallet prompts, order tracking, or delayed settlement to users.

If you only need to embed the widget, start with Getting Started.

Key words

• quote: ask the API for routes and prices.
• build: turn the chosen route into wallet actions.
• submit: send the signed transaction hash or signed payload to the API.
• track: poll the order until it is filled, refunded, or failed.
• walletAdapter: the object that asks the user's wallet to sign.
• EXACT_INPUT: the user fixes the amount they pay.
• EXACT_OUTPUT: your app fixes the amount that must arrive.

State Machine Diagram

Any active phase (quoting through tracking) can transition to error. From error, the widget returns 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 the matching error callback for the active flow.

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 success 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.

Next step

• Need callbacks for each outcome? Read Events & Callbacks.
• Need to trust a completed payment? Read Backend Verification.