Select UTXOs - Fireblocks Developer Docs

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.

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

Endpoint	Description
Label UTXOs — `PATCH /utxo_management/{vaultAccountId}/{assetId}/labels`
List UTXOs — `GET /utxo_management/{vaultAccountId}/{assetId}/unspent_outputs`	Paginated, 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 /transactions`	New `utxoSelectionParams` field for server-side UTXO filtering (`filters`) and explicit UTXO picks (`inputSelection`). Endpoint reference
Estimate Transaction Fee — `POST /transactions/estimate_fee`	New `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.

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:

Call List UTXOs filtered by the customer’s address to get all their unspent outputs.
Sum the UTXO amounts to get the transfer amount.
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

Field	Used in	Description
`utxoIdentifiers`	Label UTXOs	Array identifying the UTXOs to label. Each entry is `{txHash, vout}` or `{txId}`.
`labelsToAttach`	Label UTXOs	Array of label strings to attach to the identified UTXOs.
`labelsToDetach`	Label UTXOs	Array of label strings to detach from the identified UTXOs.
`txHash / vout`	UTXO identifiers	`txHash` is the transaction hash; `vout` is the output index within that transaction. `txId` is accepted as an alternative identifier in labeling requests.
`includeAllLabels`	List UTXOs, `utxoSelectionParams.filters`	Array of labels. Matches UTXOs that carry all of the listed labels (AND logic). Use when you need every label to be present.
`includeAnyLabels`	List UTXOs, `utxoSelectionParams.filters`	Array of labels. Matches UTXOs that carry at least one of the listed labels (OR logic).
`excludeAnyLabels`	List UTXOs, `utxoSelectionParams.filters`	Array of labels. Excludes UTXOs that carry any of the listed labels.
`utxoSelectionParams`	Create Transaction	Container for UTXO selection criteria. Replaces `extraParameters.inputsSelection`.
`utxoSelectionParams.filters`	Create Transaction	Server-side filter criteria. Supported sub-fields include `address`, `minAmount`, `includeAllLabels`, and `includeAnyLabels`.
`utxoSelectionParams.inputSelection`	Create Transaction	Explicit UTXO picks. Spent first, before any filter-based selection.
`inputsToSpend`	`inputSelection`	Array of UTXOs to spend explicitly. Each entry is `{txHash, vout}`.
`fillFeeForSelectedInputs`	`inputSelection`	When `true`, Fireblocks adds more UTXOs (subject to `filters`) if the explicit selection doesn’t cover the fee. Requires at least one entry in `inputsToSpend`.

​How UTXO selection works

​API reference

​Label UTXOs

​List UTXOs

​Select UTXOs in a transaction

​Example: Send from labeled UTXOs above a minimum amount

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

​Field reference

How UTXO selection works

API reference

Label UTXOs

List UTXOs

Select UTXOs in a transaction

Example: Send from labeled UTXOs above a minimum amount

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

Field reference