---
title: "Attach or detach labels to/from UTXOs"
method: PATCH
path: "/utxo_management/{vaultAccountId}/{assetId}/labels"
tags: ["UTXO Management"]
---

# Attach or detach labels to/from UTXOs

`PATCH /utxo_management/{vaultAccountId}/{assetId}/labels`

## Request

- Base URL: `https://api.fireblocks.io/v1`
- URL: `https://api.fireblocks.io/v1/utxo_management/{vaultAccountId}/{assetId}/labels`
- Auth: none declared
- TypeScript: <https://skmtc.dev/fireblocks/apis/fireblocks-api/docs/utxo_management/:vaultAccountId/:assetId/labels/patch.ts> (a function with typed inputs; its response is checked against the schema)

Attach or detach labels to/from UTXOs in a vault account. Labels can be
used for organizing and filtering UTXOs.

Labels are applied additively — `labelsToAttach` adds to the existing
label set and `labelsToDetach` removes from it. Neither operation
replaces the full set.

The request is all-or-nothing: if any identifier cannot be labelled, no
UTXO is labelled and the request fails with `400`. The response lists
every failed identifier in `failures`, each with its own `reason` — use
it, not the status, to decide what to do:
- `NOT_FOUND` — not found in this vault and asset.
- `NOT_LABELLABLE` — spent, or removed, and can no longer be labelled.

A UTXO removed within the last hour is reported as `NOT_FOUND` with
`utxoStatus: REMOVED`; if it does not reappear, it becomes
`NOT_LABELLABLE` after about an hour. A `400` without `failures` means
the request itself is malformed.

Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver,
Editor.

## Path parameters

- `vaultAccountId` string, numeric, required
- `assetId` string, required

## Headers

- `Idempotency-Key` string

## Request body

- AttachDetachUtxoLabelsRequest
  - `utxoIdentifiers` UtxoIdentifier[], required: List of UTXO identifiers to apply label changes to
    - `txId` string: Fireblocks transaction ID
    - `txHash` string: On-chain transaction hash, in lowercase hex as the chain reports it. Matched case-sensitively, so an uppercase hash is never found.
    - `index` integer: Output index (vout)
  - `labelsToAttach` string[]: Labels to attach to the specified UTXOs. At least one of labelsToAttach or labelsToDetach must be provided.
  - `labelsToDetach` string[]: Labels to detach from the specified UTXOs. At least one of labelsToAttach or labelsToDetach must be provided.

## Response `200`

UTXOs with updated labels

- AttachDetachUtxoLabelsResponse
  - `utxos` UtxoOutput[]: Modified UTXOs with updated labels
    - `input` UtxoInput2, required
      - `txHash` string: The transaction hash
      - `index` integer: The output index (vout)
    - `utxoId` string, required: The unique UTXO identifier
    - `address` string, required: The address holding this UTXO
    - `amount` string, required: The UTXO amount in the asset's native unit
    - `confirmations` integer: Number of confirmations
    - `status` 'PENDING' | 'AVAILABLE' | 'FROZEN' | 'SELECTED', required: The UTXO status
    - `isChange` boolean: Whether this is a change output
    - `isCoinbase` boolean: Whether this is a coinbase output
    - `fbTxId` string: The Fireblocks transaction ID that created this UTXO
    - `createdByHash` string: The on-chain block hash where this UTXO was created
    - `spentByFbTxId` string[]: Fireblocks transaction IDs that selected/spent this UTXO
    - `createdByHeight` integer: The block height at which this UTXO was created
    - `createdAt` string, date-time: The timestamp when this UTXO was created
    - `updatedAt` string, date-time: The timestamp when this UTXO was last updated
    - `labels` string[]: Labels attached to this UTXO
    - `hasNativeAssets` boolean: Whether this UTXO carries Cardano native assets (tokens)

## Other responses

- `400`: Some identifiers could not be labelled (listed in `failures`), or the request is malformed. No UTXO was labelled.
- `default`: Error Response

---

[API](https://skmtc.dev/fireblocks/apis/fireblocks-api.md) - [All operations](https://skmtc.dev/fireblocks/apis/fireblocks-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fireblocks/apis/fireblocks-api/revisions/4eba9965659a?raw)