Create a withdrawal

POST

withdrawals

Node.js

const url = 'https://api.openfx.com/v3/fx/withdrawals';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'X-Request-Signature': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    withdrawalAccountId: 'wac_NDqQ9LmcUASpnHR6CTvdkk',
    withdrawalAmount: '1000.00',
    currency: 'USD'
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests, json, uuid
# sign_request mints a fresh 60s JWT AND the matching X-Request-Signature. See Authentication
# `withdrawalAccountId` from GET /v3/fx/withdrawal-accounts

url = 'https://api.openfx.com/v3/fx/withdrawals'
body = json.dumps({
    'withdrawalAccountId': withdrawal_account_id,
    'withdrawalAmount': '1000.00',
    'currency': 'USD',
}).encode()
headers, body = sign_request('POST', url, body)
withdrawal = requests.post(
    url,
    headers={**headers, 'Idempotency-Key': str(uuid.uuid4())},
    data=body,
).json()

HttpResponse<String> response = Unirest.post("https://api.openfx.com/v3/fx/withdrawals")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("X-Request-Signature", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"withdrawalAccountId\": \"wac_NDqQ9LmcUASpnHR6CTvdkk\",\n  \"withdrawalAmount\": \"1000.00\",\n  \"currency\": \"USD\"\n}")
  .asString();

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.openfx.com/v3/fx/withdrawals");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Idempotency-Key: <idempotency-key>");
headers = curl_slist_append(headers, "Authorization: Bearer <token>");
headers = curl_slist_append(headers, "X-Request-Signature: <api-key>");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{\n  \"withdrawalAccountId\": \"wac_NDqQ9LmcUASpnHR6CTvdkk\",\n  \"withdrawalAmount\": \"1000.00\",\n  \"currency\": \"USD\"\n}");

CURLcode ret = curl_easy_perform(hnd);

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.openfx.com/v3/fx/withdrawals"

	payload := strings.NewReader("{\n  \"withdrawalAccountId\": \"wac_NDqQ9LmcUASpnHR6CTvdkk\",\n  \"withdrawalAmount\": \"1000.00\",\n  \"currency\": \"USD\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("X-Request-Signature", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

curl --request POST \
  --url https://api.openfx.com/v3/fx/withdrawals \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Request-Signature: <api-key>' \
  --data '
{
  "withdrawalAccountId": "wac_NDqQ9LmcUASpnHR6CTvdkk",
  "withdrawalAmount": "1000.00",
  "currency": "USD"
}
'

{
  "data": {
    "object": "withdrawal",
    "id": "wtd_4nR9pQ2vXk7LmZs8TcWobY",
    "currency": "USD",
    "assetType": "FIAT",
    "withdrawalAmount": "1000.00",
    "status": "COMPLETED",
    "network": null,
    "withdrawalAccountId": "wac_NDqQ9LmcUASpnHR6CTvdkk",
    "estimatedCompletionAt": null,
    "transactionHash": null,
    "paymentDetails": {
      "FEDWIRE": {
        "imad": "20260517KLR00318000742",
        "omad": "20261103GHP0041800293847561NQ0785"
      }
    },
    "actorId": "usr_7m4VsfRw4pGrS76WYj5tnx",
    "actorEmail": "client-user@example.com",
    "createdAt": "2026-03-22T12:00:00.000Z",
    "metadata": {}
  }
}

Authorizations

Authorization

string

header

required

ES256-signed JWT bearer token, single-use, 60-second TTL. See Authentication for how to mint one.

X-Request-Signature

string

header

required

ES256 signature over the request, bound to the bearer JWT. Required on every request. See Authentication → Request signing.

Headers

Idempotency-Key

string

required

Client-generated unique key to make a write operation safely retryable. UUID recommended. See Idempotency.

Required string length: 1 - 255

Pattern: ^[a-zA-Z0-9_-]{1,255}$

Example:

"550e8400-e29b-41d4-a716-446655440000"

X-Request-Id

string

Optional, client-supplied correlation ID for this request. Echoed verbatim on the response when supplied; the response omits it when the request did not supply one. Distinct from X-Trace-Id (server-generated, always present). See Metadata & tracing.

Example:

"my-req-abc-123"

X-App-Mode

enum<string>

default:SANDBOX

Environment selector, matching the API key's bound environment. Defaults to SANDBOX when omitted. See Environments. When present, the value must be SANDBOX or LIVE, matched without regard to case. Any other value, including an empty one, returns 400 INVALID_APP_MODE; details.received echoes the value you sent.

Available options:

SANDBOX,

LIVE

Example:

"SANDBOX"

Body

application/json

Initiates a withdrawal to a verified withdrawal account. Rail (fiat vs stablecoin) and network are resolved server-side from withdrawalAccountId. Unknown fields are rejected with 400 VALIDATION_BODY_FAILED.

currency

string

required

Currency to withdraw. The server dispatches crypto vs fiat based on the value — a single union, not separate endpoints.

Pattern: ^[A-Z0-9]{2,15}$

Example:

"USDC"

withdrawalAmount

string

required

Positive decimal amount; must be greater than zero.

Pattern: ^[0-9]+(\.[0-9]{1,16})?$

Example:

"1000.00"

withdrawalAccountId

string

required

Verified withdrawal account from GET /v3/fx/withdrawal-accounts.

Pattern: ^([a-z]{3,5}_[1-9A-HJ-NP-Za-km-z]{1,22}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$

Example:

"wac_NDqQ9LmcUASpnHR6CTvdkk"

metadata

object

Optional client-owned bookkeeping bag, persisted with the withdrawal. Accepted only in the request body of POST /v3/fx/withdrawals and returned nested at data.metadata on success. Keys are client-defined strings (e.g. customerId); values must be strings. See Withdrawal metadata for limits, immutability, and error-response behavior. Metadata is visible in the OpenFX platform, API, and MCP server (including connected AI tools), so don't include sensitive or personal data.

Show child attributes

Example:

{
  "customerId": "cus_12345",
  "reconId": "recon-2026-0001"
}

Response

Withdrawal created.

data

object

required

A withdrawal from your trade account.

Show child attributes

⌘I

Node.js

const url = 'https://api.openfx.com/v3/fx/withdrawals';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'X-Request-Signature': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    withdrawalAccountId: 'wac_NDqQ9LmcUASpnHR6CTvdkk',
    withdrawalAmount: '1000.00',
    currency: 'USD'
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests, json, uuid
# sign_request mints a fresh 60s JWT AND the matching X-Request-Signature. See Authentication
# `withdrawalAccountId` from GET /v3/fx/withdrawal-accounts

url = 'https://api.openfx.com/v3/fx/withdrawals'
body = json.dumps({
    'withdrawalAccountId': withdrawal_account_id,
    'withdrawalAmount': '1000.00',
    'currency': 'USD',
}).encode()
headers, body = sign_request('POST', url, body)
withdrawal = requests.post(
    url,
    headers={**headers, 'Idempotency-Key': str(uuid.uuid4())},
    data=body,
).json()

HttpResponse<String> response = Unirest.post("https://api.openfx.com/v3/fx/withdrawals")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("X-Request-Signature", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"withdrawalAccountId\": \"wac_NDqQ9LmcUASpnHR6CTvdkk\",\n  \"withdrawalAmount\": \"1000.00\",\n  \"currency\": \"USD\"\n}")
  .asString();

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.openfx.com/v3/fx/withdrawals");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Idempotency-Key: <idempotency-key>");
headers = curl_slist_append(headers, "Authorization: Bearer <token>");
headers = curl_slist_append(headers, "X-Request-Signature: <api-key>");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{\n  \"withdrawalAccountId\": \"wac_NDqQ9LmcUASpnHR6CTvdkk\",\n  \"withdrawalAmount\": \"1000.00\",\n  \"currency\": \"USD\"\n}");

CURLcode ret = curl_easy_perform(hnd);

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.openfx.com/v3/fx/withdrawals"

	payload := strings.NewReader("{\n  \"withdrawalAccountId\": \"wac_NDqQ9LmcUASpnHR6CTvdkk\",\n  \"withdrawalAmount\": \"1000.00\",\n  \"currency\": \"USD\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("X-Request-Signature", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

curl --request POST \
  --url https://api.openfx.com/v3/fx/withdrawals \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Request-Signature: <api-key>' \
  --data '
{
  "withdrawalAccountId": "wac_NDqQ9LmcUASpnHR6CTvdkk",
  "withdrawalAmount": "1000.00",
  "currency": "USD"
}
'

{
  "data": {
    "object": "withdrawal",
    "id": "wtd_4nR9pQ2vXk7LmZs8TcWobY",
    "currency": "USD",
    "assetType": "FIAT",
    "withdrawalAmount": "1000.00",
    "status": "COMPLETED",
    "network": null,
    "withdrawalAccountId": "wac_NDqQ9LmcUASpnHR6CTvdkk",
    "estimatedCompletionAt": null,
    "transactionHash": null,
    "paymentDetails": {
      "FEDWIRE": {
        "imad": "20260517KLR00318000742",
        "omad": "20261103GHP0041800293847561NQ0785"
      }
    },
    "actorId": "usr_7m4VsfRw4pGrS76WYj5tnx",
    "actorEmail": "client-user@example.com",
    "createdAt": "2026-03-22T12:00:00.000Z",
    "metadata": {}
  }
}

Core concepts

Endpoints

Webhooks

Create a withdrawal

Authorizations

Headers

Body

Response