> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs-v3.openfx.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Initiate fiat withdrawal
> Initiates a fiat withdrawal to an approved bank account.
Initiates a fiat withdrawal to an approved bank account. The target account must already exist in the organization's approved fiat withdrawal accounts — retrieve its ID via [List fiat withdrawal accounts](/v2/api-reference/withdrawals/list-fiat-withdrawal-accounts).
Use this endpoint to:
* Send USD, EUR, GBP, AED, AUD, MXN, BRL, PHP, ARS, or COP to an approved bank account
* Initiate fiat payouts from the organization's balance
* Record a withdrawal that can later be tracked by ID
**Idempotency required.** This POST requires an `Idempotency-Key` header. Keys are cached for 7 days. Reusing the same key with the same body returns the cached response; reusing it with different parameters returns a 422 error.
**FEDWIRE payment details.** Once a USD FEDWIRE withdrawal settles, the bank-side identifiers (IMAD outbound, OMAD inbound) are surfaced on the withdrawal record under `paymentDetails.FEDWIRE`. Poll [`GET /v2/brokerage/{orgId}/withdrawal/{withdrawalId}`](/v2/api-reference/withdrawals/get-withdrawal-by-id) after submission to pick them up — they may not appear on the initial response.
## Errors
| Status | Message | Notes |
| ------ | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| 400 | `Query validation failed` | Request didn't match schema |
| 400 | `Checksum verification failed for withdrawal address` | Destination account fails verification (e.g. malformed routing/SWIFT data) |
| 400 | `Insufficient balance for this withdraw.` | Fiat balance below requested amount (message string includes trailing period and `withdraw` typo per spec) |
| 400 | `Withdrawal account is not active or verified` | Destination bank account exists but is not yet approved for outbound transfers |
| 401 | `The authorization key provided is either invalid or expired, please try again` | Mint a fresh JWT — see [Authentication](/v2/authentication) |
| 409 | `Request with this idempotency key is currently processing` | See [Errors → Idempotency](/v2/errors#idempotency-errors) |
| 422 | `Idempotency key reused with different parameters` | New body → new key |
| 500 | `An internal error has occurred` | Withdrawal may or may not have been submitted — GET the withdrawal by ID before retrying |
See the full [v2 error reference](/v2/errors) for retry semantics and idempotency-specific codes.
## OpenAPI
````yaml POST /v2/brokerage/{orgId}/fiat_withdrawal
openapi: 3.1.0
info:
title: Overview of OpenFX APIs
description: >-
OpenFX provides a robust and secure API suite engineered for high
performance and reliability, enabling programmatic access to real-time
market data, trade execution, and money movement functionalities. This guide
will walk through the step-by-step process of deposits, quoting, trading,
settlements and monitoring using OpenFX APIs.
version: v2.0.0
termsOfService: https://www.openfx.com/terms
contact:
name: OpenFX Support
email: support@openfx.com
url: https://www.openfx.com
servers:
- url: https://api.openfx.com
description: OpenFX API Server
security:
- bearerAuth: []
tags:
- name: MarketData
description: >-
This endpoint retrieves a complete list of all tradable fiat and
stablecoin currency pairs on the OpenFX platform.
- name: Balances
description: >-
The Balance endpoints enable real-time tracking and management of currency
holdings within an account.
- name: Trade
description: >-
The Trade APIs facilitate programmatic currency exchange through a
quote-then-trade workflow, ensuring price transparency and guaranteed
execution at quoted rates.
- name: Deposits
description: >-
Deposit endpoints enable secure funding of trading accounts across
multiple supported currencies and methods.
- name: Withdrawals
description: >-
The Withdrawal API facilitates secure fund withdrawals for both fiat and
stablecoins.
paths:
/v2/brokerage/{orgId}/fiat_withdrawal:
post:
tags:
- Withdrawals
summary: Initiate fiat withdrawal
description: >-
Initiates a fiat withdrawal to an approved bank account.
**Idempotency (V2 only):** This endpoint requires an `Idempotency-Key`
header. Keys are cached for 7 days. Reusing a key with the same
parameters returns the cached response; different parameters return a
422 error.
operationId: initiateFiatWithdrawal
parameters:
- name: Idempotency-Key
in: header
required: true
schema:
type: string
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
description: >-
Unique key to ensure idempotent requests. UUID v4 recommended. Valid
for 7 days.
- schema:
type: string
in: path
name: orgId
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
amount:
type: number
exclusiveMinimum: 0
example: 10
currency:
type: string
enum:
- USD
- AED
- GBP
- EUR
- AUD
- MXN
- BRL
- PHP
- ARS
- COP
example: USD
withdrawalAddressId:
type: string
format: uuid
example: 123e4567-e89b-12d3-a456-426614174001
required:
- amount
- currency
- withdrawalAddressId
responses:
'200':
description: success
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- success
- error
example: success
data:
type: object
properties:
id:
type: string
format: uuid
example: 392cf015-5045-4615-a226-df3543d9c15f
description: Unique identifier for the withdrawal record
createdAt:
type: string
example: '2025-02-07T14:04:14.268Z'
description: UTC Timestamp when the withdrawal request was created
amount:
type: number
example: 0.5
description: Amount of currency requested for withdrawal
currency:
type: string
example: USDT
description: Currency symbol of the withdrawn asset
network:
type: string
example: ETHEREUM
description: Blockchain network name used to process the withdrawal
status:
type: string
examples:
- COMPLETED
- PENDING
description: Current status of the withdrawal
transactionHash:
type:
- string
- 'null'
example: null
description: >-
Blockchain transaction hash if available; null if not
yet processed
withdrawalAddressId:
type: string
format: uuid
example: 2697eff1-ac30-41db-94b7-d615133a5c9e
description: Unique identifier for the withdrawal address used
orgId:
type: string
format: uuid
example: c96183a5-2830-4606-9ae2-15dfd058872b
description: >-
Unique identifier of the organization associated with
the withdrawal
actorId:
type: string
format: uuid
example: 36bdb6a4-7cc6-4a08-b325-db416dbdd9f5
description: >-
Unique identifier of the user who initiated the
withdrawal
actorEmail:
type: string
format: email
example: test-user@example.co
description: Email of the actor who initiated the withdrawal
comments:
type: string
example: Client initiated the withdrawal
description: >-
Optional notes or comments about the withdrawal
request
message:
type: string
example: Data fetched successfully
examples:
default_example:
value:
status: success
data:
id: 123e4567-e89b-12d3-a456-426614174000
createdAt: '2024-10-10T07:15:44.030Z'
amount: 1000000
currency: USD
network: FIAT
status: PENDING
transactionHash: null
withdrawalAddressId: 123e4567-e89b-12d3-a456-426614174001
orgId: 123e4567-e89b-12d3-a456-426614174002
actorId: 123e4567-e89b-12d3-a456-426614174003
actorEmail: test-user@example.co
comments: Client initiated the withdrawal via API
'400':
description: error
content:
application/json:
examples:
checksum_failed:
summary: Checksum failed
value:
status: error
message: Checksum verification failed for withdrawal address
insufficient_balance:
summary: Insufficient balance
value:
status: error
message: Insufficient balance for this withdraw.
inactive_account:
summary: Inactive account
value:
status: error
message: Withdrawal account is not active or verified
'401':
description: Unauthorized
content:
application/json:
examples:
default_example:
value:
status: error
message: >-
The authorization key provided is either invalid or
expired, please try again
'409':
description: Conflict
content:
application/json:
examples:
default_example:
value:
status: error
message: Request with this idempotency key is currently processing
error:
code: IDEMPOTENCY_IN_FLIGHT
details: Please wait for the original request to complete
'422':
description: Unprocessable Entity
content:
application/json:
examples:
default_example:
value:
status: error
message: Idempotency key reused with different parameters
error:
code: IDEMPOTENCY_MISMATCH
details: >-
This idempotency key was already used with different
request parameters
'500':
description: Internal Server Error
content:
application/json:
examples:
default_example:
value:
status: error
message: An internal error has occurred
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````