State machine

Diagram

A request that is refused before it is created never enters this machine and locks nothing: it gets a 4xx error, or a 201 body with status: "rejected" and a code (compliance refusal, for example wallet_banned or aml_blocked), or status: "REJECTED" with an empty id and the reason in reason (for example insufficient balance).

States

State	Meaning	Balance	Next action
`PENDING`	Just created; balance locked	locked	automatic: auto-approved or routed to compliance review
`MLRO_REVIEW`	Awaiting a human compliance decision	locked	compliance team approves or rejects
`CO_SIGNED`	Backend signed; waiting for broadcast	locked	on-chain broadcast
`SUBMITTED`	On-chain tx broadcast; `txHash` stored (it changes if the tx is re-broadcast)	locked	on-chain confirmation
`CONFIRMED`	Terminal — funds left platform	`locked -= amount`	—
`REJECTED`	Terminal — denied in compliance review	`locked → available`	—
`CANCELLED`	Terminal — cancelled by the user before broadcast	`locked → available`	—
`FAILED`	Terminal — could not be broadcast on-chain (the broadcast kept failing, or an account hold blocked it)	`locked → available`	—
`EXPIRED`	Terminal — the signed deadline passed before the withdrawal executed on-chain	`locked → available`	—

The status enum also contains REVERTED. No current transition produces it; if you see it, treat it as terminal and refunded.

Cancellation rules

Users can cancel while status is PENDING, MLRO_REVIEW, or CO_SIGNED:

POST /api/me/withdrawals/{id}/cancel
X-Api-Key: ps_live_<keyId>_<secret>   # needs `vault:write` scope

Cancel needs vault:write even though POST /api/withdrawals/request also accepts the narrower withdraw:write. A key you create in your account settings with the Withdraw permission carries only withdraw:write, so it can request a withdrawal but cannot cancel one. After SUBMITTED the tx is already in the mempool — cancel is not possible. Response (409, standard error envelope):

{
  "status": 409,
  "error": {
    "code": "invalid_state",
    "message": "cannot transition SUBMITTED → CANCELLED",
    "trace_id": "..."
  }
}

Audit trail

Every status transition is recorded in an append-only event log. GET /api/me/withdrawals/{id}/events (portfolio:read) returns it, oldest first:

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

kind is one of created, auto_approved, flagged_for_review:<reason>, mlro_approved, mlro_rejected, broadcast, rebroadcast:… / rebroadcast_unstamped:… (status unchanged, another txHash for the same withdrawal), confirmed, cancelled, expired:<reason>, broadcast_failed:<error>, broadcast_blocked:<reason>. Match on the part before the first :. actor is the user’s wallet (lowercase) for created and cancelled, system for automatic transitions, mlro:<reviewer> for compliance decisions, or chain for the on-chain confirmation 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