Skip to main content
Manual UTXO selection lets you control which unspent transaction outputs (UTXOs) are spent in a transaction, instead of relying on the default selection logic. Use it to send only from UTXOs that match criteria such as label, amount, or address, or to manage funds across multiple clients with precision.
Note: Beta endpoints — The UTXO labeling and listing endpoints, and the utxoSelectionParams field on Create Transaction, are in beta and may change. Supported assets: BTC, LTC, DOGE, BCH. To request access, contact your Customer Success Manager.

​
How UTXO selection works

UTXO selection has three building blocks. You can use them independently or in combination:
  • Labels are arbitrary strings you attach to UTXOs (for example, client-a or counterparty). You can use them later as filter criteria.
  • Filters narrow a set of UTXOs by label, amount, address, and other attributes. Filters work both in the listing endpoint and inside utxoSelectionParams when you create a transaction.
  • Explicit selection lets you specify exact UTXOs to spend by txHash and vout.
When you create a transaction with utxoSelectionParams, you can pass either filters, an explicit selection, or both. When you pass both, Fireblocks spends the explicit picks first and uses filters to select any additional UTXOs needed to cover the fee, if fillFeeForSelectedInputs is set to true.

​
API reference

EndpointDescription
Label UTXOs — PATCH /utxo_management/{vaultAccountId}/{assetId}/labels
List UTXOs — GET /utxo_management/{vaultAccountId}/{assetId}/unspent_outputsPaginated, filterable listing of unspent outputs. Filter by labels, amount range, address, status, change/coinbase. Default page size 50, max 250. Endpoint reference
Create Transaction — POST /transactionsNew utxoSelectionParams field for server-side UTXO filtering (filters) and explicit UTXO picks (inputSelection). Endpoint reference
Estimate Transaction Fee — POST /transactions/estimate_feeNew utxoSelectionParams field for server-side UTXO filtering (filters) and explicit UTXO picks (inputSelection). Endpoint reference

​
Label UTXOs

Attach or detach labels by identifying UTXOs with {txHash, vout} or {txId}. 
import { Fireblocks } from "@fireblocks/ts-sdk";

const fireblocks = new Fireblocks();

await fireblocks.utxoManagementBeta.updateUtxoLabels({
  vaultAccountId: "0",
  assetId: "BTC",
  attachDetachUtxoLabelsRequest: {
    utxoIdentifiers: [{ txHash: "abc123...def", vout: 0 }],
    labelsToAttach: ["counterparty"],
  },
});

​
List UTXOs

Retrieve a paginated list of unspent outputs for a vault account and asset. Filter by labels, amount range, address, status, and change/coinbase. 
const { data: utxoList } = await fireblocks.utxoManagementBeta.getUtxos({
  vaultAccountId: "0",
  assetId: "BTC",
  includeAnyLabels: ["counterparty"],
});

utxoList.data.forEach((utxo) => {
  console.log(utxo.input.txHash, utxo.input.index, utxo.amount, utxo.address);
});

​
Select UTXOs in a transaction

The utxoSelectionParams field on Create Transaction has two subfields:
  • filters — server-side filter criteria. Fireblocks selects UTXOs that match.
  • inputSelection — an explicit list of UTXOs to spend. Set fillFeeForSelectedInputs: true to let Fireblocks add more UTXOs (subject to filters) if the selected inputs don’t cover the fee.
Note: utxoSelectionParams replaces the previous extraParameters.inputsSelection field. You can still use extraParameters.inputsSelection in requests, but you cannot use both fields together or the transaction will fail.

​
Example: Send from labeled UTXOs above a minimum amount

When you manage funds for multiple clients using labels, you can send from UTXOs labeled for specific clients without picking them manually. Filters alone are enough — Fireblocks selects matching UTXOs that cover the transaction amount. 
import { Fireblocks, TransferPeerPathType } from "@fireblocks/ts-sdk";

const fireblocks = new Fireblocks();

const { data: tx } = await fireblocks.transactions.createTransaction({
  transactionRequest: {
    assetId: "BTC",
    amount: "0.5",
    source: { type: TransferPeerPathType.VaultAccount, id: "0" },
    destination: {
      type: TransferPeerPathType.OneTimeAddress,
      oneTimeAddress: { address: "bc1q..." },
    },
    utxoSelectionParams: {
      filters: {
        includeAnyLabels: ["client-a", "client-b"],
        minAmount: "0.1",
      },
    },
  },
});

​
Example: Drain a specific address and pay fees from another address (same vault)

A common pattern for omnibus vault operators: transfer the full balance of a specific customer address and have the network fee paid by a different address in the same vault (a dedicated “gas station” address). This keeps the customer’s transaction clean on the block explorer — no extra fee-related transfers. The flow:
  1. Call List UTXOs filtered by the customer’s address to get all their unspent outputs.
  2. Sum the UTXO amounts to get the transfer amount.
  3. Call Create Transaction with inputsToSpend set to those UTXOs and fillFeeForSelectedInputs: true. Fireblocks automatically picks additional UTXOs from other addresses in the vault to cover the fee.
Optionally, use filters to restrict which UTXOs Fireblocks can pick for fee coverage (for example, only UTXOs labeled gas-station). 
import { Fireblocks, TransferPeerPathType } from "@fireblocks/ts-sdk";

const fireblocks = new Fireblocks();

const VAULT_ID = "0";
const ASSET_ID = "BTC";
const CUSTOMER_ADDRESS = "bc1q...customer";
const DESTINATION_ADDRESS = "bc1q...destination";

// Step 1: List all UTXOs for the customer's address
const { data: utxoList } = await fireblocks.utxoManagementBeta.getUtxos({
  vaultAccountId: VAULT_ID,
  assetId: ASSET_ID,
  address: CUSTOMER_ADDRESS,
  pageSize: 250,
});

const utxos = utxoList.data;
if (!utxos || utxos.length === 0) {
  throw new Error(`No UTXOs found for address ${CUSTOMER_ADDRESS}`);
}

// Step 2: Calculate total amount and build inputsToSpend
const totalAmount = utxos
  .reduce((sum, u) => sum + parseFloat(u.amount), 0)
  .toString();

const inputsToSpend = utxos.map((u) => ({
  txHash: u.input.txHash,
  vout: u.input.index,
}));

// Step 3: Create transaction — drain the address, fee paid by other UTXOs in the vault
const { data: tx } = await fireblocks.transactions.createTransaction({
  transactionRequest: {
    assetId: ASSET_ID,
    amount: totalAmount,
    source: { type: TransferPeerPathType.VaultAccount, id: VAULT_ID },
    destination: {
      type: TransferPeerPathType.OneTimeAddress,
      oneTimeAddress: { address: DESTINATION_ADDRESS },
    },
    utxoSelectionParams: {
      inputSelection: {
        inputsToSpend,
        fillFeeForSelectedInputs: true,
      },
      // Optional: restrict fee-covering UTXOs to a labeled pool
      // filters: { includeAllLabels: ["gas-station"] },
    },
  },
});

console.log(`Transaction ${tx.id} — status: ${tx.status}`);
Key points:
  • fillFeeForSelectedInputs: true tells Fireblocks to use the specified UTXOs for the transfer amount, and to automatically select additional UTXOs from the vault to cover the network fee.
  • Without this flag, if the specified UTXOs don’t have enough to cover both the amount and the fee, the transaction fails.

​
Field reference

FieldUsed inDescription
utxoIdentifiersLabel UTXOsArray identifying the UTXOs to label. Each entry is {txHash, vout} or {txId}.
labelsToAttachLabel UTXOsArray of label strings to attach to the identified UTXOs.
labelsToDetachLabel UTXOsArray of label strings to detach from the identified UTXOs.
txHash / voutUTXO identifierstxHash is the transaction hash; vout is the output index within that transaction. txId is accepted as an alternative identifier in labeling requests.
includeAllLabelsList UTXOs, utxoSelectionParams.filtersArray of labels. Matches UTXOs that carry all of the listed labels (AND logic). Use when you need every label to be present.
includeAnyLabelsList UTXOs, utxoSelectionParams.filtersArray of labels. Matches UTXOs that carry at least one of the listed labels (OR logic).
excludeAnyLabelsList UTXOs, utxoSelectionParams.filtersArray of labels. Excludes UTXOs that carry any of the listed labels.
utxoSelectionParamsCreate TransactionContainer for UTXO selection criteria. Replaces extraParameters.inputsSelection.
utxoSelectionParams.filtersCreate TransactionServer-side filter criteria. Supported sub-fields include address, minAmount, includeAllLabels, and includeAnyLabels.
utxoSelectionParams.inputSelectionCreate TransactionExplicit UTXO picks. Spent first, before any filter-based selection.
inputsToSpendinputSelectionArray of UTXOs to spend explicitly. Each entry is {txHash, vout}.
fillFeeForSelectedInputsinputSelectionWhen true, Fireblocks adds more UTXOs (subject to filters) if the explicit selection doesn’t cover the fee. Requires at least one entry in inputsToSpend.