Docs › Build with Beluga

Order lifecycle

Every state an order can be in, how it moves between them, and what to show your users at each step.

Read the current order

GET /api/order/:id returns the order or 404. The order ID is the only access credential: anyone who has it can read the order, so treat it like a receipt number. Poll every 10 seconds or slower. Field reference: API reference.

States

State	Kind	Meaning
`new`	deposit	Order created, subaddress being assigned (about 20 seconds).
`awaiting_deposit`	deposit	Waiting for XMR at `depositAddress` until `expiresAt`.
`confirming`	deposit	XMR seen; `confirmations` counts up to `confsNeeded` (5, or 10 for deposits of 200 XMR or more). No longer expires.
`crediting`	deposit	Confirmed; XMR2 is being sent to `hlAddress`.
`awaiting_tokens`	withdraw	Waiting for XMR2 at the order's own address `depositAddress` (= `sendTo`) until `expiresAt`.
`paying`	withdraw	XMR2 received; XMR payout to `xmrAddress` in progress.
`completed`	both	Done. `amountOut` and `outTx` are set.
`review`	both	Held for a manual check. Nothing is lost; the order continues or is refunded.
`expired`	both	Nothing arrived before `expiresAt`. Late funds are recovered through support.
`refunded`	both	Funds returned per the refund policy.

Final states: completed, expired, refunded. review is not final.

Deposit flow

new → awaiting_deposit → confirming → crediting → completed
               │                           └→ review → crediting | refunded
               └→ expired

Several transfers to the same subaddress add up; amountIn is their sum and inTx lists all transaction IDs, comma-separated.
Confirmations are those of the least-confirmed transfer, so a late top-up restarts the wait for that part.
Expiry only applies while nothing has been seen. Once a transfer is in the pool, the order moves to confirming and stays alive.
Review happens while issuing is paused, or if we can't confirm the credit on chain.

Redemption flow

awaiting_tokens → paying → completed
        │            └→ review → paying | refunded
        └→ expired

Matching: every redemption has its own Hyperliquid address, never reused. The first XMR2 transfer to it, from any account, pays that order's xmrAddress. A transfer after expiresAt still belongs to its order (an expired order then moves on to paying; checked for 7 days).
Unmatched transfers (straight to the bridge wallet, or a second transfer to an order address) are recorded and handled by support; they don't create an order.
Review happens while redemptions are paused or if the payout can't be confirmed automatically.

What to show users

Funding instructions (address, window) exactly as returned, with the expiry time.
Confirmation progress as confirmations of confsNeeded; don't estimate completion from elapsed time.
For review: "being checked, nothing is lost". For expired: "create a new order before sending".