Status mapping
Internal lifecycle states mapped to the stable partner-facing status field.
Six possible status values. Use them directly — don’t infer state from anything else. They appear in every /v1/order response and every webhook body.
Partner status vocabulary
| Value | Meaning |
|---|---|
| NEW | Order created, awaiting the deposit transaction. |
| PENDING | Deposit observed on-chain, awaiting confirmations. |
| EXCHANGE | Payout is being executed; the end user has not received funds yet. |
| DONE | Payout transaction broadcast; the end user has received funds. This is the terminal success state on the wire. |
| EXPIRED | Order is no longer actionable — the deposit window closed, the order was removed by the user, or it landed in any other non-live state. We never invent a live state we cannot back with data. |
| EMERGENCY | Partner choice required; see emergency.status for the reason. |
When DONE is final
DONE means the payout transaction has been broadcast and the end user has received funds. It is terminal on the wire; no further status updates follow. time.finish records the moment the payout was broadcast.
Soft-delete invisibility
When a user soft-deletes an order it disappears from the partner surface entirely. /v1/order, /v1/emergency, and /v1/qr collapse to { code: 6, msg: "NOT_FOUND" }, and webhook delivery is suppressed. Aggregate counters on your partner record are never decremented; earnings and volume stay accurate.
Emergency status detail
An order in status = "EMERGENCY" carries a non-empty emergency.status array. The set of values we emit today:
| Value | Meaning |
|---|---|
| LIMIT | Deposit amount is outside the per-pair USD bounds (caps or per-asset min/max). |
| EXPIRED | The order has terminally expired alongside status = EMERGENCY (rare race condition). |
| LESS | Reserved for future use (underpayment classification — currently rolled up into LIMIT). |
| MORE | Reserved for future use (overpayment classification — currently rolled up into LIMIT). |
Resume the order by calling POST /v1/emergency with choice: "EXCHANGE" (continue at the live rate). Orders that should not resume (for example, because the deposit needs to be returned) are finalised by the operator; the final state surfaces through order.status_changed as EXPIRED.
emergency.choice
emergency.choice in the order DTO is NONE until a partner submits a choice through /v1/emergency, then EXCHANGE. Any other value collapses to NONE in the wire response.
