Add a wallet owner

curl --request POST \
  --url https://api-sandbox.circle.com/v1/borrow/wallets/owners \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "ownerKey": "<string>",
  "credentialId": "<string>"
}
'

import requests

url = "https://api-sandbox.circle.com/v1/borrow/wallets/owners"

payload = {
    "idempotencyKey": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "ownerKey": "<string>",
    "credentialId": "<string>"
}
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: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    ownerKey: '<string>',
    credentialId: '<string>'
  })
};

fetch('https://api-sandbox.circle.com/v1/borrow/wallets/owners', 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/borrow/wallets/owners",
  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' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'ownerKey' => '<string>',
    'credentialId' => '<string>'
  ]),
  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/borrow/wallets/owners"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"ownerKey\": \"<string>\",\n  \"credentialId\": \"<string>\"\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/borrow/wallets/owners")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"ownerKey\": \"<string>\",\n  \"credentialId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.circle.com/v1/borrow/wallets/owners")

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\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"ownerKey\": \"<string>\",\n  \"credentialId\": \"<string>\"\n}"

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

{
  "data": {
    "id": "a7b8c9d0-e123-4567-890a-bcdef1234567",
    "jobType": "add_owner",
    "status": "received",
    "createDate": "2026-06-25T11:00:00.000Z",
    "updateDate": "2026-06-25T11:00:00.000Z"
  }
}

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

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

{
  "code": 3,
  "message": "Forbidden"
}

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

{
  "code": 409,
  "message": "Conflicts with another request."
}

POST

borrow

wallets

owners

Add a wallet owner

curl --request POST \
  --url https://api-sandbox.circle.com/v1/borrow/wallets/owners \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "ownerKey": "<string>",
  "credentialId": "<string>"
}
'

import requests

url = "https://api-sandbox.circle.com/v1/borrow/wallets/owners"

payload = {
    "idempotencyKey": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "ownerKey": "<string>",
    "credentialId": "<string>"
}
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: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    ownerKey: '<string>',
    credentialId: '<string>'
  })
};

fetch('https://api-sandbox.circle.com/v1/borrow/wallets/owners', 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/borrow/wallets/owners",
  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' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'ownerKey' => '<string>',
    'credentialId' => '<string>'
  ]),
  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/borrow/wallets/owners"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"ownerKey\": \"<string>\",\n  \"credentialId\": \"<string>\"\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/borrow/wallets/owners")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"ownerKey\": \"<string>\",\n  \"credentialId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.circle.com/v1/borrow/wallets/owners")

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\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"ownerKey\": \"<string>\",\n  \"credentialId\": \"<string>\"\n}"

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

{
  "data": {
    "id": "a7b8c9d0-e123-4567-890a-bcdef1234567",
    "jobType": "add_owner",
    "status": "received",
    "createDate": "2026-06-25T11:00:00.000Z",
    "updateDate": "2026-06-25T11:00:00.000Z"
  }
}

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

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

{
  "code": 3,
  "message": "Forbidden"
}

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

{
  "code": 409,
  "message": "Conflicts with another request."
}

Authorizations

Authorization

string

header

required

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

Body

application/json

Request to add a new passkey owner to your wallet. The new owner is added as an additional authorized signer. Existing owners are retained. Circle signs the UserOperation that adds the new owner.

idempotencyKey

string<uuid>

required

Idempotency key (UUID v4) for this request. Reusing it with a different body returns 409 Conflict.

ownerKey

string

required

Hex-encoded raw P256 public key bytes of the passkey to add as an owner.

credentialId

string

required

Hex-encoded WebAuthn credential identifier captured during passkey registration. Stored on the new owner record and returned by GET /v1/borrow/wallets.

Response

Request to add a wallet owner accepted. Poll the returned job to track its status.

data

object

An async onchain operation. Each job represents one of: borrow, repay, add collateral, wallet setup, owner change, or residual withdraw. Poll this resource until the job reaches a terminal status (completed, failed, or approval_rejected). Fields that do not apply to the current status or job type are omitted rather than returned as null.

Show child attributes

Example:

{
  "id": "b3d9d2d5-4c12-4946-a09d-953e82fae2b0",
  "jobType": "borrow",
  "status": "completed",
  "amount": "1000.00",
  "asset": "USD",
  "collateralAmount": "0.05",
  "collateralAsset": "CIRBTC",
  "toAddress": "0x5a0b4a11d3f9b2c1e8a7d6c5b4a39281f0e1d2c3",
  "loanId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32",
  "transferId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "oraclePrice": "67234.51",
  "userOpHash": "0x9f8e7d6c5b4a39281f0e1d2c3b4a5968778695a4b3c2d1e0f9a8b7c6d5e4f3a2",
  "txHash": "0x1a2b3c4d5e6f70819293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "createDate": "2026-06-20T14:20:00.000Z",
  "updateDate": "2026-06-20T14:22:00.000Z"
}

API overview

Custody API

Mint API

Cross-currency API

Reserve management API

Credit API

Digital Asset-Backed Borrowing

Webhook events

Add a wallet owner

Authorizations

Body

Response