State machine

Diagram

States

State	Meaning	Balance	Next action
`PENDING`	Just created; balance locked	locked	automatic: AML runs
`AML_REVIEW`	Reserved (MVP: not used — AML done pre-request in core-api)	locked	—
`MLRO_REVIEW`	Awaiting human compliance decision	locked	staff via `/internal/.../aml/decision`
`CO_SIGNED`	Backend signed; waiting for submission	locked	on-chain broadcast
`SUBMITTED`	On-chain tx broadcast; `txHash` stored	locked	on-chain confirm/revert
`CONFIRMED`	Terminal — funds left platform	`locked -= amount`	—
`REJECTED`	Terminal — denied / failed / reverted	`locked → available`	—
`CANCELLED`	Terminal — user-cancelled pre-submit	`locked → 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. GET /api/me/withdrawals/{id}/events returns the full lifecycle audit stream:

{
  "id": "wd-...",
  "events": [
    {
      "id": "evt-...",
      "kind": "created",
      "fromStatus": null,
      "toStatus": "CREATED",
      "actor": "0xab12...",
      "txHash": null,
      "createdAt": "2026-04-30T12:00:00Z"
    },
    {
      "id": "evt-...",
      "kind": "broadcast",
      "fromStatus": "BACKEND_COSIGNED",
      "toStatus": "SUBMITTED",
      "actor": "system",
      "txHash": "0x...",
      "createdAt": "2026-04-30T12:00:05Z"
    }
  ]
}

kind is one of created, auto_approved, mlro_approved, mlro_rejected, cosigned, broadcast, confirmed, reverted, cancelled, rejected. actor is the EOA for user-initiated transitions, system for back-office workflows, or chain for the chain-watcher that flips SUBMITTED → CONFIRMED. Use this endpoint for any compliance audit trail — GET /api/me/withdrawals/{id} only returns the head state.

Getting Started

Authentication

Vaults

Deposits

Trading

Events & Tags

Markets

Portfolio

Withdrawals

WebSocket

Settlement & Oracle

On-chain Contracts

Partners

Errors

Diagram

States

Cancellation rules

Audit trail

​Diagram

​States

​Cancellation rules

​Audit trail

Diagram

States

Cancellation rules

Audit trail