Submit a Fiat Withdrawal Request

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

Raise a request to withdraw fiat to a bank account already registered 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 Fiat Withdrawal Requests before resending. See Retrying a submit.

---

Before you call

The bankAccountUuid must already exist on your onboarded entity for this account group, and be enabled and verified, with a currency equal to ccy. It cannot be created as part of this call. Read the registered accounts from Get Account Details List.

amount is capped at two decimal places, and the check is on the scale of the number you send: 25.10 is accepted, 25.100 is not. withdrawalMethod accepts BANK_WIRE and nothing else.

A field-level failure returns 403 Invalid signed params without naming the field, so validate client-side against the table below.

---

After it succeeds

The request starts in PENDING_APPROVAL and appears on List Fiat Withdrawal Requests. It can be withdrawn with Cancel a Fiat Withdrawal Request until Operations approves it. Passing the balance check here is not an approval: a stricter check and a withdrawal limit are applied again at processing, and neither is visible through this API.

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/fiat

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	Currency code, e.g. USD. Must be a currency the platform supports.
amount	number (double)	yes	Amount to withdraw. Must be positive and carry at most two decimal places; a third is rejected.
withdrawalMethod	string (enum)	yes	BANK_WIRE is the only accepted value. — One of: BANK_WIRE
bankAccountUuid	string	yes	A bank account registered against your onboarded entity for this account group. It must be enabled and verified, and its currency 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 fiat 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
Bank account not found in account group	bankAccountUuid is not a bank account on your onboarded entity for this account group
Bank account is disabled or is not verified	The account exists but is not usable
Bank account does not support the requested currency	The account’s currency is not ccy
Insufficient funds	amount exceeds your total balance on that currency 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