Skip to main content

​
Diagram

​
States

StateMeaningBalanceNext action
PENDINGJust created; balance lockedlockedautomatic: AML runs
AML_REVIEWReserved (MVP: not used — AML done pre-request in core-api)locked—
MLRO_REVIEWAwaiting human compliance decisionlockedstaff via /internal/.../aml/decision
CO_SIGNEDBackend signed; waiting for submissionlockedon-chain broadcast
SUBMITTEDOn-chain tx broadcast; txHash storedlockedon-chain confirm/revert
CONFIRMEDTerminal — funds left platformlocked -= amount—
REJECTEDTerminal — denied / failed / revertedlocked → available—
CANCELLEDTerminal — user-cancelled pre-submitlocked → available—

​
Cancellation rules

Users can cancel while status is PENDING, MLRO_REVIEW, or CO_SIGNED: 
POST /api/me/withdrawals/{id}/cancel
# Withdrawal endpoints aren't exposed on the partner API today.
After SUBMITTED the tx is already in the mempool — cancel is not possible. Response: 
{ "code": "invalid_state", "message": "cannot cancel withdrawal in status=SUBMITTED (tx already broadcast or terminal)" }

​
Audit trail

Every transition writes an immutable row to withdrawal_events: CREATED, AML_PASSED, AML_FLAGGED, MLRO_APPROVED, MLRO_REJECTED, BACKEND_COSIGNED, SUBMITTED, CONFIRMED, REVERTED, USER_CANCELLED, REJECTED. The table has NO_UPDATE / NO_DELETE PG rules enforcing append-only semantics. Events are exposed via GET /api/me/withdrawals/{id}/events.