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.

Treat this key as opaque: store it verbatim, do not derive or parse it from a transaction hash. New Tron token deposit keys distinguish the chain, transaction, recipient and token. Different recipients or tokens in one transaction produce distinct deposits and keys. Multiple transfers of the same token to the same recipient within one Tron transaction are still treated as one deposit. Existing queued events retain their original key and payload on retry; EVM/native keys and callback fields are unchanged.

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.

Deposit recovery and combined credits

A normal/force sweep may carry several previously held deposits in one transfer. The single DEPOSIT callback reports that sweep's recorded grossAmount, net amount, and feeAmount; do not separately credit the covered deposits. Retry uses the same recorded ownership, amounts, session correlation and callback identity, without adding later deposits. Treat Tron callback keys as opaque values; never reconstruct or parse them.

An admin refund is an operational return, not a withdrawal or another deposit credit. A held deposit swept specifically for a refund does not generate a DEPOSIT credit. An uncertain refund/sweep is held for operational verification; HTTP 503 from an admin action does not prove no funds moved and must not trigger a new transfer. Operator callback request/payload shapes are unchanged.

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" }.