Create a recipient address
curl --request POST \
--url https://api-sandbox.circle.com/v1/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",
"riskSignals": {
"ipAddress": "203.0.113.42",
"sessionId": "8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c",
"deviceId": "2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f"
},
"clientEntityId": "a3f1b2c4-d5e6-7890-abcd-ef1234567890",
"addressTag": "123456789"
}
'import requests
url = "https://api-sandbox.circle.com/v1/addresses/recipient"
payload = {
"idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
"address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
"description": "My USDC address at a cryptocurrency exchange",
"riskSignals": {
"ipAddress": "203.0.113.42",
"sessionId": "8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c",
"deviceId": "2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f"
},
"clientEntityId": "a3f1b2c4-d5e6-7890-abcd-ef1234567890",
"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',
riskSignals: {
ipAddress: '203.0.113.42',
sessionId: '8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c',
deviceId: '2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f'
},
clientEntityId: 'a3f1b2c4-d5e6-7890-abcd-ef1234567890',
addressTag: '123456789'
})
};
fetch('https://api-sandbox.circle.com/v1/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/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',
'riskSignals' => [
'ipAddress' => '203.0.113.42',
'sessionId' => '8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c',
'deviceId' => '2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f'
],
'clientEntityId' => 'a3f1b2c4-d5e6-7890-abcd-ef1234567890',
'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/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 \"riskSignals\": {\n \"ipAddress\": \"203.0.113.42\",\n \"sessionId\": \"8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c\",\n \"deviceId\": \"2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f\"\n },\n \"clientEntityId\": \"a3f1b2c4-d5e6-7890-abcd-ef1234567890\",\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/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 \"riskSignals\": {\n \"ipAddress\": \"203.0.113.42\",\n \"sessionId\": \"8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c\",\n \"deviceId\": \"2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f\"\n },\n \"clientEntityId\": \"a3f1b2c4-d5e6-7890-abcd-ef1234567890\",\n \"addressTag\": \"123456789\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.circle.com/v1/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 \"riskSignals\": {\n \"ipAddress\": \"203.0.113.42\",\n \"sessionId\": \"8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c\",\n \"deviceId\": \"2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f\"\n },\n \"clientEntityId\": \"a3f1b2c4-d5e6-7890-abcd-ef1234567890\",\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": 2,
"message": "API parameter invalid."
}{
"code": 4,
"message": "Unauthorized."
}{
"code": -1,
"message": "Something went wrong. errId: 1f0b0c455e40f753f07b4f0ae6abd4b4"
}Create a recipient address
Stores an external blockchain address.
POST
/
v1
/
addresses
/
recipient
Create a recipient address
curl --request POST \
--url https://api-sandbox.circle.com/v1/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",
"riskSignals": {
"ipAddress": "203.0.113.42",
"sessionId": "8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c",
"deviceId": "2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f"
},
"clientEntityId": "a3f1b2c4-d5e6-7890-abcd-ef1234567890",
"addressTag": "123456789"
}
'import requests
url = "https://api-sandbox.circle.com/v1/addresses/recipient"
payload = {
"idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
"address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
"description": "My USDC address at a cryptocurrency exchange",
"riskSignals": {
"ipAddress": "203.0.113.42",
"sessionId": "8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c",
"deviceId": "2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f"
},
"clientEntityId": "a3f1b2c4-d5e6-7890-abcd-ef1234567890",
"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',
riskSignals: {
ipAddress: '203.0.113.42',
sessionId: '8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c',
deviceId: '2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f'
},
clientEntityId: 'a3f1b2c4-d5e6-7890-abcd-ef1234567890',
addressTag: '123456789'
})
};
fetch('https://api-sandbox.circle.com/v1/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/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',
'riskSignals' => [
'ipAddress' => '203.0.113.42',
'sessionId' => '8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c',
'deviceId' => '2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f'
],
'clientEntityId' => 'a3f1b2c4-d5e6-7890-abcd-ef1234567890',
'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/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 \"riskSignals\": {\n \"ipAddress\": \"203.0.113.42\",\n \"sessionId\": \"8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c\",\n \"deviceId\": \"2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f\"\n },\n \"clientEntityId\": \"a3f1b2c4-d5e6-7890-abcd-ef1234567890\",\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/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 \"riskSignals\": {\n \"ipAddress\": \"203.0.113.42\",\n \"sessionId\": \"8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c\",\n \"deviceId\": \"2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f\"\n },\n \"clientEntityId\": \"a3f1b2c4-d5e6-7890-abcd-ef1234567890\",\n \"addressTag\": \"123456789\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.circle.com/v1/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 \"riskSignals\": {\n \"ipAddress\": \"203.0.113.42\",\n \"sessionId\": \"8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c\",\n \"deviceId\": \"2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f\"\n },\n \"clientEntityId\": \"a3f1b2c4-d5e6-7890-abcd-ef1234567890\",\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": 2,
"message": "API parameter invalid."
}{
"code": 4,
"message": "Unauthorized."
}{
"code": -1,
"message": "Something went wrong. errId: 1f0b0c455e40f753f07b4f0ae6abd4b4"
}Authorizations
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.
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"
An alphanumeric string representing a blockchain address. Formatting varies by blockchain. Be sure to preserve the exact formatting and capitalization of the address.
Example:
"0x8381470ED67C3802402dbbFa0058E8871F017A6F"
A blockchain that a given currency is available on.
Available options:
ALGO, APTOS, ARB, 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 An identifier or sentence that describes the recipient.
Example:
"My USDC address at a cryptocurrency exchange"
Client-collected risk metadata for the end user initiating the request. All three fields must be present.
Show child attributes
Show child attributes
Identifier of the client entity. Required for 3rd-party flows.
Example:
"a3f1b2c4-d5e6-7890-abcd-ef1234567890"
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"
A currency associated with a balance or address.
Available options:
USD, EUR Response
Successfully added a recipient address.
Show child attributes
Show child attributes
Was this page helpful?