# 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.

## How UTXO change works

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`.

## Change address strategies

| Strategy | Behavior | Use when |
|  --- | --- | --- |
| `GenerateNewAddress` | Sends change to a newly generated internal change address. | You want the standard BIP32 change-address behavior. |
| `PrimaryAddress` | Sends change to the account's first generated address. | You need change to return to a stable address that can be whitelisted. |


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

## API usage

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


```json
{
  "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`:


```json
{
  "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.

## UI usage

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`.

![Quick transfer form showing the Send change to primary address option](/assets/send-change-to-primary-address.a35ba68273e0429c3de9d24c280cfed0f76824d7bb936b90a95eafe33590f6f7.665ea620.png)

## Migration best practice

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.

Consolidate existing UTXOs
Contact your CPE if you need help planning UTXO consolidation. Consolidation moves value on-chain and should follow your normal approval, fee, and operational controls.

## Operational considerations

- 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.


## Related topics

| Topic | Documentation |
|  --- | --- |
| Send assets with the API | [Send assets with the API](/products/custody/transactions/send-and-receive/send-assets-api) |
| Send assets in the UI | [Send assets in the UI](/products/custody/transactions/send-and-receive/send-assets-ui) |
| Transaction workflow | [Transaction workflow](/products/custody/transactions/initiation) |
| UTXO account derivation | [Account key derivation and ledger compatibility](/products/custody/accounts-and-assets/accounts/account-key-derivation-and-ledger-compatibility) |