Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt

Use this file to discover all available pages before exploring further.

Update mutable fields on an existing Offloader Wallet. You can change the bank account destination (including the payout rail and reference), adjust the integrator fee rate, or update the return address for failed transactions. The on-chain address and network are immutable after creation.

​
Endpoint

PATCH https://api.spherepay.co/v2/offloader-wallet/{id}

​
Authentication

All requests must include a Bearer token in the Authorization header. 
Authorization: Bearer <token>

​
Path parameters

​
id
string
required
The ID of the offloader wallet to update.

​
Request parameters

​
destination
object
Updated bank account destination configuration. Only supply fields you want to change.
​
integratorBpsFeeRate
string
Updated integrator fee in basis points (0–1000). Send "0" to remove the integrator fee entirely.
​
returnAddress
string
Updated on-chain return address for failed transactions. Must be valid for the wallet’s network.
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": {
      "bankAccountId": "bankAccount_6221e8d4299f4a889bd882255e92f581",
      "achReference": "REF456"
    }
  }'

​
Response fields

​
id
string
Unique identifier for the offloader wallet.
​
customerId
string
The ID of the customer who owns this wallet.
​
address
string
The on-chain wallet address (unchanged after creation).
​
currency
string
The stablecoin this wallet accepts (e.g., "usdc").
​
network
string
The blockchain network (e.g., "ethereum").
​
destination
object
The updated bank account destination configuration.
​
fees
object
Updated integrator and platform fee configuration.
​
returnAddress
string
The updated on-chain return address.
​
created
string
ISO 8601 timestamp of when the wallet was created.
​
updated
string
ISO 8601 timestamp of the most recent update.
{
  "id": "wallet_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "customerId": "customer_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "address": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97",
  "currency": "usdc",
  "network": "ethereum",
  "destination": {
    "bankAccountId": "bankAccount_6221e8d4299f4a889bd882255e92f581",
    "currency": "usd",
    "network": "ach",
    "achReference": "REF456"
  },
  "fees": {
    "integratorFee": {
      "bpsRate": "100",
      "currency": "usdc"
    },
    "platformFee": {
      "bpsRate": "30",
      "currency": "usdc"
    }
  },
  "returnAddress": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97",
  "created": "2024-06-15T10:30:00.000Z",
  "updated": "2024-06-15T14:00:00.000Z"
}
Last modified on May 12, 2026