Create an account bank withdrawal
curl --request POST \
--url https://api-sandbox.circle.com/v1/accounts/withdrawals \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
"destination": {
"type": "wire",
"id": "b8627ae8-732b-4d25-b947-1df8f4007a29"
},
"amount": {
"amount": "3.14",
"currency": "USD"
},
"riskSignals": {
"ipAddress": "203.0.113.42",
"sessionId": "8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c",
"deviceId": "2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f"
},
"burnAll": false,
"metadata": {
"customerExternalRef": "payout-2026-0001"
}
}
'import requests
url = "https://api-sandbox.circle.com/v1/accounts/withdrawals"
payload = {
"idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
"destination": {
"type": "wire",
"id": "b8627ae8-732b-4d25-b947-1df8f4007a29"
},
"amount": {
"amount": "3.14",
"currency": "USD"
},
"riskSignals": {
"ipAddress": "203.0.113.42",
"sessionId": "8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c",
"deviceId": "2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f"
},
"burnAll": False,
"metadata": { "customerExternalRef": "payout-2026-0001" }
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
idempotencyKey: 'ba943ff1-ca16-49b2-ba55-1057e70ca5c7',
destination: {type: 'wire', id: 'b8627ae8-732b-4d25-b947-1df8f4007a29'},
amount: {amount: '3.14', currency: 'USD'},
riskSignals: {
ipAddress: '203.0.113.42',
sessionId: '8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c',
deviceId: '2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f'
},
burnAll: false,
metadata: {customerExternalRef: 'payout-2026-0001'}
})
};
fetch('https://api-sandbox.circle.com/v1/accounts/withdrawals', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-sandbox.circle.com/v1/accounts/withdrawals",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'idempotencyKey' => 'ba943ff1-ca16-49b2-ba55-1057e70ca5c7',
'destination' => [
'type' => 'wire',
'id' => 'b8627ae8-732b-4d25-b947-1df8f4007a29'
],
'amount' => [
'amount' => '3.14',
'currency' => 'USD'
],
'riskSignals' => [
'ipAddress' => '203.0.113.42',
'sessionId' => '8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c',
'deviceId' => '2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f'
],
'burnAll' => false,
'metadata' => [
'customerExternalRef' => 'payout-2026-0001'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-sandbox.circle.com/v1/accounts/withdrawals"
payload := strings.NewReader("{\n \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n \"destination\": {\n \"type\": \"wire\",\n \"id\": \"b8627ae8-732b-4d25-b947-1df8f4007a29\"\n },\n \"amount\": {\n \"amount\": \"3.14\",\n \"currency\": \"USD\"\n },\n \"riskSignals\": {\n \"ipAddress\": \"203.0.113.42\",\n \"sessionId\": \"8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c\",\n \"deviceId\": \"2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f\"\n },\n \"burnAll\": false,\n \"metadata\": {\n \"customerExternalRef\": \"payout-2026-0001\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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))
}HttpResponse<String> response = Unirest.post("https://api-sandbox.circle.com/v1/accounts/withdrawals")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n \"destination\": {\n \"type\": \"wire\",\n \"id\": \"b8627ae8-732b-4d25-b947-1df8f4007a29\"\n },\n \"amount\": {\n \"amount\": \"3.14\",\n \"currency\": \"USD\"\n },\n \"riskSignals\": {\n \"ipAddress\": \"203.0.113.42\",\n \"sessionId\": \"8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c\",\n \"deviceId\": \"2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f\"\n },\n \"burnAll\": false,\n \"metadata\": {\n \"customerExternalRef\": \"payout-2026-0001\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.circle.com/v1/accounts/withdrawals")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n \"destination\": {\n \"type\": \"wire\",\n \"id\": \"b8627ae8-732b-4d25-b947-1df8f4007a29\"\n },\n \"amount\": {\n \"amount\": \"3.14\",\n \"currency\": \"USD\"\n },\n \"riskSignals\": {\n \"ipAddress\": \"203.0.113.42\",\n \"sessionId\": \"8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c\",\n \"deviceId\": \"2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f\"\n },\n \"burnAll\": false,\n \"metadata\": {\n \"customerExternalRef\": \"payout-2026-0001\"\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
"sourceAccountId": "<string>",
"source": {
"type": "account",
"id": "1000662322",
"description": "Operating account"
},
"destination": {
"type": "wire",
"id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
"name": "COMMERZBANK AG ****3000"
},
"transferType": "wire",
"amount": {
"amount": "3.14",
"currency": "USD"
},
"toAmount": {
"currency": "USD",
"amount": "3.14"
},
"fees": {
"amount": "3.14",
"currency": "USD"
},
"status": "pending",
"trackingRef": "<string>",
"errorCode": "insufficient_funds",
"externalRef": "b8627ae8-732b-4d25-b947-1df8f4007a29",
"riskEvaluation": {
"decision": "denied",
"reason": "3000"
},
"adjustments": {
"fxCredit": {
"amount": "3.14",
"currency": "USD"
},
"fxDebit": {
"amount": "3.14",
"currency": "USD"
}
},
"return": {
"id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
"payoutId": "abdb500d-4a59-457c-801f-2d418c8703ac",
"amount": {
"amount": "3.14",
"currency": "USD"
},
"fees": {
"amount": "3.14",
"currency": "USD"
},
"reason": "payout_returned",
"status": "pending",
"createDate": "2020-04-10T02:13:30.000Z",
"updateDate": "2020-04-10T02:13:30.000Z"
},
"description": "<string>",
"customerExternalRef": "<string>",
"burnAll": true,
"subAccountSweeps": [
{
"subAccountId": "<string>",
"amount": {
"amount": "3.14",
"currency": "USD"
},
"status": "pending"
}
],
"createDate": "2020-04-10T02:13:30.000Z",
"updateDate": "2020-04-10T02:13:30.000Z"
}
}{
"code": 2,
"message": "API parameter invalid."
}{
"code": 4,
"message": "Unauthorized."
}{
"code": 2,
"message": "API parameter invalid.",
"externalMessage": "The provided amount exceeds the maximum allowed.",
"errors": [
{
"error": "invalid_value",
"message": "The operation and assetType combination is invalid.",
"location": "assetType"
}
]
}{
"code": 2,
"message": "API parameter invalid.",
"externalMessage": "The provided amount exceeds the maximum allowed.",
"errors": [
{
"error": "invalid_value",
"message": "The operation and assetType combination is invalid.",
"location": "assetType"
}
]
}{
"code": 2,
"message": "API parameter invalid.",
"externalMessage": "The provided amount exceeds the maximum allowed.",
"errors": [
{
"error": "invalid_value",
"message": "The operation and assetType combination is invalid.",
"location": "assetType"
}
]
}{
"code": 2,
"message": "API parameter invalid.",
"externalMessage": "The provided amount exceeds the maximum allowed.",
"errors": [
{
"error": "invalid_value",
"message": "The operation and assetType combination is invalid.",
"location": "assetType"
}
]
}{
"code": 2,
"message": "API parameter invalid.",
"externalMessage": "The provided amount exceeds the maximum allowed.",
"errors": [
{
"error": "invalid_value",
"message": "The operation and assetType combination is invalid.",
"location": "assetType"
}
]
}{
"code": -1,
"message": "Something went wrong. errId: 1f0b0c455e40f753f07b4f0ae6abd4b4"
}{
"code": 2,
"message": "API parameter invalid.",
"externalMessage": "The provided amount exceeds the maximum allowed.",
"errors": [
{
"error": "invalid_value",
"message": "The operation and assetType combination is invalid.",
"location": "assetType"
}
]
}Create an account bank withdrawal
Create a bank withdrawal from an account. This converts a digital asset to fiat currency and sends it to the specified destination bank account.
POST
/
v1
/
accounts
/
withdrawals
Create an account bank withdrawal
curl --request POST \
--url https://api-sandbox.circle.com/v1/accounts/withdrawals \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
"destination": {
"type": "wire",
"id": "b8627ae8-732b-4d25-b947-1df8f4007a29"
},
"amount": {
"amount": "3.14",
"currency": "USD"
},
"riskSignals": {
"ipAddress": "203.0.113.42",
"sessionId": "8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c",
"deviceId": "2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f"
},
"burnAll": false,
"metadata": {
"customerExternalRef": "payout-2026-0001"
}
}
'import requests
url = "https://api-sandbox.circle.com/v1/accounts/withdrawals"
payload = {
"idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
"destination": {
"type": "wire",
"id": "b8627ae8-732b-4d25-b947-1df8f4007a29"
},
"amount": {
"amount": "3.14",
"currency": "USD"
},
"riskSignals": {
"ipAddress": "203.0.113.42",
"sessionId": "8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c",
"deviceId": "2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f"
},
"burnAll": False,
"metadata": { "customerExternalRef": "payout-2026-0001" }
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
idempotencyKey: 'ba943ff1-ca16-49b2-ba55-1057e70ca5c7',
destination: {type: 'wire', id: 'b8627ae8-732b-4d25-b947-1df8f4007a29'},
amount: {amount: '3.14', currency: 'USD'},
riskSignals: {
ipAddress: '203.0.113.42',
sessionId: '8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c',
deviceId: '2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f'
},
burnAll: false,
metadata: {customerExternalRef: 'payout-2026-0001'}
})
};
fetch('https://api-sandbox.circle.com/v1/accounts/withdrawals', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-sandbox.circle.com/v1/accounts/withdrawals",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'idempotencyKey' => 'ba943ff1-ca16-49b2-ba55-1057e70ca5c7',
'destination' => [
'type' => 'wire',
'id' => 'b8627ae8-732b-4d25-b947-1df8f4007a29'
],
'amount' => [
'amount' => '3.14',
'currency' => 'USD'
],
'riskSignals' => [
'ipAddress' => '203.0.113.42',
'sessionId' => '8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c',
'deviceId' => '2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f'
],
'burnAll' => false,
'metadata' => [
'customerExternalRef' => 'payout-2026-0001'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-sandbox.circle.com/v1/accounts/withdrawals"
payload := strings.NewReader("{\n \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n \"destination\": {\n \"type\": \"wire\",\n \"id\": \"b8627ae8-732b-4d25-b947-1df8f4007a29\"\n },\n \"amount\": {\n \"amount\": \"3.14\",\n \"currency\": \"USD\"\n },\n \"riskSignals\": {\n \"ipAddress\": \"203.0.113.42\",\n \"sessionId\": \"8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c\",\n \"deviceId\": \"2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f\"\n },\n \"burnAll\": false,\n \"metadata\": {\n \"customerExternalRef\": \"payout-2026-0001\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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))
}HttpResponse<String> response = Unirest.post("https://api-sandbox.circle.com/v1/accounts/withdrawals")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n \"destination\": {\n \"type\": \"wire\",\n \"id\": \"b8627ae8-732b-4d25-b947-1df8f4007a29\"\n },\n \"amount\": {\n \"amount\": \"3.14\",\n \"currency\": \"USD\"\n },\n \"riskSignals\": {\n \"ipAddress\": \"203.0.113.42\",\n \"sessionId\": \"8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c\",\n \"deviceId\": \"2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f\"\n },\n \"burnAll\": false,\n \"metadata\": {\n \"customerExternalRef\": \"payout-2026-0001\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.circle.com/v1/accounts/withdrawals")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n \"destination\": {\n \"type\": \"wire\",\n \"id\": \"b8627ae8-732b-4d25-b947-1df8f4007a29\"\n },\n \"amount\": {\n \"amount\": \"3.14\",\n \"currency\": \"USD\"\n },\n \"riskSignals\": {\n \"ipAddress\": \"203.0.113.42\",\n \"sessionId\": \"8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c\",\n \"deviceId\": \"2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f\"\n },\n \"burnAll\": false,\n \"metadata\": {\n \"customerExternalRef\": \"payout-2026-0001\"\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
"sourceAccountId": "<string>",
"source": {
"type": "account",
"id": "1000662322",
"description": "Operating account"
},
"destination": {
"type": "wire",
"id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
"name": "COMMERZBANK AG ****3000"
},
"transferType": "wire",
"amount": {
"amount": "3.14",
"currency": "USD"
},
"toAmount": {
"currency": "USD",
"amount": "3.14"
},
"fees": {
"amount": "3.14",
"currency": "USD"
},
"status": "pending",
"trackingRef": "<string>",
"errorCode": "insufficient_funds",
"externalRef": "b8627ae8-732b-4d25-b947-1df8f4007a29",
"riskEvaluation": {
"decision": "denied",
"reason": "3000"
},
"adjustments": {
"fxCredit": {
"amount": "3.14",
"currency": "USD"
},
"fxDebit": {
"amount": "3.14",
"currency": "USD"
}
},
"return": {
"id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
"payoutId": "abdb500d-4a59-457c-801f-2d418c8703ac",
"amount": {
"amount": "3.14",
"currency": "USD"
},
"fees": {
"amount": "3.14",
"currency": "USD"
},
"reason": "payout_returned",
"status": "pending",
"createDate": "2020-04-10T02:13:30.000Z",
"updateDate": "2020-04-10T02:13:30.000Z"
},
"description": "<string>",
"customerExternalRef": "<string>",
"burnAll": true,
"subAccountSweeps": [
{
"subAccountId": "<string>",
"amount": {
"amount": "3.14",
"currency": "USD"
},
"status": "pending"
}
],
"createDate": "2020-04-10T02:13:30.000Z",
"updateDate": "2020-04-10T02:13:30.000Z"
}
}{
"code": 2,
"message": "API parameter invalid."
}{
"code": 4,
"message": "Unauthorized."
}{
"code": 2,
"message": "API parameter invalid.",
"externalMessage": "The provided amount exceeds the maximum allowed.",
"errors": [
{
"error": "invalid_value",
"message": "The operation and assetType combination is invalid.",
"location": "assetType"
}
]
}{
"code": 2,
"message": "API parameter invalid.",
"externalMessage": "The provided amount exceeds the maximum allowed.",
"errors": [
{
"error": "invalid_value",
"message": "The operation and assetType combination is invalid.",
"location": "assetType"
}
]
}{
"code": 2,
"message": "API parameter invalid.",
"externalMessage": "The provided amount exceeds the maximum allowed.",
"errors": [
{
"error": "invalid_value",
"message": "The operation and assetType combination is invalid.",
"location": "assetType"
}
]
}{
"code": 2,
"message": "API parameter invalid.",
"externalMessage": "The provided amount exceeds the maximum allowed.",
"errors": [
{
"error": "invalid_value",
"message": "The operation and assetType combination is invalid.",
"location": "assetType"
}
]
}{
"code": 2,
"message": "API parameter invalid.",
"externalMessage": "The provided amount exceeds the maximum allowed.",
"errors": [
{
"error": "invalid_value",
"message": "The operation and assetType combination is invalid.",
"location": "assetType"
}
]
}{
"code": -1,
"message": "Something went wrong. errId: 1f0b0c455e40f753f07b4f0ae6abd4b4"
}{
"code": 2,
"message": "API parameter invalid.",
"externalMessage": "The provided amount exceeds the maximum allowed.",
"errors": [
{
"error": "invalid_value",
"message": "The operation and assetType combination is invalid.",
"location": "assetType"
}
]
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
The challengeId returned by POST /v1/accounts/passkeys/challenges. Required for end users under EEA/FR legal entities (PSD2 SCA). Omit for all other end users.
Example:
"b2c3d4e5-f6a7-8901-bc23-def456789012"
The signed assertion string returned by the DAA web SDK's sca.approve method. Required for end users under EEA/FR legal entities (PSD2 SCA). Pass the value through unchanged — do not base64-encode or re-serialize it.
Body
application/json
Universally unique identifier (UUID v4) idempotency key. This key is utilized to ensure exactly-once execution of mutating requests.
Example:
"ba943ff1-ca16-49b2-ba55-1057e70ca5c7"
The destination bank account.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Risk metadata for the end user initiating the request. All three fields must be present.
deviceId must be the identifier returned by checkDevice() in the @circle-fin/device-checks SDK. Circle resolves it against the device check that produced it, so an identifier you generate yourself does not resolve. When it does not resolve, the request is accepted and then declined: the endpoint returns 201, and the transaction later settles as failed with errorCode transfer_denied. See Collect device risk signals.
Show child attributes
Show child attributes
The source account for the withdrawal. The type must be account.
Show child attributes
Show child attributes
To be used when requesting currency exchange.
Show child attributes
Show child attributes
If true, withdraw the full balance of all sub-accounts and the main wallet in a single operation. The source must be the main wallet. When set, amount.amount is ignored and amount.currency must be USD.
Optional metadata for the withdrawal. Only supported for omnibus accounts.
Show child attributes
Show child attributes
Response
Successfully created a withdrawal.
Show child attributes
Show child attributes
Was this page helpful?