Submit a Crypto Withdrawal Request

POST https://trade-uk.sandbox.zodiamarkets.com/api/3/withdrawal/crypto

Raise a request to withdraw a digital asset to a wallet already whitelisted against your onboarded entity. The request enters an approval queue and moves no funds.

Permissions

The API key needs the Move Funds permission, and your user needs ROLE_OPERATIONS on the accountGroupUuid you name.

Not idempotent

A retry with a fresh nonce creates a second withdrawal. On a timeout or a 500, call List Crypto Withdrawal Requests before resending. See Retrying a submit.

---

Before you call

The walletParticipantUuid must already exist on your onboarded entity for this account group, and be enabled and whitelisted, with an asset equal to ccy. It cannot be created as part of this call. Read the registered wallets from Get Account Details List.

You do not send a destination address. The address is copied from the whitelisted wallet at submit time and returned as coinAddress on the list endpoint. There is no address, network or memo field.

Unlike fiat, amount has no two-decimal cap. The platform stores it to 8 decimal places, so do not send more. A field-level failure returns 403 Invalid signed params without naming the field.

---

After it succeeds

The request starts in PENDING_APPROVAL and appears on List Crypto Withdrawal Requests. The cancel window is shorter than fiat’s: a crypto request is first accepted into the approval queue and then approved, and Cancel a Crypto Withdrawal Request stops working at the first of those two steps.

Domain: Withdrawals

Note

This call is not idempotent and there is no idempotency key. A retry does not resolve to the same request: replaying the original body is refused by the anti-replay check, and resending with a fresh nonce or tonce creates a second withdrawal request. If a submit times out or returns 500, do not retry blind - call the matching list endpoint first to establish whether the request was created, and resubmit only if it was not.

Request

POST https://trade-uk.sandbox.zodiamarkets.com/api/3/withdrawal/crypto

Headers

Header	Required	Description
Rest-Key	yes	API key for authentication
Rest-Sign	yes	Calculated API Signature

Body

Field	Type	Required	Description
tonce	integer (int64)	yes	The current Unix time in microseconds. Accepted only within two minutes of server time. Send either tonce or nonce.
nonce	integer (int64)		Alternative to tonce, and takes precedence when both are sent. Must be a whole number and strictly increasing for a given API key: a reused or lower value is rejected. A request carrying neither nonce nor tonce is rejected with 401.
accountGroupUuid	string	yes	The account group to withdraw from. You must hold ROLE_OPERATIONS on it.
ccy	string	yes	Asset code, e.g. BTC. Must be an asset the platform supports.
amount	number (double)	yes	Amount to withdraw. Must be positive. There is no two-decimal-place cap as there is on fiat, but the platform stores the amount to 8 decimal places, so do not send more.
walletParticipantUuid	string	yes	A wallet registered against your onboarded entity for this account group. It must be enabled and whitelisted, and its asset must equal ccy. Register it before withdrawing; it cannot be created as part of this call. See Get Account Details List.
clientComment	string		Free text, up to 1024 characters. Echoed back on the list endpoints.

Responses

200 OK

Request accepted into the approval queue. No funds have moved.

Body

Field	Type	Required	Description
success	boolean
uuid	string		Identifier of the new crypto withdrawal request. Pass it to the cancel endpoint, and match it against the list endpoint. The request starts in PENDING_APPROVAL.

401 Unauthorized

Authentication failed: unknown key, bad signature, a missing, malformed, reused or decreasing nonce or out-of-window tonce, a body that is not parseable JSON, or a throttled caller. Rate limiting surfaces here as 401, not 429.

Body

Field	Type	Required	Description
success	boolean
message	string

403 Forbidden

Body missing or failed field validation (Invalid signed params), the API key lacks the Move Funds permission (MOVE FUNDS permission required), or you do not hold ROLE_OPERATIONS on accountGroupUuid (You do not have permission to perform this action). The message does not name the field or the permission at fault.

Body

Field	Type	Required	Description
success	boolean
message	string

422 Unprocessable Entity

Business validation failed. The request was not created.

message	Cause
Wallet not found for the caller's accountGroup	walletParticipantUuid is not a wallet on your onboarded entity for this account group
Wallet is disabled or is not whitelisted	The wallet exists but is not usable
Wallet does not support the requested currency	The wallet’s asset is not ccy
Insufficient funds	amount exceeds your total balance on that asset less the requests already in flight

Body

Field	Type	Required	Description
success	boolean
message	string

500 Internal Server Error

Unexpected error. The outcome is undefined - for a submit, use the list endpoint to establish whether the request was created before resending.

Body

Field	Type	Required	Description
success	boolean
message	string