Order lifecycle
Save orderId and sessionId when creating an order. Use customerState for progress and available actions, and status for the overall outcome.
Read the current order
| Order | REST read | Optional WebSocket |
|---|---|---|
| Swap | GET /v2/swaps/{id} | GET /v2/swaps/{id}/events |
| Native bridge | GET /v2/bridges/{id} | GET /v2/bridges/{id}/events |
Send X-Session-ID, or use ?verify=<destination-address> for one read-only order. Missing orders and invalid access proof both return 404. See live updates for WebSockets.
Statuses
| Status | What to show |
|---|---|
awaiting_deposit | Returned funding instructions; check for a partial-deposit notice. |
awaiting_xmr1, awaiting_trx1 | Wrapped-asset funding instructions. |
processing | Progress from customerState; keep tracking. |
completed | Resolved outcome and actual output. |
failed, expired | Failure or expiry, unless customerState supplies a recovery state or action. |
refunded | Refund completed. |
needs_review | Legacy status: treat as processing. |
processing can include an unconfirmed deposit. Use optional confirmations and requiredConfirmations for confirmation progress; do not estimate completion from elapsed time.
Pauses and customer actions
Only customerState.kind: "action_required" enables an action. Its supported actions are coinflip, refund_address, and payout_address. Use the corresponding resource for form data.
A paused state can mean preparing_refund or below_minimum; neither is a completed failure. Continue tracking. A checking notice is informational and requires no separate action.
What arrived versus what was asked
depositAmount is the requested amount. Optional observedDepositAmount on swap reads is what arrived, in the same atomic unit. Use the observed amount for “you sent.”
Partial deposits and continuing early
While awaiting a deposit, customerState.notice.kind: "below_expected" means less than requested arrived. The customer can top up at the same address. Otherwise, when the funding window ends, the order continues with the received amount and adjusts the output. A deposit below the chain minimum pauses as below_minimum.
With the owning session, POST /v2/orders/{id}/deposit-wait/close requests an early end to this wait. Show it only while below_expected is present; otherwise it returns 409. The engine rechecks the deposit before continuing.
Refund address submission
PUT /v2/orders/{id}/refund-address saves an eligible order's refund address. Show the form only for action refund_address. Saving an address is not a completed refund; keep tracking until refunded.
For refundRecovery.kind: "wrong_chain", use its asset, chain, amount, and phase to describe the recovery. The saved destination is immutable. See actions and retries.
Session lists and bulk reads
GET /v2/orders with X-Session-ID lists the session's orders. Rows omit customerState and can lag behind detail reads: use the per-order endpoint before presenting an action. Bridge rows include optional asset and direction; use product to distinguish swaps and bridges.
Hyperliquid execution hashes
Execution receipts and pagination
Swap details can include up to 200 saved fills in hlFills. Deduplicate by tradeId, not the optional txHash: multiple fills may share a hash. This execution hash is separate from deposit and payout hashes.
hlFillsStatus is pending, complete, or incomplete. Collection runs independently of payouts and retries automatically. Missing hashes are omitted; unavailable historical receipts may remain incomplete.
For older fills, call GET /v2/swaps/:id/fills with the same session or destination proof. It returns { fills, status, nextCursor }. Send nextCursor as before; limit accepts 1–200 and defaults to 200. Order detail exposes the cursor as hlFillsNextCursor.
Pages follow receipt collection order, newest first; each page sorts fills by execution time. A null cursor means no older saved receipts, not completed collection. Use terminal order status and actualOutput for the customer's payout.