Create a crypto payout

curl --request POST \
  --url https://api-sandbox.circle.com/v1/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
  "source": {
    "type": "wallet",
    "id": "1000662322"
  },
  "destination": {
    "type": "address_book",
    "id": "b8627ae8-732b-4d25-b947-1df8f4007a29"
  },
  "amount": {
    "amount": "3.14"
  },
  "riskSignals": {
    "ipAddress": "203.0.113.42",
    "sessionId": "8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c",
    "deviceId": "2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f"
  },
  "purposeOfTransfer": "PMT001",
  "metadata": {
    "customerExternalRef": "INV-2024-001234"
  }
}
'

import requests

url = "https://api-sandbox.circle.com/v1/payouts"

payload = {
    "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
    "source": {
        "type": "wallet",
        "id": "1000662322"
    },
    "destination": {
        "type": "address_book",
        "id": "b8627ae8-732b-4d25-b947-1df8f4007a29"
    },
    "amount": { "amount": "3.14" },
    "riskSignals": {
        "ipAddress": "203.0.113.42",
        "sessionId": "8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c",
        "deviceId": "2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f"
    },
    "purposeOfTransfer": "PMT001",
    "metadata": { "customerExternalRef": "INV-2024-001234" }
}
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',
    source: {type: 'wallet', id: '1000662322'},
    destination: {type: 'address_book', id: 'b8627ae8-732b-4d25-b947-1df8f4007a29'},
    amount: {amount: '3.14'},
    riskSignals: {
      ipAddress: '203.0.113.42',
      sessionId: '8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c',
      deviceId: '2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f'
    },
    purposeOfTransfer: 'PMT001',
    metadata: {customerExternalRef: 'INV-2024-001234'}
  })
};

fetch('https://api-sandbox.circle.com/v1/payouts', 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/payouts",
  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',
    'source' => [
        'type' => 'wallet',
        'id' => '1000662322'
    ],
    'destination' => [
        'type' => 'address_book',
        'id' => 'b8627ae8-732b-4d25-b947-1df8f4007a29'
    ],
    'amount' => [
        'amount' => '3.14'
    ],
    'riskSignals' => [
        'ipAddress' => '203.0.113.42',
        'sessionId' => '8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c',
        'deviceId' => '2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f'
    ],
    'purposeOfTransfer' => 'PMT001',
    'metadata' => [
        'customerExternalRef' => 'INV-2024-001234'
    ]
  ]),
  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/payouts"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"source\": {\n    \"type\": \"wallet\",\n    \"id\": \"1000662322\"\n  },\n  \"destination\": {\n    \"type\": \"address_book\",\n    \"id\": \"b8627ae8-732b-4d25-b947-1df8f4007a29\"\n  },\n  \"amount\": {\n    \"amount\": \"3.14\"\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  \"purposeOfTransfer\": \"PMT001\",\n  \"metadata\": {\n    \"customerExternalRef\": \"INV-2024-001234\"\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/payouts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"source\": {\n    \"type\": \"wallet\",\n    \"id\": \"1000662322\"\n  },\n  \"destination\": {\n    \"type\": \"address_book\",\n    \"id\": \"b8627ae8-732b-4d25-b947-1df8f4007a29\"\n  },\n  \"amount\": {\n    \"amount\": \"3.14\"\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  \"purposeOfTransfer\": \"PMT001\",\n  \"metadata\": {\n    \"customerExternalRef\": \"INV-2024-001234\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.circle.com/v1/payouts")

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  \"source\": {\n    \"type\": \"wallet\",\n    \"id\": \"1000662322\"\n  },\n  \"destination\": {\n    \"type\": \"address_book\",\n    \"id\": \"b8627ae8-732b-4d25-b947-1df8f4007a29\"\n  },\n  \"amount\": {\n    \"amount\": \"3.14\"\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  \"purposeOfTransfer\": \"PMT001\",\n  \"metadata\": {\n    \"customerExternalRef\": \"INV-2024-001234\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
    "sourceWalletId": "1000662322",
    "destination": {
      "type": "address_book",
      "id": "b8627ae8-732b-4d25-b947-1df8f4007a29"
    },
    "amount": {
      "amount": "3.14",
      "currency": "USD"
    },
    "toAmount": {
      "amount": "3.14",
      "currency": "USD"
    },
    "fees": {
      "amount": "3.14",
      "currency": "USD"
    },
    "networkFees": {
      "amount": "3.14",
      "currency": "USD"
    },
    "purposeOfTransfer": "PMT001",
    "customerExternalRef": "INV-2024-001234",
    "status": "pending",
    "errorCode": "insufficient_funds",
    "riskEvaluation": {
      "decision": "denied",
      "reason": "3000"
    },
    "externalRef": "0x7351585460bd657f320b9afa02a52c26d89272d0d10cc29913eb8b28e64fd906",
    "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": 3,
  "message": "Missing permission."
}

{
  "code": -1,
  "message": "Something went wrong. errId: 1f0b0c455e40f753f07b4f0ae6abd4b4"
}

Create a crypto payout

Create a stablecoin payout to a recipient address.

Digital Asset Accounts: crypto payouts are available only for custody accounts (purpose: custody) and are for third-party payouts only. They are not supported when the distributor or the end user is under the Circle FR (CIRCLE_FR) or Circle SG (CIRCLE_SG) legal entity. source is required: set source.id to the accountId of the end user’s custody account. A master wallet source is rejected with 403. The destination must be an address book recipient created with clientEntityId set to the end user who owns that account.

The following table includes the supported pairs of amount.currency and toAmount.currency:

amount.currency	toAmount.currency
USD	USD
EUR	EUR

For Circle Inc (CIRCLE_INC) customers using Managed Payments, purposeOfTransfer is required and must use a payment reason code from Crypto Payouts payment reason codes. Invalid or missing values can return error code 5020.

POST

payouts

Create a crypto payout

curl --request POST \
  --url https://api-sandbox.circle.com/v1/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
  "source": {
    "type": "wallet",
    "id": "1000662322"
  },
  "destination": {
    "type": "address_book",
    "id": "b8627ae8-732b-4d25-b947-1df8f4007a29"
  },
  "amount": {
    "amount": "3.14"
  },
  "riskSignals": {
    "ipAddress": "203.0.113.42",
    "sessionId": "8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c",
    "deviceId": "2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f"
  },
  "purposeOfTransfer": "PMT001",
  "metadata": {
    "customerExternalRef": "INV-2024-001234"
  }
}
'

import requests

url = "https://api-sandbox.circle.com/v1/payouts"

payload = {
    "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
    "source": {
        "type": "wallet",
        "id": "1000662322"
    },
    "destination": {
        "type": "address_book",
        "id": "b8627ae8-732b-4d25-b947-1df8f4007a29"
    },
    "amount": { "amount": "3.14" },
    "riskSignals": {
        "ipAddress": "203.0.113.42",
        "sessionId": "8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c",
        "deviceId": "2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f"
    },
    "purposeOfTransfer": "PMT001",
    "metadata": { "customerExternalRef": "INV-2024-001234" }
}
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',
    source: {type: 'wallet', id: '1000662322'},
    destination: {type: 'address_book', id: 'b8627ae8-732b-4d25-b947-1df8f4007a29'},
    amount: {amount: '3.14'},
    riskSignals: {
      ipAddress: '203.0.113.42',
      sessionId: '8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c',
      deviceId: '2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f'
    },
    purposeOfTransfer: 'PMT001',
    metadata: {customerExternalRef: 'INV-2024-001234'}
  })
};

fetch('https://api-sandbox.circle.com/v1/payouts', 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/payouts",
  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',
    'source' => [
        'type' => 'wallet',
        'id' => '1000662322'
    ],
    'destination' => [
        'type' => 'address_book',
        'id' => 'b8627ae8-732b-4d25-b947-1df8f4007a29'
    ],
    'amount' => [
        'amount' => '3.14'
    ],
    'riskSignals' => [
        'ipAddress' => '203.0.113.42',
        'sessionId' => '8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c',
        'deviceId' => '2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f'
    ],
    'purposeOfTransfer' => 'PMT001',
    'metadata' => [
        'customerExternalRef' => 'INV-2024-001234'
    ]
  ]),
  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/payouts"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"source\": {\n    \"type\": \"wallet\",\n    \"id\": \"1000662322\"\n  },\n  \"destination\": {\n    \"type\": \"address_book\",\n    \"id\": \"b8627ae8-732b-4d25-b947-1df8f4007a29\"\n  },\n  \"amount\": {\n    \"amount\": \"3.14\"\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  \"purposeOfTransfer\": \"PMT001\",\n  \"metadata\": {\n    \"customerExternalRef\": \"INV-2024-001234\"\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/payouts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"source\": {\n    \"type\": \"wallet\",\n    \"id\": \"1000662322\"\n  },\n  \"destination\": {\n    \"type\": \"address_book\",\n    \"id\": \"b8627ae8-732b-4d25-b947-1df8f4007a29\"\n  },\n  \"amount\": {\n    \"amount\": \"3.14\"\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  \"purposeOfTransfer\": \"PMT001\",\n  \"metadata\": {\n    \"customerExternalRef\": \"INV-2024-001234\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.circle.com/v1/payouts")

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  \"source\": {\n    \"type\": \"wallet\",\n    \"id\": \"1000662322\"\n  },\n  \"destination\": {\n    \"type\": \"address_book\",\n    \"id\": \"b8627ae8-732b-4d25-b947-1df8f4007a29\"\n  },\n  \"amount\": {\n    \"amount\": \"3.14\"\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  \"purposeOfTransfer\": \"PMT001\",\n  \"metadata\": {\n    \"customerExternalRef\": \"INV-2024-001234\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
    "sourceWalletId": "1000662322",
    "destination": {
      "type": "address_book",
      "id": "b8627ae8-732b-4d25-b947-1df8f4007a29"
    },
    "amount": {
      "amount": "3.14",
      "currency": "USD"
    },
    "toAmount": {
      "amount": "3.14",
      "currency": "USD"
    },
    "fees": {
      "amount": "3.14",
      "currency": "USD"
    },
    "networkFees": {
      "amount": "3.14",
      "currency": "USD"
    },
    "purposeOfTransfer": "PMT001",
    "customerExternalRef": "INV-2024-001234",
    "status": "pending",
    "errorCode": "insufficient_funds",
    "riskEvaluation": {
      "decision": "denied",
      "reason": "3000"
    },
    "externalRef": "0x7351585460bd657f320b9afa02a52c26d89272d0d10cc29913eb8b28e64fd906",
    "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": 3,
  "message": "Missing permission."
}

{
  "code": -1,
  "message": "Something went wrong. errId: 1f0b0c455e40f753f07b4f0ae6abd4b4"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

idempotencyKey

string<uuid>

required

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"

source

object

required

The source wallet to fund the payout. Required for Digital Asset Accounts: set id to the accountId of the custody account to pay out from.

Show child attributes

destination

object

required

The payout destination: an address book recipient created with POST /v1/addressBook/recipients. The recipient must be in active status and created with clientEntityId set to the end user who owns the payout's source account.

Show child attributes

amount

object

required

Show child attributes

riskSignals

object

required

Risk metadata for the end user initiating the payout. For payouts, a risk denial fails the payout with errorCode transaction_denied.

Show child attributes

toAmount

object

The destination currency. Defaults to amount.currency.

Show child attributes

purposeOfTransfer

enum<string>

Required for Circle Inc (CIRCLE_INC) customers using Managed Payments, based on the source account's legal entity.

Available options:

PMT000,

PMT001,

PMT002,

PMT003,

PMT004,

PMT005,

PMT007,

PMT008,

PMT009,

PMT010,

PMT011,

PMT012,

PMT013,

PMT014,

PMT015,

PMT016,

PMT017,

PMT018,

PMT019,

PMT020,

PMT021,

PMT022,

PMT023,

PMT024,

PMT025,

PMT026,

PMT027,

PMT028,

PMT029,

PMT030

Example:

"PMT001"

metadata

object

Additional properties related to the crypto payout.

Show child attributes

Response

Successfully created a payout.

data

object

A crypto payout.

Show child attributes