Create a recipient address

curl --request POST \
  --url https://api-sandbox.circle.com/v1/businessAccount/wallets/addresses/recipient \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
  "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
  "description": "My USDC address at a cryptocurrency exchange",
  "addressTag": "123456789"
}
'

import requests

url = "https://api-sandbox.circle.com/v1/businessAccount/wallets/addresses/recipient"

payload = {
    "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
    "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
    "description": "My USDC address at a cryptocurrency exchange",
    "addressTag": "123456789"
}
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',
    address: '0x8381470ED67C3802402dbbFa0058E8871F017A6F',
    description: 'My USDC address at a cryptocurrency exchange',
    addressTag: '123456789'
  })
};

fetch('https://api-sandbox.circle.com/v1/businessAccount/wallets/addresses/recipient', 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/businessAccount/wallets/addresses/recipient",
  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',
    'address' => '0x8381470ED67C3802402dbbFa0058E8871F017A6F',
    'description' => 'My USDC address at a cryptocurrency exchange',
    'addressTag' => '123456789'
  ]),
  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/businessAccount/wallets/addresses/recipient"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"address\": \"0x8381470ED67C3802402dbbFa0058E8871F017A6F\",\n  \"description\": \"My USDC address at a cryptocurrency exchange\",\n  \"addressTag\": \"123456789\"\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/businessAccount/wallets/addresses/recipient")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"address\": \"0x8381470ED67C3802402dbbFa0058E8871F017A6F\",\n  \"description\": \"My USDC address at a cryptocurrency exchange\",\n  \"addressTag\": \"123456789\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.circle.com/v1/businessAccount/wallets/addresses/recipient")

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  \"address\": \"0x8381470ED67C3802402dbbFa0058E8871F017A6F\",\n  \"description\": \"My USDC address at a cryptocurrency exchange\",\n  \"addressTag\": \"123456789\"\n}"

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

{
  "data": {
    "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
    "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
    "addressTag": "123456789",
    "chain": "ALGO",
    "currency": "USD",
    "description": "My USDC address at a cryptocurrency exchange",
    "status": "active"
  }
}

{
  "code": 400,
  "message": "Bad request."
}

{
  "code": 401,
  "message": "Malformed authorization."
}

Create a recipient address

Stores an external blockchain address. Once added, the recipient address must be verified to ensure that you know and trust each new address.

cirBTC recipients: Recipient addresses for cirBTC flows are registered with one of these chain and currency pairs:

chain=ETH or chain=ARC with currency=CIRBTC for onchain cirBTC transfers.
chain=BTC with currency=BTC for native Bitcoin recipients. To redeem cirBTC to native Bitcoin, create a transfer with amount.currency=CIRBTC to a recipient of this form; Circle will burn the cirBTC and release the equivalent amount of native Bitcoin (1:1) to the Bitcoin address.

For France customers:

Circle Mint France customers must verify all transfer recipients using the UI in the Circle Console, as transfers from unverified addresses will be held in pending status. Please see Help Center articles below for details:

POST

businessAccount

wallets

addresses

recipient

Create a recipient address

curl --request POST \
  --url https://api-sandbox.circle.com/v1/businessAccount/wallets/addresses/recipient \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
  "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
  "description": "My USDC address at a cryptocurrency exchange",
  "addressTag": "123456789"
}
'

import requests

url = "https://api-sandbox.circle.com/v1/businessAccount/wallets/addresses/recipient"

payload = {
    "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
    "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
    "description": "My USDC address at a cryptocurrency exchange",
    "addressTag": "123456789"
}
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',
    address: '0x8381470ED67C3802402dbbFa0058E8871F017A6F',
    description: 'My USDC address at a cryptocurrency exchange',
    addressTag: '123456789'
  })
};

fetch('https://api-sandbox.circle.com/v1/businessAccount/wallets/addresses/recipient', 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/businessAccount/wallets/addresses/recipient",
  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',
    'address' => '0x8381470ED67C3802402dbbFa0058E8871F017A6F',
    'description' => 'My USDC address at a cryptocurrency exchange',
    'addressTag' => '123456789'
  ]),
  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/businessAccount/wallets/addresses/recipient"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"address\": \"0x8381470ED67C3802402dbbFa0058E8871F017A6F\",\n  \"description\": \"My USDC address at a cryptocurrency exchange\",\n  \"addressTag\": \"123456789\"\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/businessAccount/wallets/addresses/recipient")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"address\": \"0x8381470ED67C3802402dbbFa0058E8871F017A6F\",\n  \"description\": \"My USDC address at a cryptocurrency exchange\",\n  \"addressTag\": \"123456789\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.circle.com/v1/businessAccount/wallets/addresses/recipient")

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  \"address\": \"0x8381470ED67C3802402dbbFa0058E8871F017A6F\",\n  \"description\": \"My USDC address at a cryptocurrency exchange\",\n  \"addressTag\": \"123456789\"\n}"

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

{
  "data": {
    "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
    "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
    "addressTag": "123456789",
    "chain": "ALGO",
    "currency": "USD",
    "description": "My USDC address at a cryptocurrency exchange",
    "status": "active"
  }
}

{
  "code": 400,
  "message": "Bad request."
}

{
  "code": 401,
  "message": "Malformed authorization."
}

Authorizations

Authorization

string

header

required

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

Body

application/json

Adds a recipient address. The currency parameter will default to USD for all chains except for BTC where it defaults to BTC.

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"

address

string

required

An alphanumeric string representing a blockchain address. Formatting varies by blockchain. Be sure to preserve the exact formatting and capitalization of the address.
Important: For Ripple (XRP) addresses, only the classic address format is supported (for example, rPEPPER7kfTD9w2To4CQk6UCfuHM9c6GDY).
The x-address format is NOT supported currently (for example, XV5sbjUmgPpvXv4ixFWZ5ptAYZ6PD2q1qM6owqNbug8W6KV).

Example:

"0x8381470ED67C3802402dbbFa0058E8871F017A6F"

chain

enum<string>

required

A blockchain that a given currency is available on.

Note: Arc (ARC) is only available in the sandbox environment (api-sandbox.circle.com).

Available options:

ALGO,

APTOS,

ARB,

ARC,

AVAX,

BASE,

BTC,

CELO,

CODEX,

ETH,

HBAR,

HYPEREVM,

INK,

LINEA,

NEAR,

NOBLE,

OP,

PLUME,

PAH,

POLY,

SEI,

SOL,

SONIC,

SUI,

UNI,

WORLDCHAIN,

XDC,

XLM,

XRP,

ZKS,

ZKSYNC

description

string

required

An identifier or sentence that describes the recipient.

Example:

"My USDC address at a cryptocurrency exchange"

addressTag

string | null

The secondary identifier for a blockchain address. An example of this is the memo field on the Stellar network, which can be text, id, or hash format.

Example:

"123456789"

currency

enum<string> | null

A currency associated with a balance or address.

Available options:

USD,

EUR,

BTC,

ETH,

CIRBTC

Response

Successfully added a recipient address.

data

object

Show child attributes

List all recipient addresses

Delete a recipient address

⌘I