Derive a wallet

Derives an EOA (Externally Owned Account) or SCA (Smart Contract Account) wallet using the address of the specified wallet and blockchain. If the target wallet already exists, its metadata will be updated with the provided metadata. This operation is only supported for EVM-based blockchains.

PUT /v1/w3s/developer/wallets/{id}/blockchains/{blockchain}

Derive a wallet

cURL

curl --request PUT \
  --url https://api.circle.com/v1/w3s/developer/wallets/{id}/blockchains/{blockchain} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "metadata": {
    "name": "<string>",
    "refId": "customer_12345"
  }
}
'

import requests

url = "https://api.circle.com/v1/w3s/developer/wallets/{id}/blockchains/{blockchain}"

payload = { "metadata": {
        "name": "<string>",
        "refId": "customer_12345"
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({metadata: {name: '<string>', refId: 'customer_12345'}})
};

fetch('https://api.circle.com/v1/w3s/developer/wallets/{id}/blockchains/{blockchain}', 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/developer/wallets/{id}/blockchains/{blockchain}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'metadata' => [
        'name' => '<string>',
        'refId' => 'customer_12345'
    ]
  ]),
  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.circle.com/v1/w3s/developer/wallets/{id}/blockchains/{blockchain}"

	payload := strings.NewReader("{\n  \"metadata\": {\n    \"name\": \"<string>\",\n    \"refId\": \"customer_12345\"\n  }\n}")

	req, _ := http.NewRequest("PUT", 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.put("https://api.circle.com/v1/w3s/developer/wallets/{id}/blockchains/{blockchain}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"metadata\": {\n    \"name\": \"<string>\",\n    \"refId\": \"customer_12345\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.circle.com/v1/w3s/developer/wallets/{id}/blockchains/{blockchain}")

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

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"metadata\": {\n    \"name\": \"<string>\",\n    \"refId\": \"customer_12345\"\n  }\n}"

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

200

{
  "data": {
    "wallet": {
      "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
      "address": "0xca9142d0b9804ef5e239d3bc1c7aa0d1c74e7350",
      "blockchain": "MATIC-AMOY",
      "createDate": "2023-01-01T12:04:05Z",
      "updateDate": "2023-01-01T12:04:05Z",
      "state": "LIVE",
      "walletSetId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
      "accountType": "EOA",
      "name": "<string>",
      "refId": "customer_12345",
      "userId": "ext_user_id_1",
      "initialPublicKey": "3eQoJ3ex6uWX3R8F1THF6Y6oBQwPYpF1X9HBM1gjqw7w"
    }
  }
}

{
  "data": {
    "wallet": {
      "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
      "address": "0xca9142d0b9804ef5e239d3bc1c7aa0d1c74e7350",
      "blockchain": "MATIC-AMOY",
      "createDate": "2023-01-01T12:04:05Z",
      "updateDate": "2023-01-01T12:04:05Z",
      "state": "LIVE",
      "walletSetId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
      "accountType": "EOA",
      "name": "<string>",
      "refId": "customer_12345",
      "userId": "ext_user_id_1",
      "initialPublicKey": "3eQoJ3ex6uWX3R8F1THF6Y6oBQwPYpF1X9HBM1gjqw7w"
    }
  }
}

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

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

{
  "code": 404,
  "message": "Not found."
}

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

Path Parameters

id · string<uuid> · required

The universally unique identifier of the resource.

Example:

"b3d9d2d5-4c12-4946-a09d-953e82fae2b0"

blockchain · enum<string> · required

The unique identifier of the blockchains. 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, ARB, ARB-SEPOLIA, UNI, UNI-SEPOLIA, BASE, BASE-SEPOLIA, OP, OP-SEPOLIA, EVM, EVM-TESTNET, ARC-TESTNET, MONAD, MONAD-TESTNET

Example:

"MATIC-AMOY"

Body

application/json

Defines the request payload schema for deriving a new wallet.

metadata · object

Show child attributes

Response

200

application/json

Successfully updated the metadata for an existing wallet.

data · object · required

Show child attributes