Derive wallet by address

Creates a wallet on the target blockchain using the same address as the source wallet identified by source blockchain and wallet address. If the target wallet already exists, its metadata is updated.

PUT /v1/w3s/developer/wallets/derive

Derive wallet by address

cURL

curl --request PUT \
  --url https://api.circle.com/v1/w3s/developer/wallets/derive \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sourceBlockchain": "MATIC-AMOY",
  "walletAddress": "0xca9142d0b9804ef5e239d3bc1c7aa0d1c74e7350",
  "targetBlockchain": "MATIC-AMOY",
  "metadata": {
    "name": "<string>",
    "refId": "customer_12345"
  }
}
'

import requests

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

payload = {
    "sourceBlockchain": "MATIC-AMOY",
    "walletAddress": "0xca9142d0b9804ef5e239d3bc1c7aa0d1c74e7350",
    "targetBlockchain": "MATIC-AMOY",
    "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({
    sourceBlockchain: 'MATIC-AMOY',
    walletAddress: '0xca9142d0b9804ef5e239d3bc1c7aa0d1c74e7350',
    targetBlockchain: 'MATIC-AMOY',
    metadata: {name: '<string>', refId: 'customer_12345'}
  })
};

fetch('https://api.circle.com/v1/w3s/developer/wallets/derive', 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/derive",
  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([
    'sourceBlockchain' => 'MATIC-AMOY',
    'walletAddress' => '0xca9142d0b9804ef5e239d3bc1c7aa0d1c74e7350',
    'targetBlockchain' => 'MATIC-AMOY',
    '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/derive"

	payload := strings.NewReader("{\n  \"sourceBlockchain\": \"MATIC-AMOY\",\n  \"walletAddress\": \"0xca9142d0b9804ef5e239d3bc1c7aa0d1c74e7350\",\n  \"targetBlockchain\": \"MATIC-AMOY\",\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/derive")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"sourceBlockchain\": \"MATIC-AMOY\",\n  \"walletAddress\": \"0xca9142d0b9804ef5e239d3bc1c7aa0d1c74e7350\",\n  \"targetBlockchain\": \"MATIC-AMOY\",\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/derive")

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  \"sourceBlockchain\": \"MATIC-AMOY\",\n  \"walletAddress\": \"0xca9142d0b9804ef5e239d3bc1c7aa0d1c74e7350\",\n  \"targetBlockchain\": \"MATIC-AMOY\",\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"

Body

application/json

Request payload to derive a wallet by source blockchain + address onto a target blockchain.

sourceBlockchain · enum<string> · required

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"

walletAddress · string · required

Blockchain generated unique identifier, associated with wallet (account), smart contract or other blockchain objects.

Example:

"0xca9142d0b9804ef5e239d3bc1c7aa0d1c74e7350"

targetBlockchain · enum<string> · required

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"

metadata · object

Show child attributes

Response

200

application/json

Successfully updated the metadata for an existing wallet.

data · object · required

Show child attributes