Overview

UTXO blockchains support using multiple source addresses in a single transaction. When sending transactions from your Fireblocks workspace, multi-input transactions must originate from a single vault account.

By default, when creating transactions in the Fireblocks Console or API, inputs in a vault account are combined from the smallest to the largest until the requested amount and all fees are accommodated. Create transactions using the Fireblocks Console to combine address inputs that transfer the total amount requested. Create transactions using the Fireblocks API to select address inputs for new transactions either automatically or manually.

Input management

UTXO transactions created in Fireblocks are limited to 250 inputs for Bitcoin, Bitcoin Cash, Bitcoin SV, Dash, and Litecoin, 110 inputs for Cardano, and 50 inputs for ZCash. Each blockchain’s respective testnet has the same input limitations. However, in testnet workspaces that use the Fireblocks Communal API Co-Signer, all UTXO transactions are limited to 50 inputs. Learn more about the Fireblocks Communal API Co-Signer.

If you expect a high volume of incoming transactions to separate deposit addresses, you can use the Fireblocks API to manage outgoing UTXO transaction inputs manually. Each method below can be used independently of the others.

Transactions that require more inputs than the allowed amount will fail with the substatus TOO_MANY_INPUTS.

Manually select inputs for each transaction

Use the unspent inputs endpoint via the Fireblocks API to retrieve a list of unspent inputs that can be used for each UTXO transaction. Pass the specific inputs in the create a new transaction request by specifying the inputsSelection parameter within the extraParameters object. Use the ToSpend object to only use the selected inputs. The transaction will fail if the specified inputs don’t cover the requested amount.

Configure input selection

Instead of the default automatic input selection, you can switch your workspace to inverse input selection. With inverse input selection, inputs are automatically selected from largest to smallest amounts up to the maximum allowed inputs for new transactions created in the Fireblocks Console. Contact Fireblocks Support to change the input selection for your workspace.

Use the default selection method to avoid leaving small amounts of assets spread across multiple deposit addresses.

Use the inverse selection method if you frequently send large UTXO transactions and encounter transactions failing with the TOO_MANY_INPUTS substatus.

Periodically merge UTXO asset wallets

Use the maximum spendable amount API endpoint to find the maximum amount available for a single transaction from a vault account. You can then merge a UTXO asset wallet to combine the maximum available inputs into a single address output or send larger transfers as multiple transactions.

To merge multiple UTXO inputs into a single output, create a transaction using the maximum spendable amount and transfer it to an asset wallet in a different vault account in your workspace. This is an on-chain transaction that requires network fees. This allows future transactions to require significantly fewer inputs.

Merging UTXO inputs in the Fireblocks Console

For example, if a vault account has 600 Bitcoin deposit addresses, each with $2, then the largest transaction available is $500 even though the total amount held in the vault account is $1200. Using the Fireblocks Console, you can create a $500 transaction from this vault account to another vault account that will automatically select the first 250 inputs. The permanent address of the destination vault account will receive the $500 of Bitcoin in one deposit address. Create two more transactions of $500 and $200 to consolidate the $1200, minus fees, to the destination vault account.

Create a new transfer and use the one-time address feature to merge UTXO inputs into a specific deposit address in a vault account. This can be a deposit address in the same vault account as the source or a specific deposit address in a different vault account.

Merging UTXO inputs in the Fireblocks API

Find the maximum spendable amount in a single transaction. Then create a transaction using the create a new transaction endpoint and include the extraParameters field to identify the addresses in InputsSelection. Send the transaction to a single deposit address in your Vault.