Create wallets

curl --request POST \
  --url https://api.circle.com/v1/w3s/user/wallets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-User-Token: <x-user-token>' \
  --data '
{
  "idempotencyKey": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "blockchains": [
    "MATIC-AMOY"
  ],
  "metadata": [
    {
      "name": "<string>",
      "refId": "customer_12345"
    }
  ],
  "scaConfiguration": {
    "scaCore": "circle_6900_singleowner_v4"
  }
}
'

import requests

url = "https://api.circle.com/v1/w3s/user/wallets"

payload = {
    "idempotencyKey": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
    "blockchains": ["MATIC-AMOY"],
    "metadata": [
        {
            "name": "<string>",
            "refId": "customer_12345"
        }
    ],
    "scaConfiguration": { "scaCore": "circle_6900_singleowner_v4" }
}
headers = {
    "X-User-Token": "<x-user-token>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-User-Token': '<x-user-token>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    idempotencyKey: 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11',
    blockchains: ['MATIC-AMOY'],
    metadata: [{name: '<string>', refId: 'customer_12345'}],
    scaConfiguration: {scaCore: 'circle_6900_singleowner_v4'}
  })
};

fetch('https://api.circle.com/v1/w3s/user/wallets', 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.circle.com/v1/w3s/user/wallets",
  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' => 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11',
    'blockchains' => [
        'MATIC-AMOY'
    ],
    'metadata' => [
        [
                'name' => '<string>',
                'refId' => 'customer_12345'
        ]
    ],
    'scaConfiguration' => [
        'scaCore' => 'circle_6900_singleowner_v4'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-User-Token: <x-user-token>"
  ],
]);

$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.circle.com/v1/w3s/user/wallets"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11\",\n  \"blockchains\": [\n    \"MATIC-AMOY\"\n  ],\n  \"metadata\": [\n    {\n      \"name\": \"<string>\",\n      \"refId\": \"customer_12345\"\n    }\n  ],\n  \"scaConfiguration\": {\n    \"scaCore\": \"circle_6900_singleowner_v4\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-User-Token", "<x-user-token>")
	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.circle.com/v1/w3s/user/wallets")
  .header("X-User-Token", "<x-user-token>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11\",\n  \"blockchains\": [\n    \"MATIC-AMOY\"\n  ],\n  \"metadata\": [\n    {\n      \"name\": \"<string>\",\n      \"refId\": \"customer_12345\"\n    }\n  ],\n  \"scaConfiguration\": {\n    \"scaCore\": \"circle_6900_singleowner_v4\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.circle.com/v1/w3s/user/wallets")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-User-Token"] = '<x-user-token>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotencyKey\": \"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11\",\n  \"blockchains\": [\n    \"MATIC-AMOY\"\n  ],\n  \"metadata\": [\n    {\n      \"name\": \"<string>\",\n      \"refId\": \"customer_12345\"\n    }\n  ],\n  \"scaConfiguration\": {\n    \"scaCore\": \"circle_6900_singleowner_v4\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "challengeId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5"
  }
}

{
  "data": {
    "challengeId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5"
  }
}

{
  "code": 400,
  "message": "Bad request."
}

{
  "code": 401,
  "message": "Malformed authorization."
}

POST

w3s

user

wallets

Create wallets

curl --request POST \
  --url https://api.circle.com/v1/w3s/user/wallets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-User-Token: <x-user-token>' \
  --data '
{
  "idempotencyKey": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "blockchains": [
    "MATIC-AMOY"
  ],
  "metadata": [
    {
      "name": "<string>",
      "refId": "customer_12345"
    }
  ],
  "scaConfiguration": {
    "scaCore": "circle_6900_singleowner_v4"
  }
}
'

import requests

url = "https://api.circle.com/v1/w3s/user/wallets"

payload = {
    "idempotencyKey": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
    "blockchains": ["MATIC-AMOY"],
    "metadata": [
        {
            "name": "<string>",
            "refId": "customer_12345"
        }
    ],
    "scaConfiguration": { "scaCore": "circle_6900_singleowner_v4" }
}
headers = {
    "X-User-Token": "<x-user-token>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-User-Token': '<x-user-token>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    idempotencyKey: 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11',
    blockchains: ['MATIC-AMOY'],
    metadata: [{name: '<string>', refId: 'customer_12345'}],
    scaConfiguration: {scaCore: 'circle_6900_singleowner_v4'}
  })
};

fetch('https://api.circle.com/v1/w3s/user/wallets', 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.circle.com/v1/w3s/user/wallets",
  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' => 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11',
    'blockchains' => [
        'MATIC-AMOY'
    ],
    'metadata' => [
        [
                'name' => '<string>',
                'refId' => 'customer_12345'
        ]
    ],
    'scaConfiguration' => [
        'scaCore' => 'circle_6900_singleowner_v4'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-User-Token: <x-user-token>"
  ],
]);

$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.circle.com/v1/w3s/user/wallets"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11\",\n  \"blockchains\": [\n    \"MATIC-AMOY\"\n  ],\n  \"metadata\": [\n    {\n      \"name\": \"<string>\",\n      \"refId\": \"customer_12345\"\n    }\n  ],\n  \"scaConfiguration\": {\n    \"scaCore\": \"circle_6900_singleowner_v4\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-User-Token", "<x-user-token>")
	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.circle.com/v1/w3s/user/wallets")
  .header("X-User-Token", "<x-user-token>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11\",\n  \"blockchains\": [\n    \"MATIC-AMOY\"\n  ],\n  \"metadata\": [\n    {\n      \"name\": \"<string>\",\n      \"refId\": \"customer_12345\"\n    }\n  ],\n  \"scaConfiguration\": {\n    \"scaCore\": \"circle_6900_singleowner_v4\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.circle.com/v1/w3s/user/wallets")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-User-Token"] = '<x-user-token>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotencyKey\": \"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11\",\n  \"blockchains\": [\n    \"MATIC-AMOY\"\n  ],\n  \"metadata\": [\n    {\n      \"name\": \"<string>\",\n      \"refId\": \"customer_12345\"\n    }\n  ],\n  \"scaConfiguration\": {\n    \"scaCore\": \"circle_6900_singleowner_v4\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "challengeId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5"
  }
}

{
  "data": {
    "challengeId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5"
  }
}

{
  "code": 400,
  "message": "Bad request."
}

{
  "code": 401,
  "message": "Malformed authorization."
}

Authorizations

Authorization

string

header

required

Circle's API Keys are formatted in the following structure "PREFIX:ID:SECRET". All three parts are required to make a successful request.

Headers

X-User-Token

string

required

Unique system generated JWT session token for specific user.

X-Request-Id

string<uuid>

Developer-provided identifier for this request, used for tracing requests in Wallets API logs and the Developer Console, and when communicating with Circle Support. Must be a UUID to appear in logs. Non-UUID values are accepted by the API but are ignored by logging and tracing systems.

A unique identifier, which can be helpful for identifying a request when communicating with Circle support.

Example:

"2adba88e-9d63-44bc-b975-9b6ae3440dde"

Body

application/json

walletResponse creation request

idempotencyKey

string<uuid>

required

Universally unique identifier (UUID v4) idempotency key. This key is utilized to ensure exactly-once execution of mutating requests. To create a UUIDv4 go to uuidgenerator.net. If the same key is reused, it will be treated as the same request and the original response will be returned.

Example:

"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"

blockchains

enum<string>[]

required

Blockchain(s) the requested wallets will be created on.

The blockchain network that the resource is to be created on or is currently on.

Available options:

ETH,

ETH-SEPOLIA,

AVAX,

AVAX-FUJI,

MATIC,

MATIC-AMOY,

SOL,

SOL-DEVNET,

ARB,

ARB-SEPOLIA,

NEAR,

NEAR-TESTNET,

EVM,

EVM-TESTNET,

UNI,

UNI-SEPOLIA,

BASE,

BASE-SEPOLIA,

OP,

OP-SEPOLIA,

APTOS,

APTOS-TESTNET,

ARC-TESTNET,

MONAD,

MONAD-TESTNET

accountType

enum<string>

An account can be a Smart Contract Account (SCA) or an Externally Owned Account (EOA). To learn more, see the account types guide.

If an account type is not specified during the creation of a wallet, it defaults to EOA (Externally Owned Account). Note that Solana and Aptos don't support Smart Contract Account (SCA).

Available options:

SCA,

EOA

metadata

object[]

List of metadata fields to associate with the corresponding wallet.

Show child attributes

scaConfiguration

object

Optional configuration applied when creating SCA (smart contract account) wallets. Ignored for externally owned account (EOA) wallets.

Show child attributes

Response

Returns the existing challenge if the idempotency key matches a previous successful request.

data

object

Show child attributes

API overview

Configurations

Developer-controlled

User-controlled

Modular

Compliance Engine

Create wallets

Authorizations

Headers

Body

Response