FIfireblocks
UTXO Management

Attach or detach labels to/from UTXOs

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.

patch/utxo_management/{vaultAccountId}/{assetId}/labels

Request

Path parameters

vaultAccountIdstring numeric required

The ID of the vault account

assetIdstring required

The ID of the asset

Headers

Idempotency-Keystring

A unique identifier for the request. If the request is sent multiple times with the same idempotency key, the server will return the same response as the first request. The idempotency key is valid for 24 hours.

Request body

labelsToAttachstring[]

Labels to attach to the specified UTXOs. At least one of labelsToAttach or labelsToDetach must be provided.

labelsToDetachstring[]

Labels to detach from the specified UTXOs. At least one of labelsToAttach or labelsToDetach must be provided.

Example request

{
  "utxoIdentifiers": [
    {
      "txId": "b70701f4-d7b1-4795-a8ee-b09cdb5b850e",
      "txHash": "b34f0c3ce612f1e5a5c19d6b1e6b5e3e7f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c"
    }
  ],
  "labelsToAttach": [
    "cold-storage",
    "vip"
  ],
  "labelsToDetach": [
    "deprecated"
  ]
}

Response

UTXOs with updated labels

Example response

{
  "utxos": [
    {
      "input": {
        "txHash": "b34f0c3ce612f1e5a5c19d6b1e6b5e3e7f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c"
      },
      "utxoId": "123456",
      "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
      "amount": "0.00150000",
      "confirmations": 6,
      "status": "AVAILABLE",
      "fbTxId": "b70701f4-d7b1-4795-a8ee-b09cdb5b850e",
      "createdByHash": "000000000000000000024bead8df69990852c202db0e0097c1a12ea637d7e96d",
      "spentByFbTxId": [
        "b70701f4-d7b1-4795-a8ee-b09cdb5b850e"
      ],
      "createdByHeight": 800100,
      "createdAt": "2025-01-16T15:45:00Z",
      "updatedAt": "2025-01-16T15:45:00Z",
      "labels": [
        "cold-storage",
        "vip"
      ],
      "hasNativeAssets": true
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.