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",
"chain": "ETH",
"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",
"chain": "ETH",
"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',
chain: 'ETH',
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',
'chain' => 'ETH',
'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 \"chain\": \"ETH\",\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 \"chain\": \"ETH\",\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 \"chain\": \"ETH\",\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": "ETH",
"currency": "USD",
"description": "My USDC address at a cryptocurrency exchange",
"status": "active",
"verificationChallenge": {
"satoshiTest": {
"destinationAddress": "0x8f3b2c1a9d4e4f6ab7c81e2d3f4a5b6c7d8e9f01",
"paymentId": "1234567890",
"amount": {
"amount": "0.42",
"currency": "USD"
},
"status": "active"
},
"messageSignature": {
"message": "example.circle.com wants you to sign in with your Ethereum account:\n0x8f3b2c1a9d4e4f6ab7c81e2d3f4a5b6c7d8e9f01\n\nVerify ownership of this address.\n\nURI: https://example.circle.com\nVersion: 1\nChain ID: 1\nNonce: 32891756\nIssued At: 2026-10-22T17:00:00Z",
"status": "active",
"expiresAt": "2026-10-23T17:00:00Z"
}
}
}
}{
"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 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",
"chain": "ETH",
"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",
"chain": "ETH",
"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',
chain: 'ETH',
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',
'chain' => 'ETH',
'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 \"chain\": \"ETH\",\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 \"chain\": \"ETH\",\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 \"chain\": \"ETH\",\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": "ETH",
"currency": "USD",
"description": "My USDC address at a cryptocurrency exchange",
"status": "active",
"verificationChallenge": {
"satoshiTest": {
"destinationAddress": "0x8f3b2c1a9d4e4f6ab7c81e2d3f4a5b6c7d8e9f01",
"paymentId": "1234567890",
"amount": {
"amount": "0.42",
"currency": "USD"
},
"status": "active"
},
"messageSignature": {
"message": "example.circle.com wants you to sign in with your Ethereum account:\n0x8f3b2c1a9d4e4f6ab7c81e2d3f4a5b6c7d8e9f01\n\nVerify ownership of this address.\n\nURI: https://example.circle.com\nVersion: 1\nChain ID: 1\nNonce: 32891756\nIssued At: 2026-10-22T17:00:00Z",
"status": "active",
"expiresAt": "2026-10-23T17:00:00Z"
}
}
}
}{
"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
Headers
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.
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
Was this page helpful?