Multi-input transactions

Fireblocks selects UTXO transaction inputs automatically by default. You can also manage input selection manually to handle high-volume workspaces.

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

By default, when you create transactions in the Fireblocks Console or API, the platform combines inputs in a vault account from the smallest to the largest until the requested amount and all fees are covered. In the Fireblocks Console, the platform automatically selects address inputs that transfer the total amount requested. In the Fireblocks API, you can select address inputs for new transactions either automatically or manually.

When creating a transaction in the Fireblocks Console, you can select Max to transfer the total amount of the selected asset using the available inputs.

Input management

Fireblocks limits the number of inputs per UTXO transaction based on the blockchain.

Each blockchain's testnet has the same input limits as its mainnet. The exception is testnet workspaces using the Fireblocks Communal API Co-signer, where the platform limits all UTXO transactions to 50 inputs.

Transactions that require more inputs than the limit fail with the TOO_MANY_INPUTS substatus.

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

Manually select inputs for each transaction

Use the Get UTXO unspent inputs information endpoint to retrieve a list of unspent inputs available for a UTXO transaction. Pass the specific inputs in the Create transactions endpoint by specifying the inputsSelection parameter inside the extraParameters object. Use the ToSpend object to use only the selected inputs. The transaction fails if the specified inputs don't cover the requested amount.

Configure input selection

Instead of the default smallest-to-largest input selection, you can switch your workspace to inverse input selection. With inverse input selection, the platform selects inputs from largest to smallest, up to the maximum allowed inputs for new transactions created in the Fireblocks Console. To change the input selection method for your workspace, contact Fireblocks Support.

Consolidate UTXO inputs

Before sending a large UTXO transfer, use the Get max spendable amount in a transaction endpoint to check the largest amount available in a single transaction from a vault account. If the maximum spendable amount is less than the amount you want to transfer, either consolidate the available inputs into a single output or send the transfer 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, either in the same vault account or in a different one. This is an on-chain transaction that requires network fees. Once merged, future transactions require fewer inputs.

Consolidate UTXO inputs in the Fireblocks Console

For example, if a vault account has 600 Bitcoin deposit addresses each holding 0.002 BTC, the largest available single transaction is 0.5 BTC even though the vault account holds 1.2 BTC total. From the Fireblocks Console, you can create a 0.5 BTC transaction from this vault account to another vault account; the platform automatically selects the first 250 inputs. The permanent deposit address of the destination vault account receives the 0.5 BTC in a single deposit address. Create two more transactions of 0.5 BTC and 0.2 BTC to consolidate the remaining 1.2 BTC, minus fees, to the destination vault account.

To merge UTXO inputs, create a new transfer to a specific deposit address. You can either whitelist a vault deposit address or use a One-Time Address (OTA). The deposit address can be in the same vault account as the source or in a different vault account.

Consolidate UTXO inputs in the Fireblocks API

Find the maximum spendable amount available in a single transaction. Then create a transaction using the Create Transactions endpoint and include the extraParameters field to identify the addresses in inputsSelection. Send the transaction to a single deposit address in your vault account.