Transactions and Retries
A withdrawal is an asynchronous business operation. A successful HTTP response means the request was handled; it does not establish that funds arrived on-chain.
Persist one business identifier
Generate and store client_request_id before sending a withdrawal. Reuse it for retries of the same intended operation, including after a process restart. Keep the transaction’s fields consistent; the current implementation rejects a repeated identifier with conflicting business parameters.
Do not rely only on an Idempotency-Key header. The supplied SDK can add that header, but the current withdrawal deduplication contract is based on the body field client_request_id.
Understand request data
This table highlights core fields, not a complete request schema. Confirm preview, fee confirmation and custody-specific requirements against the integration version. Avoid binary floating-point amounts and do not copy example chain or asset numbers between environments.
Follow the result
The list is illustrative and may evolve. Preserve unknown states for investigation instead of mapping them to success or failure. A failed or rejected label alone is not sufficient evidence that nothing was signed or broadcast.
Recover after a timeout
Query GET /api/v1/withdrawals/by-request using the original client_request_id query parameter. Keep polling or reconciling the original operation while its result is uncertain. If authorization renewal is required, use the same identifier and the agreed renewal procedure.
Cancellation depends on the actual signing stage and the server’s checks. Only start a replacement business operation after the original is established as not transferred and unable to transfer. Receive events through webhooks, and retain API queries as a reconciliation path.