{"templateId":"markdown","versions":[{"version":"v1.39","label":"v1.39 STS","link":"/products/custody/transactions/send-and-receive/utxo-change-address-whitelisting","default":true,"active":true,"folderId":"c15a2701"},{"version":"v1.38","label":"v1.38 STS","link":"/products/custody/v1.38/transactions/send-and-receive/utxo-change-address-whitelisting","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.34","label":"v1.34 LTS","link":"/products/custody/v1.34/transactions/send-and-receive/utxo-change-address-whitelisting","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.26","label":"v1.26 LTS","link":"/products/custody/v1.26/transactions/send-and-receive/utxo-change-address-whitelisting","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.19","label":"v1.19 LTS","link":"/products/custody/v1.19/transactions/send-and-receive/utxo-change-address-whitelisting","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.15","label":"v1.15 LTS","link":"/products/custody/v1.15/transactions/send-and-receive/utxo-change-address-whitelisting","default":false,"active":false,"folderId":"c15a2701"}],"sharedDataIds":{"sidebar":"sidebar-products/custody/@v1.15/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"UTXO change address whitelisting","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"utxo-change-address-whitelisting","__idx":0},"children":["UTXO change address whitelisting"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-utxo-change-works","__idx":1},"children":["How UTXO change works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PrimaryAddress"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"change-address-strategies","__idx":2},"children":["Change address strategies"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Strategy"},"children":["Strategy"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Behavior"},"children":["Behavior"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Use when"},"children":["Use when"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GenerateNewAddress"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sends change to a newly generated internal change address."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["You want the standard BIP32 change-address behavior."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PrimaryAddress"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sends change to the account's first generated address."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["You need change to return to a stable address that can be whitelisted."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PrimaryAddress"]}," does not change the destination address of the outgoing payment. It only changes where leftover UTXO change is returned."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api-usage","__idx":3},"children":["API usage"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For Bitcoin transaction orders, set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parameters.addressForChange"]}," to choose the change address strategy."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"payload\": {\n    \"id\": \"transaction-order-uuid\",\n    \"accountId\": \"source-account-uuid\",\n    \"ledgerId\": \"bitcoin-ledger-id\",\n    \"parameters\": {\n      \"type\": \"Bitcoin\",\n      \"outputs\": [\n        {\n          \"destination\": {\n            \"type\": \"Address\",\n            \"address\": \"destination-address\"\n          },\n          \"amount\": \"100000\"\n        }\n      ],\n      \"feeStrategy\": {\n        \"priority\": \"Medium\",\n        \"type\": \"Priority\"\n      },\n      \"addressForChange\": \"PrimaryAddress\"\n    },\n    \"customProperties\": {},\n    \"type\": \"v0_CreateTransactionOrder\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For transfer orders on Bitcoin-type ledgers, set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["preferredAddressForChange"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PrimaryAddress"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"payload\": {\n    \"id\": \"transfer-order-uuid\",\n    \"accountId\": \"source-account-uuid\",\n    \"tickerId\": \"bitcoin-ticker-uuid\",\n    \"outputs\": [\n      {\n        \"destination\": {\n          \"type\": \"Address\",\n          \"address\": \"destination-address\"\n        },\n        \"amount\": \"100000\"\n      }\n    ],\n    \"feeStrategy\": {\n      \"priority\": \"Medium\",\n      \"type\": \"Priority\"\n    },\n    \"preferredAddressForChange\": \"PrimaryAddress\",\n    \"customProperties\": {},\n    \"type\": \"v0_CreateTransferOrder\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before you submit the intent, dry run the request and review the resulting transaction details and fee estimate."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"ui-usage","__idx":4},"children":["UI usage"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The UI can use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PrimaryAddress"]}," for UTXO change when the instance-level feature flag ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HMZ_FEATURE_USE_PRIMARY_FOR_CHANGE"]}," is enabled. Contact your Customer Partner Engineer (CPE) before enabling this behavior."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When this behavior is enabled, UI-created Bitcoin-type transfers can return change to the source account's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PrimaryAddress"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/send-change-to-primary-address.a35ba68273e0429c3de9d24c280cfed0f76824d7bb936b90a95eafe33590f6f7.efc8d9a4.png","alt":"Quick transfer form showing the Send change to primary address option"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"migration-best-practice","__idx":5},"children":["Migration best practice"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To fully use a single whitelisted address, consolidate existing UTXOs before or immediately after enabling ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PrimaryAddress"]}," change handling. Move UTXOs from previous change addresses to the account's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PrimaryAddress"]}," so future outgoing transactions can originate from and return change to the same predictable address."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Consolidate existing UTXOs"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"operational-considerations","__idx":6},"children":["Operational considerations"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm that the source account's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PrimaryAddress"]}," is the address you want counterparties or internal systems to whitelist."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PrimaryAddress"]}," consistently after consolidation so future change returns to the whitelisted address."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Existing UTXOs on historical change addresses remain spendable, but they can still affect transaction origin behavior until they are consolidated."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GenerateNewAddress"]}," when you need the standard BIP32 change-address behavior."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["This feature is separate from token allowlisting and endpoint allowlisting."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-topics","__idx":7},"children":["Related topics"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Topic"},"children":["Topic"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Documentation"},"children":["Documentation"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Send assets with the API"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/transactions/send-and-receive/send-assets-api"},"children":["Send assets with the API"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Send assets in the UI"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/transactions/send-and-receive/send-assets-ui"},"children":["Send assets in the UI"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction workflow"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/transactions/initiation"},"children":["Transaction workflow"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["UTXO account derivation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/accounts-and-assets/accounts/account-key-derivation-and-ledger-compatibility"},"children":["Account key derivation and ledger compatibility"]}]}]}]}]}]}]},"headings":[{"value":"UTXO change address whitelisting","id":"utxo-change-address-whitelisting","depth":1},{"value":"How UTXO change works","id":"how-utxo-change-works","depth":2},{"value":"Change address strategies","id":"change-address-strategies","depth":2},{"value":"API usage","id":"api-usage","depth":2},{"value":"UI usage","id":"ui-usage","depth":2},{"value":"Migration best practice","id":"migration-best-practice","depth":2},{"value":"Operational considerations","id":"operational-considerations","depth":2},{"value":"Related topics","id":"related-topics","depth":2}],"frontmatter":{"seo":{"title":"UTXO change address whitelisting"}},"lastModified":"2026-08-04T20:25:11.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/custody/transactions/send-and-receive/utxo-change-address-whitelisting","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}