UTXO change address whitelisting

UTXO change address whitelisting lets Bitcoin-type transactions send change back to a predictable primary account address instead of generating a new change address for each transaction.

This feature is useful when counterparties, internal controls, or regulatory processes require a stable address to be whitelisted. It is also referred to as UTXO change address allowlisting.

Bitcoin-type ledgers use the unspent transaction output (UTXO) model. When an account spends a UTXO, the transaction consumes the full output. Any value that is not sent to the destination or paid as a fee is returned to the source account as change.

By default, Ripple Custody follows the standard BIP32 pattern and sends change to a newly generated internal change address. With UTXO change address whitelisting, you can return change to the account's first generated address, the PrimaryAddress.

Using PrimaryAddress does not change the destination address of the outgoing payment. It only changes where leftover UTXO change is returned.

For Bitcoin transaction orders, set parameters.addressForChange to choose the change address strategy.

{
  "payload": {
    "id": "transaction-order-uuid",
    "accountId": "source-account-uuid",
    "ledgerId": "bitcoin-ledger-id",
    "parameters": {
      "type": "Bitcoin",
      "outputs": [
        {
          "destination": {
            "type": "Address",
            "address": "destination-address"
          },
          "amount": "100000"
        }
      ],
      "feeStrategy": {
        "priority": "Medium",
        "type": "Priority"
      },
      "addressForChange": "PrimaryAddress"
    },
    "customProperties": {},
    "type": "v0_CreateTransactionOrder"
  }
}

For transfer orders on Bitcoin-type ledgers, set preferredAddressForChange to PrimaryAddress:

{
  "payload": {
    "id": "transfer-order-uuid",
    "accountId": "source-account-uuid",
    "tickerId": "bitcoin-ticker-uuid",
    "outputs": [
      {
        "destination": {
          "type": "Address",
          "address": "destination-address"
        },
        "amount": "100000"
      }
    ],
    "feeStrategy": {
      "priority": "Medium",
      "type": "Priority"
    },
    "preferredAddressForChange": "PrimaryAddress",
    "customProperties": {},
    "type": "v0_CreateTransferOrder"
  }
}

Before you submit the intent, dry run the request and review the resulting transaction details and fee estimate.

The UI can use PrimaryAddress for UTXO change when the instance-level feature flag HMZ_FEATURE_USE_PRIMARY_FOR_CHANGE is enabled. Contact your Customer Partner Engineer (CPE) before enabling this behavior.

When this behavior is enabled, UI-created Bitcoin-type transfers can return change to the source account's PrimaryAddress.

If you enable this feature on an existing instance that has already processed Bitcoin-type transactions, funds may be distributed across previously generated change addresses.

To fully use a single whitelisted address, consolidate existing UTXOs before or immediately after enabling PrimaryAddress change handling. Move UTXOs from previous change addresses to the account's PrimaryAddress so future outgoing transactions can originate from and return change to the same predictable address.

• Confirm that the source account's PrimaryAddress is the address you want counterparties or internal systems to whitelist.
• Use PrimaryAddress consistently after consolidation so future change returns to the whitelisted address.
• Existing UTXOs on historical change addresses remain spendable, but they can still affect transaction origin behavior until they are consolidated.
• Use GenerateNewAddress when you need the standard BIP32 change-address behavior.
• This feature is separate from token allowlisting and endpoint allowlisting.