Event Types

1. DEPOSIT

Sent when a user's deposit is confirmed on-chain and funds have been swept to the bankroll.

Delivery: Asynchronous, via a durable outbox — retried up to 5× with backoff, then dead-lettered (see Retries). Return { "error": 0 } to acknowledge; any non-zero error (or a non-2xx / non-JSON response) is treated as a failed delivery and retried — so acknowledge with 0 even for duplicates or events you choose to ignore.

Payload fields:

Expected response:

{
  "error": 0,
  "description": "ok",
  "transactionId": "your-internal-id"
}

Idempotency: Use idempotencyKey to deduplicate. You may receive the same deposit event more than once.

2. WITHDRAW_REQUEST

Sent to request your approval of a withdrawal. Delivered one of two ways depending on your operator's approval mode (see Withdrawals):

• Synchronous mode (default): sent before the withdrawal record is persisted, and the system waits for your response — return error: 0 to approve, non-zero to deny. withdrawRequestId is populated here too.
• External-approval mode: sent asynchronously (retried via our outbox) after the request is created as AWAITING_APPROVAL. Your response only acknowledges receipt (error: 0); the real decision is a separate callback you make to POST /withdraw/{withdrawRequestId}/decision.

Delivery: Synchronous (default mode) or asynchronous + retried (external-approval mode).

Payload fields:

To approve - return:

{
  "error": 0,
  "description": "ok"
}

To deny - return a non-zero error code:

{
  "error": 5,
  "description": "Daily withdrawal limit exceeded"
}

Error codes:

Any other non-zero code will show the description field from your response as the error message.

3. WITHDRAW_COMPLETE

Sent after a withdrawal has been completed (funds paid out on-chain).

Delivery: Asynchronous, via a durable outbox — retried up to 5× with backoff, then dead-lettered (see Retries). Return { "error": 0 } to acknowledge; any non-zero error (or a non-2xx / non-JSON response) is treated as a failed delivery and retried, so acknowledge even for duplicates.

Payload fields:

Expected response:

{
  "error": 0,
  "description": "ok"
}

4. WITHDRAW_FAILED (headless only)

Sent when a headless withdrawal fails. Delivered asynchronously via the durable outbox (same retry/dedup as WITHDRAW_COMPLETE).

Payload fields — the WITHDRAW_COMPLETE shape (same fields, same units) with status: "FAILED", no completedAt, plus the two fields marked headless-only:

Expected response: { "error": 0, "description": "ok" } — acknowledge (even duplicates). Acknowledging does not decide the outcome; drive your ledger from retryable.

5. WITHDRAW_CANCELLED (headless only)

Sent when a headless withdrawal is cancelled before any on-chain broadcast (via POST /withdrawals/{sessionRef}/cancel, or an equivalent terminal cancellation). Delivered asynchronously via the durable outbox.

Cancellation is terminal and releases the reserve — the reservation is freed and no payout was or will be sent.

Payload fields: the same shape as WITHDRAW_FAILED with event: "WITHDRAW_CANCELLED", status: "CANCELLED", a reasonCode and an eventId, and no retryable field (the event itself is terminal). cryptoAmountSent / amountInUsd are "null" when the intent was cancelled before it was priced — the common case.

Expected response: { "error": 0, "description": "ok" }.