Rotate a wallet

curl --request POST \
  --url https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallets/{walletId}/rotate \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>'

import requests

url = "https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallets/{walletId}/rotate"

headers = {
    "Idempotency-Key": "<idempotency-key>",
    "x-api-key": "<api-key>"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'Idempotency-Key': '<idempotency-key>', 'x-api-key': '<api-key>'}
};

fetch('https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallets/{walletId}/rotate', 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.conduit.financial/v2/customers/{customerId}/wallets/{walletId}/rotate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Idempotency-Key: <idempotency-key>",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallets/{walletId}/rotate"

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

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("x-api-key", "<api-key>")

	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.conduit.financial/v2/customers/{customerId}/wallets/{walletId}/rotate")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("x-api-key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallets/{walletId}/rotate")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["x-api-key"] = '<api-key>'

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

{
  "id": "wlt_2xKjF9mQb7vN4hL1pR3w8t",
  "chain": "ethereum",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  "status": "pending",
  "balances": [
    {
      "available": {
        "code": "USD",
        "amount": "<string>",
        "chain": "ethereum"
      },
      "pending": {
        "code": "USD",
        "amount": "<string>",
        "chain": "ethereum"
      },
      "frozen": {
        "code": "USD",
        "amount": "<string>",
        "chain": "ethereum"
      }
    }
  ],
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z",
  "custodyModel": "non_custodial",
  "rotatedAt": "2026-01-15T09:30:00.000Z",
  "replacedByWalletId": "<string>",
  "clientReferenceId": "<string>"
}

{
  "ceremonyId": "<string>",
  "verificationUrl": "<string>"
}

{
  "type": "INVALID_OID_FORMAT",
  "title": "Invalid Object ID Format",
  "status": 400,
  "detail": "A path or query parameter expected a valid object identifier but received a value that does not match the expected format.",
  "resolution": "Verify that all IDs in the request URL and query parameters are correctly formatted. IDs are typically prefixed strings like 'cus_...', 'app_...', or 'doc_...'.",
  "docs": "https://v2.docs.conduit.financial/errors#invalid-oid-format",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "API_KEY_MISSING",
  "title": "API Key Missing",
  "status": 401,
  "detail": "The request did not include an API key. All API requests must be authenticated.",
  "resolution": "Include your API key in the 'x-api-key' header with every request.",
  "docs": "https://v2.docs.conduit.financial/errors#api-key-missing",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "ORGANIZATION_ACCESS_SUSPENDED",
  "title": "Organization Access Suspended",
  "status": 403,
  "detail": "Conduit has suspended this organization's access. Requests with the organization's API keys and from its users are refused until Conduit restores access.",
  "resolution": "Contact Conduit support.",
  "docs": "https://v2.docs.conduit.financial/errors#organization-access-suspended",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "WALLET_NOT_FOUND",
  "title": "Wallet Not Found",
  "status": 404,
  "detail": "No wallet exists with the specified ID, or the wallet belongs to a different organization.",
  "resolution": "Verify the wallet ID is correct. Use the list wallets endpoint to find valid wallet IDs for your organization.",
  "docs": "https://v2.docs.conduit.financial/errors#wallet-not-found",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "IDEMPOTENCY_KEY_CONFLICT",
  "title": "Idempotency Key Conflict",
  "status": 409,
  "detail": "The idempotency key was previously used with a different request body, and that request succeeded or ended in a `5xx`. A `4xx` response does not bind the key. Idempotency keys are bound to the exact request shape — replays must match the original.",
  "resolution": "Use a fresh idempotency key for the new request, or replay the original request unchanged.",
  "docs": "https://v2.docs.conduit.financial/errors#idempotency-key-conflict",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "UNSUPPORTED_MEDIA_TYPE",
  "title": "Unsupported Media Type",
  "status": 415,
  "detail": "The request carries a body with a Content-Type this endpoint cannot parse. JSON endpoints accept 'application/json'; a body with no Content-Type header at all is assumed to be JSON. File-upload endpoints accept only 'multipart/form-data' — JSON or undeclared bodies are rejected there.",
  "resolution": "Send the request body with the 'Content-Type: application/json' header. For file uploads, use 'Content-Type: multipart/form-data' — upload endpoints accept no other body type.",
  "docs": "https://v2.docs.conduit.financial/errors#unsupported-media-type",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "WALLET_ROTATION_BLOCKED_BALANCE",
  "title": "Wallet Rotation Blocked: Balance Above Dust",
  "status": 422,
  "detail": "The wallet holds a balance (available, pending, or frozen) above the asset's dust floor and cannot be rotated. Rotation would strand those funds on the retired wallet record. A leftover at or below the dust floor does not block rotation — it is too small to be worth a transfer, so nothing will ever move it.",
  "resolution": "Move the funds out of the wallet (e.g. via a payout) and wait for any in-flight deposits to settle, then retry the rotation. Compliance-frozen balances must be released before rotation is possible.",
  "docs": "https://v2.docs.conduit.financial/errors#wallet-rotation-blocked-balance",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "RATE_LIMITED",
  "title": "Rate Limited",
  "status": 429,
  "detail": "Too many requests. This error is returned by three independent checks: the per-organization bucket applied to every authenticated API request; the per-IP bucket applied to unauthenticated traffic before an API key is validated; and the per-IP bucket applied when repeated invalid API keys are submitted from the same address. Honor the Retry-After header (also exposed as retryAfterSeconds in the body) before retrying. Current limits and remaining budget are visible in X-RateLimit-Limit (the bucket size), X-RateLimit-Remaining, and X-RateLimit-Reset (seconds until the bucket refills) on every response once your API key is accepted.",
  "resolution": "Sleep until Retry-After seconds have elapsed, then retry. For sustained workloads exceeding the per-organization defaults, request a rate-limit increase through your support contact.",
  "docs": "https://v2.docs.conduit.financial/errors#rate-limited",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z",
  "retryAfterSeconds": 3
}

{
  "type": "INTERNAL_ERROR",
  "title": "Internal Error",
  "status": 500,
  "detail": "An unexpected error occurred while processing your request.",
  "resolution": "Retry the request after a brief delay. If the error persists, contact support and include the correlationId from the error response for investigation.",
  "docs": "https://v2.docs.conduit.financial/errors#internal-error",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

{
  "type": "ASSET_CHAIN_PAUSED",
  "title": "Asset Chain Paused",
  "status": 503,
  "detail": "Conduit has temporarily paused this asset on this chain, or the whole chain, so it cannot accept this request now. Asset and chain pairs that are not paused stay available.",
  "resolution": "Retry the same request later; it succeeds once Conduit lifts the pause. Use an asset and chain pair that is not paused if you cannot wait.",
  "docs": "https://v2.docs.conduit.financial/errors#asset-chain-paused",
  "instance": "/v2/...",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}