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
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
The challengeId returned by POST /v1/accounts/passkeys/challenges. Required for end users under EEA/FR legal entities (PSD2 SCA). Omit for all other end users.
Example:
"b2c3d4e5-f6a7-8901-bc23-def456789012"
The signed assertion string returned by the DAA web SDK's sca.approve method. Required for end users under EEA/FR legal entities (PSD2 SCA). Pass the value through unchanged — do not base64-encode or re-serialize it.
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, 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 Example:
"ETH"
An identifier or sentence that describes the recipient.
Example:
"My USDC address at a cryptocurrency exchange"
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
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 Ownership and custody of the wallet, used for Travel Rule and compliance.
Show child attributes
Show child attributes
Response
Successfully added a recipient address.
Show child attributes
Show child attributes
Was this page helpful?