Skip to main content
POST
/
v1
/
addressBook
/
recipients
Create a recipient
curl --request POST \
  --url https://api-sandbox.circle.com/v1/addressBook/recipients \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
  "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
  "metadata": {
    "nickname": "sample nickname",
    "email": "satoshi@circle.com",
    "bns": "sample.circle"
  },
  "addressTag": "123456789",
  "identity": {
    "firstName": "Ada",
    "lastName": "Lovelace",
    "businessName": "Example Corp"
  }
}
'
import requests

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

payload = {
    "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
    "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
    "metadata": {
        "nickname": "sample nickname",
        "email": "satoshi@circle.com",
        "bns": "sample.circle"
    },
    "addressTag": "123456789",
    "identity": {
        "firstName": "Ada",
        "lastName": "Lovelace",
        "businessName": "Example Corp"
    }
}
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',
    metadata: {nickname: 'sample nickname', email: 'satoshi@circle.com', bns: 'sample.circle'},
    addressTag: '123456789',
    identity: {firstName: 'Ada', lastName: 'Lovelace', businessName: 'Example Corp'}
  })
};

fetch('https://api-sandbox.circle.com/v1/addressBook/recipients', 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/addressBook/recipients",
  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',
    'metadata' => [
        'nickname' => 'sample nickname',
        'email' => 'satoshi@circle.com',
        'bns' => 'sample.circle'
    ],
    'addressTag' => '123456789',
    'identity' => [
        'firstName' => 'Ada',
        'lastName' => 'Lovelace',
        'businessName' => 'Example Corp'
    ]
  ]),
  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/addressBook/recipients"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"address\": \"0x8381470ED67C3802402dbbFa0058E8871F017A6F\",\n  \"metadata\": {\n    \"nickname\": \"sample nickname\",\n    \"email\": \"satoshi@circle.com\",\n    \"bns\": \"sample.circle\"\n  },\n  \"addressTag\": \"123456789\",\n  \"identity\": {\n    \"firstName\": \"Ada\",\n    \"lastName\": \"Lovelace\",\n    \"businessName\": \"Example Corp\"\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/addressBook/recipients")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"address\": \"0x8381470ED67C3802402dbbFa0058E8871F017A6F\",\n  \"metadata\": {\n    \"nickname\": \"sample nickname\",\n    \"email\": \"satoshi@circle.com\",\n    \"bns\": \"sample.circle\"\n  },\n  \"addressTag\": \"123456789\",\n  \"identity\": {\n    \"firstName\": \"Ada\",\n    \"lastName\": \"Lovelace\",\n    \"businessName\": \"Example Corp\"\n  }\n}")
  .asString();
require 'uri'
require 'net/http'

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

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  \"metadata\": {\n    \"nickname\": \"sample nickname\",\n    \"email\": \"satoshi@circle.com\",\n    \"bns\": \"sample.circle\"\n  },\n  \"addressTag\": \"123456789\",\n  \"identity\": {\n    \"firstName\": \"Ada\",\n    \"lastName\": \"Lovelace\",\n    \"businessName\": \"Example Corp\"\n  }\n}"

response = http.request(request)
puts response.read_body
{
  "data": {
    "id": "8755d0ea-14f9-4259-b092-de23c14b6568",
    "chain": "ETH",
    "address": "0x45bfcf1a6289a0b77b4d3f7d12005a05949fd8c3",
    "metadata": {
      "nickname": "sample nickname",
      "email": "satoshi@circle.com",
      "bns": "sample.circle"
    },
    "status": "pending",
    "identity": {
      "type": "individual",
      "firstName": "Ada",
      "lastName": "Lovelace"
    },
    "createDate": "2022-07-21T20:13:35.578678Z",
    "updateDate": "2022-07-21T20:19:24.859052Z"
  }
}

Authorizations

​
Authorization
string
header
required

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

Body

application/json

For Circle entities other than CIRCLE_SG.

​
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"

​
chain
enum<string>
required

Blockchain network code for the recipient address (address book scope).

Available options:
ALGO,
APTOS,
ARB,
AVAX,
BASE,
CELO,
ETH,
HBAR,
NEAR,
NOBLE,
OP,
PAH,
POLY,
SOL,
SUI,
UNI,
XLM,
XRP,
ZKS
​
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"

​
metadata
object
required

Recipient metadata. For Singapore (CIRCLE_SG) customers creating a self-hosted (ownership.custody.type = self_hosted) entry, email is required (validation error 2038).

​
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"

​
identity
object

Beneficiary identity for the address book entry.

When type is individual, include firstName and lastName. When type is business, include businessName.

Beneficiary Personally Identifiable Information (PII) required for MAS Travel Rule compliance on self-hosted wallet payouts is carried in the nested individual and business objects. These two child objects are mutually exclusive — at most one may be provided, and it must match type. For Singapore (CIRCLE_SG) customers creating a self-hosted (ownership.custody.type = self_hosted) entry the child object matching type is required; for non-regulated jurisdictions it is accepted if provided but not required. Name fields stay at this level and are not duplicated inside the child objects.

Related validation error codes include 2024 (identity missing), 2031–2034, 2036 (identity cannot be updated via PATCH), and the PII-missing errors ADDRESS_BOOK_INDIVIDUAL_PII_MISSING and ADDRESS_BOOK_BUSINESS_PII_MISSING.

Response

Successfully created an address book recipient.

​
data
General customers · object

For Circle entities other than CIRCLE_SG.