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": {
      "destinationAddress": "0x8f3b2c1a9d4e4f6ab7c81e2d3f4a5b6c7d8e9f01",
      "paymentId": "<string>",
      "amount": {
        "amount": "0.42",
        "currency": "USD"
      },
      "status": "active"
    }
  }
}

{
  "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": -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"
    }
  ]
}

POST

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": {
      "destinationAddress": "0x8f3b2c1a9d4e4f6ab7c81e2d3f4a5b6c7d8e9f01",
      "paymentId": "<string>",
      "amount": {
        "amount": "0.42",
        "currency": "USD"
      },
      "status": "active"
    }
  }
}

{
  "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": -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

Authorization

string

header

required

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

Headers

X-Sca-Challenge-Id

string<uuid>

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"

X-Sca-Assertion

string

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.

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.

Example:

"0x8381470ED67C3802402dbbFa0058E8871F017A6F"

chain

enum<string>

required

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

Example:

"ETH"

description

string

required

An identifier or sentence that describes the recipient.

Example:

"My USDC address at a cryptocurrency exchange"

riskSignals

object

required

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

clientEntityId

string<uuid>

Identifier of the client entity. Required for 3rd-party flows.

Example:

"a3f1b2c4-d5e6-7890-abcd-ef1234567890"

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

ownership

object

Ownership and custody of the wallet, used for Travel Rule and compliance.

Show child attributes

Response

Successfully added a recipient address.

data

object

Show child attributes