UTXO Management

31 min

Heads up!

UTXO management via the API is currently available for Bitcoin (BTC) only.

Introduction

Managing UTXOs (Unspent Transaction Outputs) is essential for keeping your Bitcoin wallets efficient and ready for future transactions. Without ongoing management, wallets accumulate many small UTXOs that make transactions costly, slow, or even impossible to build within system limits.

This article walks you through how to check, merge, and adjust UTXOs using our API, so you can reduce transaction fees, avoid system constraints, and maintain operational readiness. UTXO management is a cyclical process, not a one-time action, and is critical for keeping large Bitcoin wallets usable over time.

For sending UTXO transactions, see Sending Transactions via API.

Summary

To help you navigate, here are quick links to each section:

Introduction

What is a "UTXO"

The UTXO Management Process

Limitations

Checking your UTXOs

Merging and Tracking the Merge

Modifying a Merge Request

Endpoint Deep Dive

*Endpoint Deep Dive - Expanded

retrieveAllMpcUtxosForAccount

retrieveSingleMpcUtxoByTxIdAndVoutIndex

mergeUtxos

searchMergeUtxosRequests

getMergeUtxosRequestById

raiseFeeForMergeUtxosTransactionRequest

overrideMergeUtxosTransactionRequest

What is a "UTXO"

Before we get into the process, let’s quickly define UTXOs and why managing them matters. A UTXO (Unspent Transaction Output) is a piece of Bitcoin in your wallet that hasn’t been spent yet. Over time, wallets collect many small UTXOs from deposits and other activity.

If left unmanaged, these small UTXOs make future transactions larger, slower, and more expensive—since fees are based on transaction size. Plus, there’s a hard limit of 299 UTXOs per transaction, so too many small pieces can prevent you from moving funds when needed.

That’s why UTXO management is ongoing. By regularly merging smaller UTXOs into larger ones, you keep your wallet efficient, avoid system limits, and reduce fees.

Understanding the UTXO Management Process

The diagram below shows the full UTXO management cycle — from checking available UTXOs to creating, tracking, and modifying merge requests when needed.

flowchart TD
    A[Start: Review UTXOs] --> B[Call retrieveAllMpcUtxosForAccount]
    B --> C{Merge needed?}
    C -- No --> Z[End]
    C -- Yes --> D[Call mergeUtxos to create request]
    D --> E[System creates transactions, max 299 UTXOs each]
    E --> F[Track merge with getMergeUtxosRequestById]
    F --> G{Stuck in mempool?}
    G -- No --> Z
    G -- Yes --> H{Raise fee or override?}
    H -- Raise fee --> I[Call raiseFeeForMergeUtxosTransactionRequest]
    H -- Override --> J[Call overrideMergeUtxosTransactionRequest]
    I --> Z
    J --> Z

The UTXO management cycle starts by reviewing available UTXOs and deciding whether to merge them to keep your wallet efficient and reduce fees.

If you choose to merge, you submit a merge request with rules for which UTXOs to combine—like size ranges, batch limits, and fee per vbyte. The system automatically selects eligible UTXOs and groups them into transactions, respecting your max_utxos_per_transaction limit (up to 299).

Once submitted, you can track the merge and review all requests for that account. If a transaction gets stuck, you can raise the fee or override it with a smaller high-fee transaction to free UTXOs.

The cycle ends when UTXOs are merged or you decide no further action is needed—keeping you in full control throughout.

Limitations

BTC only: UTXO management is limited to Bitcoin.

Max 299 UTXOs per transaction (set via max_utxos_per_transaction).

Multiple transactions auto-created if more than (the value ofmax_utxos_per_transaction) UTXOs match criteria.

Checking Your UTXOs

Before deciding to merge UTXOs or send a transaction, you need to know what UTXOs are currently available in your wallet.

Checking your UTXOs gives you a clear view of how your funds are distributed, helping you decide whether merging is necessary. If you want more details about a specific UTXO, you can also drill down to see information such as whether it’s currently spendable or mergeable.

Detailed Process Diagram

The diagram below shows the process for checking UTXOs in your wallet, from identifying the account to reviewing available UTXOs and drilling down for more detail.

flowchart TD
    A[Call retrieveAllMpcUtxosForAccount] --> B{Need more details?}
    B -- Yes --> C[Call retrieveSingleMpcUtxoByTxIdAndVoutIndex]
    B -- No --> D[Done reviewing UTXOs]

Prerequisites

Before you can check your UTXOs, you’ll need:

The account ID (account_id) of the wallet you want to review.

The currency symbol (coin_type), currently "BTC" only.

Call-by-Call Walkthrough

Retrieve all UTXOs by calling retrieveAllMpcUtxosForAccount. Provide the coin_type and account_id:

client.retrieveAllMpcUtxosForAccount(coin_type="BTC", account_id=1)

You’ll get a list of UTXOs, including fields like TxId, VoutIndex, Amount, CurrencySymbol, Spendable, Mergeable, and more. See the Endpoint Deep Dive for a detailed breakdown of the response.

(Optional) Drill into a specific UTXO by calling retrieveSingleMpcUtxoByTxIdAndVoutIndex. If you want more detail on a specific UTXO, use its TxId and VoutIndex from the previous step:

client.retrieveSingleMpcUtxoByTxIdAndVoutIndex( coin_type="BTC", tx_id="e16b070a1d4d56301c8ef97952b06376c404b1dc6e7d46430f3d3885d23df8d3", vout_index=0 )

This will return full details of the UTXO, including whether it’s currently spendable or eligible for merging. See the deep dive for a full breakdown of the response.

Merging UTXOs and Tracking the Merge Request

Merging smaller UTXOs together helps reduce future transaction fees, keep your wallet efficient, and ensure you stay within the system’s technical limits.

Detailed Process Diagram

The diagram below illustrates how the system selects UTXOs and creates transactions, as well as how to track the results of the merge.

flowchart TD
    A[Start] --> B[Call mergeUtxos to create a merge request]
    B --> C[User defines batch size using max_utxos_per_transaction Maximum allowed is 299]
    C --> D{Are there enough UTXOs that meet the criteria?}

    D -- No --> E[No merge will occur Not enough UTXOs to merge]
    D -- Yes --> F[System creates transaction with up to max_utxos_per_transaction UTXOs]

    F --> G{Are more UTXOs remaining to merge?}
    G -- Yes --> F
    G -- No --> H[Merge request creation complete]

    H --> I[Call getMergeUtxosRequestById to track merge request status]

When you call mergeUtxos, the system automatically selects all "Mergeable" UTXOs within the min_amount and max_amount you set—there’s no way to exclude individual UTXOs that fit your criteria.

The system then groups these UTXOs into transactions based on your max_utxos_per_transaction limit (up to 299). If more UTXOs are available, it creates multiple transactions under the same merge request. If fewer, it still merges them—UTXOs aren’t skipped just because they don’t form a full batch.

If no UTXOs match, no merge occurs.

Once submitted, you can track the request and its transactions using getMergeUtxosRequestById.

Prerequisite Information

Before you can merge UTXOs, you need to check your wallet’s current UTXOs and the current network conditions.

Internal information — from your wallet

You’ll need to know:

The account ID (account_id) for the wallet you want to manage.

The currency symbol (coin_type, currently "BTC" only).

The size and number of UTXOs you want to merge. This will help you decide:

The minimum amount for UTXOs to include (min_amount, as a string, e.g., "1").

The maximum amount for UTXOs to include (max_amount, as a string, e.g., "100000000").

The maximum number of UTXOs to merge in a single transaction (max_utxos_per_transaction). This cannot exceed 299.

Note: UTXOs are merged in groups based on the batch size you set. If fewer UTXOs remain than your max_utxos_per_transaction, the system merges them into a smaller transaction. For example, if you set max_utxos_per_transaction to 299 and 342 UTXOs match your size limits, the system will create two transactions — one with 299 UTXOs and another with 43.

To get this information, follow the steps in Checking your UTXOs, where you’ll learn how to review all available UTXOs and drill down into specific ones if needed.

External information — from current Bitcoin network conditions

You’ll also need to decide on a fee per vbyte (fee) that makes sense based on current network fees. Because fee levels change over time depending on network activity, you should check a live Bitcoin fee estimator before setting this value.

Recommended sources include:

mempool.space

blockstream.info

Additionally, you can decide whether to allow higher-than-default fees (allow_high_fee, optional, defaults to False) to ensure your merge transaction gets confirmed quickly during high congestion periods. If you don’t set allow_high_fee to True, the system will reject the merge if the required fee is above its suggested level.

Making a Merge Request - Call-by-Call Walkthrough

Once you’re ready to merge UTXOs, follow these steps to submit a merge request and track its progress:

Create a merge request by calling mergeUtxos. Provide the coin_type, account_id, min_amount, max_amount, fee, max_utxos_per_transaction, and optionally allow_high_fee:

client.mergeUtxos( coin_type="BTC", account_id=1, min_amount="1", max_amount="100000000", fee=2, max_utxos_per_transaction=299 )

You'll get a MergeUtxosRequestId for tracking the request, along with its initial status. See the deep dive for a detailed breakdown of the response.

Track the merge request by calling getMergeUtxosRequestById. Provide the merge_utxos_request_id returned when you ran mergeUtxos:

client.getMergeUtxosRequestById("0503...8c76")

You'll get the current status of the merge request, including whether it's still pending, sent, completed, or failed. The response will also list the UTXOs involved and any transaction IDs created. See the deep dive for a full breakdown of the response.

Following Up on Existing Merge Requests

After checking or creating a merge request, you can review all existing merge requests for the account to see what’s active, completed, or failed—and decide if you need to act.

Call searchMergeUtxosRequests with coin_type and account_id:

client.searchMergeUtxosRequests(coin_type="BTC", account_id=1)

The response lists all merge requests and their statuses, helping you decide whether to wait, adjust, or create a new request.

Here’s what the main statuses mean and how to respond:

Status	Meaning	Recommended action
Waiting to be processed	The merge request is active and queued for processing.	Wait and monitor. No need to submit a new request.
Sent	The merge transaction has been broadcast to the network.	Monitor. The transaction is pending; no new merge needed yet.
Failed or Failed-Limits	The request failed due to system limits (e.g., too many UTXOs, high fee).	Review limits, adjust parameters, and create a new request.
Completed	The merge transaction(s) are confirmed on the blockchain.	No further action needed.

Modifying a Merge Request

Sometimes, a merge transaction may remain unconfirmed longer than expected. Depending on the situation, you can raise the fee or override the transaction to resolve the issue.

When to Raise the Fee

If the transaction is unconfirmed because the fee was too low, raising the fee can incentivize miners to confirm it sooner.

Use this option when you want to keep the same UTXOs and transaction structure but simply need faster confirmation.

Raising the fee does not change which UTXOs are being merged or how the transaction is built; it makes the transaction more appealing to miners.

When to Override the Transaction

If you can’t raise the fee (because doing so would make the transaction too expensive), but need to free up some UTXOs, override lets you create a new, smaller transaction using a subset of the original UTXOs.

Use override when you need urgent access to part of the UTXOs but don’t want to raise the fee on all of them.

This is helpful if fees have suddenly spiked, and raising the fee on the whole transaction would be too costly.

Once the small override transaction confirms, the remaining UTXOs will become available again.

Note: Override is not for fixing incorrect parameters — it’s a way to replace a large, stuck transaction with a smaller, high-fee transaction to free up funds.

Raise Fee or Override: Best Practices

Assess Network Conditions: Check current fee rates and network congestion before deciding which action to take.

Use Fee Estimation Tools: Services like mempool.space and blockstream.info can help set a realistic fee to avoid future delays.

Consider Cost vs. Need: Use raise fee when you want to preserve the whole merge; use override when you need to free some UTXOs quickly without overpaying.

By understanding when to raise fees versus when to override transactions, you can effectively manage unconfirmed transactions and maintain efficient wallet operations.

Detailed Decision Diagram

The diagram below shows how to decide what to do when a merge transaction is not confirming. Depending on whether you need faster confirmation or urgent access to some UTXOs, you can choose the right action to take.

flowchart TD
    A[Start: Merge transaction is unconfirmed] --> B{Is the fee too low for current network conditions?}

    B -- Yes --> C[Call raiseFeeForMergeUtxosTransactionRequest to raise the fee]
    B -- No --> D{Do you need to urgently free up some UTXOs?}

    D -- Yes --> E[Call overrideMergeUtxosTransactionRequest to create a smaller high-fee transaction]
    D -- No --> F[Wait longer or investigate other issues]

    C --> G[Call getMergeUtxosRequestById to monitor updated request]
    E --> G
    F --> G
    G --> H[End]

Prerequisite Information

Before modifying a merge request, you’ll need to gather some information to decide how to proceed. This includes both internal details from your system and external insights about current network conditions.

Internal information — from your system

You’ll need to know:

The MergeUtxosRequestId of the merge request you want to modify (returned when you created or tracked the request, or found using searchMergeUtxosRequests).

The current status of the merge request (retrieved using getMergeUtxosRequestById).

The original fee set for the transaction (included in the merge request details).

External information — from current Bitcoin network conditions

To determine if raising the fee is necessary, you’ll need to know what fees are currently reasonable on the Bitcoin network.

Check a live Bitcoin fee estimator to see up-to-date fee rates (mempool.space, blockstream.info).

Compare these rates to the original fee set in the merge request.

Raising the original fee may help confirm the transaction if it is too low. If you need to free some UTXOs without raising the fee on all of them, overriding the transaction is the better option.

Call-by-Call Walkthrough

If you’ve reviewed your merge request and determined that action is needed because fees are too low or because you need to free some UTXOs, here’s how to proceed.

Option 1: Raise the Fee

If the transaction is correct and valid but stuck due to low fees, you can raise the fee using raiseFeeForMergeUtxosTransactionRequest. This keeps the transaction structure intact and increases its attractiveness to miners, helping it confirm faster.

Parameters to provide:

merge_utxos_request_id: The ID of the merge request you want to update.

transaction_serial_number: The serial number of the specific transaction in that merge request.

fee: The new (higher) fee per vbyte to pay for the transaction.

extend_replaceable_transactions_chain (optional, defaults to False): Whether the system can continue raising the fee beyond usual limits if needed. Set this to True if you want to make more than six attempts to modify this transaction.

Example call:

client.raiseFeeForMergeUtxosTransactionRequest( merge_utxos_request_id="example_request_id", transaction_serial_number=1, fee=5, extend_replaceable_transactions_chain=False )

Option 2: Override the Transaction

If raising the fee is not practical — for example, because the fee would be too high to apply to all UTXOs — you can use overrideMergeUtxosTransactionRequest. This creates a new smaller transaction with a subset of the UTXOs, using a higher fee to ensure it confirms quickly.

Once the smaller transaction confirms, the larger, original transaction will be invalidated, and any remaining UTXOs not included in the override will be unlocked and available for use.

Parameters to provide:

merge_utxos_request_id: The ID of the merge request you want to override.

transaction_serial_number: The serial number of the specific transaction to override.

fee: The new (higher) fee per vbyte for the override transaction.

extend_replaceable_transactions_chain (optional, defaults to False): Set to True if you want to allow more than the usual number of fee raises.

Example Call:

client.overrideMergeUtxosTransactionRequest( merge_utxos_request_id="example_request_id", transaction_serial_number=1, fee=7, extend_replaceable_transactions_chain=False )

Endpoint Deep Dive

retrieveAllMpcUtxosForAccount

Retrieve all MPC UTXOs for the specified coin and account.

POST

retrieveAllMpcUtxosForAccount(coin_type: str, account_id: int, specific_address_to_query: Optional[str] = None)

# Example: Retrieve all UTXOs for account ID 1 (BTC only)

client.retrieveAllMpcUtxosForAccount(
    coin_type="BTC",
    account_id=1
)

For more information about this endpoint, see retrieveAllMpcUtxosForAccount.

retrieveSingleMpcUtxoByTxIdAndVoutIndex

Retrieve information about a single MPC UTXO by specifying the coin type, transaction ID (TxId), and Vout index.

POST

retrieveSingleMpcUtxoByTxIdAndVoutIndex(coin_type: str, tx_id: str, vout_index: int)

# Example: Retrieve details for a specific UTXO identified by TxId and VoutIndex

client.retrieveSingleMpcUtxoByTxIdAndVoutIndex(
    coin_type="BTC",
    tx_id="e16b...f8d3",
    vout_index=0
)

For more information about this endpoint, see retrieveSingleMpcUtxoByTxIdAndVoutIndex.

mergeUtxos

Merge unspent transaction outputs (UTXOs) within an account to reduce wallet fragmentation and future transaction fees. The system will automatically select all UTXOs marked as "Mergeable" that fall within the defined min_amount and max_amount range. You cannot exclude specific UTXOs if they match these parameters. The system groups selected UTXOs into transactions according to the batch size you define in max_utxos_per_transaction (up to 299). If more UTXOs are available than the batch size, multiple transactions will be created under the same merge request. If fewer UTXOs remain than the batch size, they will be merged into a smaller transaction. Each transaction uses the provided fee per vbyte. If the fee exceeds the system's suggested fee, the transaction will be rejected unless allow_high_fee is set to True.

POST

mergeUtxos(coin_type: str, account_id: int, min_amount: str, max_amount: str, fee: int,max_utxos_per_transaction: int,allow_high_fee: bool = False)

# Example: Merge UTXOs in account 1, setting size and fee parameters

client.mergeUtxos(
    coin_type="BTC",
    account_id=1,
    min_amount="1",
    max_amount="1000...0000",
    fee=2,
    max_utxos_per_transaction=5,
    allow_high_fee=False
)

For more information about this endpoint, see mergeUtxos.

searchMergeUtxosRequests

Retrieve all merge UTXOs requests for a given coin type and account, optionally filtered by status and request type.

POST

searchMergeUtxosRequests(coin_type: str, account_id: int, status_keys: Optional[list] = None, type_filter: Optional[list] = None)

# Example: Search all merge UTXOs requests for account 1 on BTC
client.searchMergeUtxosRequests(
    coin_type="BTC",
    account_id=1
)

For more information about this endpoint, see searchMergeUtxosRequests.

getMergeUtxosRequestById

Retrieve a specific merge UTXOs request and view its details. The response is structured like searchMergeUtxosRequests.

POST

getMergeUtxosRequestById(merge_utxos_request_id:string)

# Example: Get details for a specific merge request by ID
client.getMergeUtxosRequestById(
    merge_utxos_request_id="0d8a...bab0"
)

For more information about this endpoint, see getMergeUtxosRequestById.

raiseFeeForMergeUtxosTransactionRequest

Raise the fee on a pending merge UTXOs transaction to help it confirm faster. This function keeps the transaction structure and UTXOs the same but increases the fee per vbyte to make the transaction more appealing to miners. You can raise the fee multiple times; if you expect to need more than six raises, use extend_replaceable_transactions_chain=True to extend the limit. The response is structured like searchMergeUtxosRequests.

POST

raiseFeeForMergeUtxosTransactionRequest(merge_utxos_request_id="0503...8c76", transaction_serial_number=1, fee=4, extend_replaceable_transactions_chain=False)

# Example: Raise the fee for a specific merge transaction to help it confirm
client.raiseFeeForMergeUtxosTransactionRequest(
    merge_utxos_request_id="0503...8c76",
    transaction_serial_number=1,
    fee=4,
    extend_replaceable_transactions_chain=False
)

For more information about this endpoint, see raiseFeeForMergeUtxosTransactionRequest.

overrideMergeUtxosTransactionRequest

Create a smaller, higher-fee transaction to replace a stuck merge transaction. Use this when a large merge transaction is unconfirmed and raising the fee is too costly. The system will select a subset of UTXOs from the original transaction and create a new high-fee transaction that is more likely to confirm quickly. Once the override transaction confirms, the remaining UTXOs from the original transaction will be freed for use. The response is structured like searchMergeUtxosRequests.

POST

overrideMergeUtxosTransactionRequest(merge_utxos_request_id: str, transaction_serial_number: int, fee: int, extend_replaceable_transactions_chain: bool = False)

# Example: Override a stuck merge transaction by sending a smaller high-fee transaction
client.overrideMergeUtxosTransactionRequest(
    merge_utxos_request_id="0d8a...bab0",
    transaction_serial_number=1,
    fee=6,
    extend_replaceable_transactions_chain=False
)

For more information about this endpoint, see overrideMergeUtxosTransactionRequest.

UTXO Management

Introduction

Summary

What is a "UTXO"

Understanding the UTXO Management Process

Limitations

Checking Your UTXOs

Detailed Process Diagram

Prerequisites

Call-by-Call Walkthrough

Merging UTXOs and Tracking the Merge Request

Detailed Process Diagram

Prerequisite Information

Internal information — from your wallet

External information — from current Bitcoin network conditions

Making a Merge Request - Call-by-Call Walkthrough

Following Up on Existing Merge Requests

Modifying a Merge Request

When to Raise the Fee

When to Override the Transaction

Raise Fee or Override: Best Practices

Detailed Decision Diagram

Prerequisite Information

Internal information — from your system

External information — from current Bitcoin network conditions

Call-by-Call Walkthrough

Option 1: Raise the Fee

Option 2: Override the Transaction

Endpoint Deep Dive

Further Reading