Update an Offloader Wallet Bank Destination

Update an offloader wallet

curl --request PATCH \
  --url https://api.spherepay.co/v2/offloader-wallet/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "destination": {
    "bankAccountId": "bankAccount_6221e8d4299f4a889bd882255e92f581",
    "achReference": "REF456"
  },
  "integratorBpsFeeRate": "75",
  "returnAddress": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"
}
'

import requests

url = "https://api.spherepay.co/v2/offloader-wallet/{id}"

payload = {
    "destination": {
        "bankAccountId": "bankAccount_6221e8d4299f4a889bd882255e92f581",
        "achReference": "REF456"
    },
    "integratorBpsFeeRate": "75",
    "returnAddress": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    destination: {
      bankAccountId: 'bankAccount_6221e8d4299f4a889bd882255e92f581',
      achReference: 'REF456'
    },
    integratorBpsFeeRate: '75',
    returnAddress: '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97'
  })
};

fetch('https://api.spherepay.co/v2/offloader-wallet/{id}', 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.spherepay.co/v2/offloader-wallet/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'destination' => [
        'bankAccountId' => 'bankAccount_6221e8d4299f4a889bd882255e92f581',
        'achReference' => 'REF456'
    ],
    'integratorBpsFeeRate' => '75',
    'returnAddress' => '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97'
  ]),
  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.spherepay.co/v2/offloader-wallet/{id}"

	payload := strings.NewReader("{\n  \"destination\": {\n    \"bankAccountId\": \"bankAccount_6221e8d4299f4a889bd882255e92f581\",\n    \"achReference\": \"REF456\"\n  },\n  \"integratorBpsFeeRate\": \"75\",\n  \"returnAddress\": \"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97\"\n}")

	req, _ := http.NewRequest("PATCH", 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.patch("https://api.spherepay.co/v2/offloader-wallet/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"destination\": {\n    \"bankAccountId\": \"bankAccount_6221e8d4299f4a889bd882255e92f581\",\n    \"achReference\": \"REF456\"\n  },\n  \"integratorBpsFeeRate\": \"75\",\n  \"returnAddress\": \"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.spherepay.co/v2/offloader-wallet/{id}")

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

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"destination\": {\n    \"bankAccountId\": \"bankAccount_6221e8d4299f4a889bd882255e92f581\",\n    \"achReference\": \"REF456\"\n  },\n  \"integratorBpsFeeRate\": \"75\",\n  \"returnAddress\": \"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97\"\n}"

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

{
  "id": "wallet_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "customerId": "customer_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "address": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97",
  "currency": "usdc",
  "network": "ethereum",
  "status": "active",
  "destination": {
    "bankAccountId": "bankAccount_6221e8d4299f4a889bd882255e92f581",
    "currency": "usd",
    "network": "ach",
    "achReference": "REF123"
  },
  "fees": {
    "integratorFee": {
      "bpsRate": "100",
      "currency": "usdc"
    },
    "platformFee": {
      "bpsRate": "30",
      "currency": "usdc"
    }
  },
  "created": "2024-06-15T10:30:00.000Z",
  "updated": "2024-06-15T12:00:00.000Z",
  "returnAddress": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"
}

{
  "status": 400,
  "detail": "Invalid request parameters",
  "code": "address/invalid",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c"
}

{
  "status": 404,
  "detail": "Resource not found",
  "code": "resource/not-found",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c"
}

{
  "status": 422,
  "detail": "Validation failed",
  "code": "validation/failed",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "errors": [
    {
      "detail": "Invalid email format",
      "pointer": "/email"
    },
    {
      "detail": "Name is required",
      "pointer": "/name"
    }
  ]
}

Update an offloader wallet

curl --request PATCH \
  --url https://api.spherepay.co/v2/offloader-wallet/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "destination": {
    "bankAccountId": "bankAccount_6221e8d4299f4a889bd882255e92f581",
    "achReference": "REF456"
  },
  "integratorBpsFeeRate": "75",
  "returnAddress": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"
}
'

import requests

url = "https://api.spherepay.co/v2/offloader-wallet/{id}"

payload = {
    "destination": {
        "bankAccountId": "bankAccount_6221e8d4299f4a889bd882255e92f581",
        "achReference": "REF456"
    },
    "integratorBpsFeeRate": "75",
    "returnAddress": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    destination: {
      bankAccountId: 'bankAccount_6221e8d4299f4a889bd882255e92f581',
      achReference: 'REF456'
    },
    integratorBpsFeeRate: '75',
    returnAddress: '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97'
  })
};

fetch('https://api.spherepay.co/v2/offloader-wallet/{id}', 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.spherepay.co/v2/offloader-wallet/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'destination' => [
        'bankAccountId' => 'bankAccount_6221e8d4299f4a889bd882255e92f581',
        'achReference' => 'REF456'
    ],
    'integratorBpsFeeRate' => '75',
    'returnAddress' => '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97'
  ]),
  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.spherepay.co/v2/offloader-wallet/{id}"

	payload := strings.NewReader("{\n  \"destination\": {\n    \"bankAccountId\": \"bankAccount_6221e8d4299f4a889bd882255e92f581\",\n    \"achReference\": \"REF456\"\n  },\n  \"integratorBpsFeeRate\": \"75\",\n  \"returnAddress\": \"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97\"\n}")

	req, _ := http.NewRequest("PATCH", 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.patch("https://api.spherepay.co/v2/offloader-wallet/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"destination\": {\n    \"bankAccountId\": \"bankAccount_6221e8d4299f4a889bd882255e92f581\",\n    \"achReference\": \"REF456\"\n  },\n  \"integratorBpsFeeRate\": \"75\",\n  \"returnAddress\": \"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.spherepay.co/v2/offloader-wallet/{id}")

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

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"destination\": {\n    \"bankAccountId\": \"bankAccount_6221e8d4299f4a889bd882255e92f581\",\n    \"achReference\": \"REF456\"\n  },\n  \"integratorBpsFeeRate\": \"75\",\n  \"returnAddress\": \"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97\"\n}"

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

{
  "id": "wallet_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "customerId": "customer_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "address": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97",
  "currency": "usdc",
  "network": "ethereum",
  "status": "active",
  "destination": {
    "bankAccountId": "bankAccount_6221e8d4299f4a889bd882255e92f581",
    "currency": "usd",
    "network": "ach",
    "achReference": "REF123"
  },
  "fees": {
    "integratorFee": {
      "bpsRate": "100",
      "currency": "usdc"
    },
    "platformFee": {
      "bpsRate": "30",
      "currency": "usdc"
    }
  },
  "created": "2024-06-15T10:30:00.000Z",
  "updated": "2024-06-15T12:00:00.000Z",
  "returnAddress": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"
}

{
  "status": 400,
  "detail": "Invalid request parameters",
  "code": "address/invalid",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c"
}

{
  "status": 404,
  "detail": "Resource not found",
  "code": "resource/not-found",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c"
}

{
  "status": 422,
  "detail": "Validation failed",
  "code": "validation/failed",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "errors": [
    {
      "detail": "Invalid email format",
      "pointer": "/email"
    },
    {
      "detail": "Name is required",
      "pointer": "/name"
    }
  ]
}

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

network is not a mutable field. The destination rail is fixed when you create the Offloader Wallet. To switch rails (for example, from ACH to wire), create a new Offloader Wallet.

Authorizations

Authorization

string

header

required

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

Path Parameters

string

required

Body

application/json

destination

object

The bank account destination where converted funds are sent.

Show child attributes

Example:

{
  "bankAccountId": "bankAccount_6221e8d4299f4a889bd882255e92f581",
  "achReference": "REF456"
}

integratorBpsFeeRate

string

Integrator fee override in basis points (0-1000). Send "0" to remove the integrator fee.

Example:

"75"

returnAddress

string

Crypto address where funds are returned on failed transactions. Must be valid for the wallet network.

Example:

"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"

Response

string

required

Unique identifier for the offloader wallet.

Example:

"wallet_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

customerId

string

required

The customer who owns the offloader wallet.

Example:

"customer_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

address

string

required

The on-chain deposit address for the offloader wallet. Send crypto to this address to trigger automatic conversion.

Example:

"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"

currency

enum<string>

required

The crypto currency the offloader wallet accepts for deposits. See Supported Rails & Currencies.

Available options:

usdc,

usdt,

eurc

Example:

"usdc"

network

enum<string>

required

The blockchain network the offloader wallet is on. See Supported Rails & Currencies.

Available options:

sol,

ethereum,

arbitrum,

polygon,

base,

avalanche,

tron

Example:

"ethereum"

status

enum<string>

required

Lifecycle status of the offloader wallet. active accepts deposits and settles; deactivated no longer settles.

Available options:

active,

deactivated

Example:

"active"

destination

ACH · object

required

The bank account destination where converted funds are sent. See Bank Accounts guide.

ACH
Wire
SEPA

Show child attributes

Example:

{
  "bankAccountId": "bankAccount_6221e8d4299f4a889bd882255e92f581",
  "currency": "usd",
  "network": "ach",
  "achReference": "REF123"
}

fees

object

required

Fee configuration for the offloader wallet, including integrator and platform fees.

Show child attributes

Example:

{
  "integratorFee": { "bpsRate": "100", "currency": "usdc" },
  "platformFee": { "bpsRate": "30", "currency": "usdc" }
}

created

string

required

Timestamp when the offloader wallet was created (ISO 8601).

Example:

"2024-06-15T10:30:00.000Z"

updated

string

required

Timestamp when the offloader wallet was last updated (ISO 8601).

Example:

"2024-06-15T12:00:00.000Z"

returnAddress

string

Crypto address where funds are returned on failed transactions. Must be valid for the wallet network. Null if not configured.

Example:

"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"

Last modified on July 30, 2026

⌘I

Onboarding

Accounts

Money movement

Update an Offloader Wallet Bank Destination

Authorizations

Path Parameters

Body

Response