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.

Note: These endpoints are currently in beta and might be subject to changes.

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

PATCH

utxo_management

{vaultAccountId}

{assetId}

labels

TypeScript

const response: Promise<FireblocksResponse<AttachDetachUtxoLabelsResponse>> = fireblocks.uTXOManagementBeta.updateUtxoLabels(uTXOManagementBetaApiUpdateUtxoLabelsRequest);

curl --request PATCH \
  --url https://api.fireblocks.io/v1/utxo_management/{vaultAccountId}/{assetId}/labels \
  --header 'Content-Type: application/json' \
  --data '
{
  "utxoIdentifiers": [
    {
      "txId": "b70701f4-d7b1-4795-a8ee-b09cdb5b850e",
      "txHash": "b34f0c3ce612f1e5a5c19d6b1e6b5e3e7f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c",
      "index": 0
    }
  ],
  "labelsToAttach": [
    "cold-storage",
    "vip"
  ],
  "labelsToDetach": [
    "deprecated"
  ]
}
'

const options = {
  method: 'PATCH',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    utxoIdentifiers: [
      {
        txId: 'b70701f4-d7b1-4795-a8ee-b09cdb5b850e',
        txHash: 'b34f0c3ce612f1e5a5c19d6b1e6b5e3e7f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c',
        index: 0
      }
    ],
    labelsToAttach: ['cold-storage', 'vip'],
    labelsToDetach: ['deprecated']
  })
};

fetch('https://api.fireblocks.io/v1/utxo_management/{vaultAccountId}/{assetId}/labels', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.fireblocks.io/v1/utxo_management/{vaultAccountId}/{assetId}/labels",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'utxoIdentifiers' => [
        [
                'txId' => 'b70701f4-d7b1-4795-a8ee-b09cdb5b850e',
                'txHash' => 'b34f0c3ce612f1e5a5c19d6b1e6b5e3e7f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c',
                'index' => 0
        ]
    ],
    'labelsToAttach' => [
        'cold-storage',
        'vip'
    ],
    'labelsToDetach' => [
        'deprecated'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fireblocks.io/v1/utxo_management/{vaultAccountId}/{assetId}/labels"

	payload := strings.NewReader("{\n  \"utxoIdentifiers\": [\n    {\n      \"txId\": \"b70701f4-d7b1-4795-a8ee-b09cdb5b850e\",\n      \"txHash\": \"b34f0c3ce612f1e5a5c19d6b1e6b5e3e7f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c\",\n      \"index\": 0\n    }\n  ],\n  \"labelsToAttach\": [\n    \"cold-storage\",\n    \"vip\"\n  ],\n  \"labelsToDetach\": [\n    \"deprecated\"\n  ]\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.fireblocks.io/v1/utxo_management/{vaultAccountId}/{assetId}/labels")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"utxoIdentifiers\": [\n    {\n      \"txId\": \"b70701f4-d7b1-4795-a8ee-b09cdb5b850e\",\n      \"txHash\": \"b34f0c3ce612f1e5a5c19d6b1e6b5e3e7f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c\",\n      \"index\": 0\n    }\n  ],\n  \"labelsToAttach\": [\n    \"cold-storage\",\n    \"vip\"\n  ],\n  \"labelsToDetach\": [\n    \"deprecated\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "utxos": [
    {
      "input": {
        "txHash": "b34f0c3ce612f1e5a5c19d6b1e6b5e3e7f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c",
        "index": 0
      },
      "utxoId": "123456",
      "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
      "amount": "0.00150000",
      "status": "AVAILABLE",
      "confirmations": 6,
      "isChange": false,
      "isCoinbase": false,
      "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
    }
  ]
}

{
  "message": "Cannot label the requested UTXOs: not labellable in its current status: b70701f4-d7b1-4795-a8ee-b09cdb5b850e",
  "failures": [
    {
      "identifier": {
        "txId": "b70701f4-d7b1-4795-a8ee-b09cdb5b850e"
      },
      "reason": "NOT_LABELLABLE",
      "utxoStatus": "SPENT"
    }
  ]
}

{
  "message": "<string>",
  "code": 123
}

Headers

Idempotency-Key

string

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.

Path Parameters

vaultAccountId

string<numeric>

required

The ID of the vault account

assetId

string

required

The ID of the asset

Body

application/json

utxoIdentifiers

object[]

required

List of UTXO identifiers to apply label changes to

Required array length: 1 - 50 elements

Show child attributes

labelsToAttach

string[]

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

Required array length: 1 - 5 elements

Maximum string length: 30

Example:

["cold-storage", "vip"]

labelsToDetach

string[]

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

Required array length: 1 - 5 elements

Maximum string length: 30

Example:

["deprecated"]

Response

UTXOs with updated labels

utxos

object[]

Modified UTXOs with updated labels

Show child attributes

⌘I

TypeScript

const response: Promise<FireblocksResponse<AttachDetachUtxoLabelsResponse>> = fireblocks.uTXOManagementBeta.updateUtxoLabels(uTXOManagementBetaApiUpdateUtxoLabelsRequest);

curl --request PATCH \
  --url https://api.fireblocks.io/v1/utxo_management/{vaultAccountId}/{assetId}/labels \
  --header 'Content-Type: application/json' \
  --data '
{
  "utxoIdentifiers": [
    {
      "txId": "b70701f4-d7b1-4795-a8ee-b09cdb5b850e",
      "txHash": "b34f0c3ce612f1e5a5c19d6b1e6b5e3e7f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c",
      "index": 0
    }
  ],
  "labelsToAttach": [
    "cold-storage",
    "vip"
  ],
  "labelsToDetach": [
    "deprecated"
  ]
}
'

const options = {
  method: 'PATCH',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    utxoIdentifiers: [
      {
        txId: 'b70701f4-d7b1-4795-a8ee-b09cdb5b850e',
        txHash: 'b34f0c3ce612f1e5a5c19d6b1e6b5e3e7f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c',
        index: 0
      }
    ],
    labelsToAttach: ['cold-storage', 'vip'],
    labelsToDetach: ['deprecated']
  })
};

fetch('https://api.fireblocks.io/v1/utxo_management/{vaultAccountId}/{assetId}/labels', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.fireblocks.io/v1/utxo_management/{vaultAccountId}/{assetId}/labels",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'utxoIdentifiers' => [
        [
                'txId' => 'b70701f4-d7b1-4795-a8ee-b09cdb5b850e',
                'txHash' => 'b34f0c3ce612f1e5a5c19d6b1e6b5e3e7f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c',
                'index' => 0
        ]
    ],
    'labelsToAttach' => [
        'cold-storage',
        'vip'
    ],
    'labelsToDetach' => [
        'deprecated'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fireblocks.io/v1/utxo_management/{vaultAccountId}/{assetId}/labels"

	payload := strings.NewReader("{\n  \"utxoIdentifiers\": [\n    {\n      \"txId\": \"b70701f4-d7b1-4795-a8ee-b09cdb5b850e\",\n      \"txHash\": \"b34f0c3ce612f1e5a5c19d6b1e6b5e3e7f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c\",\n      \"index\": 0\n    }\n  ],\n  \"labelsToAttach\": [\n    \"cold-storage\",\n    \"vip\"\n  ],\n  \"labelsToDetach\": [\n    \"deprecated\"\n  ]\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.fireblocks.io/v1/utxo_management/{vaultAccountId}/{assetId}/labels")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"utxoIdentifiers\": [\n    {\n      \"txId\": \"b70701f4-d7b1-4795-a8ee-b09cdb5b850e\",\n      \"txHash\": \"b34f0c3ce612f1e5a5c19d6b1e6b5e3e7f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c\",\n      \"index\": 0\n    }\n  ],\n  \"labelsToAttach\": [\n    \"cold-storage\",\n    \"vip\"\n  ],\n  \"labelsToDetach\": [\n    \"deprecated\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "utxos": [
    {
      "input": {
        "txHash": "b34f0c3ce612f1e5a5c19d6b1e6b5e3e7f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c",
        "index": 0
      },
      "utxoId": "123456",
      "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
      "amount": "0.00150000",
      "status": "AVAILABLE",
      "confirmations": 6,
      "isChange": false,
      "isCoinbase": false,
      "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
    }
  ]
}

{
  "message": "Cannot label the requested UTXOs: not labellable in its current status: b70701f4-d7b1-4795-a8ee-b09cdb5b850e",
  "failures": [
    {
      "identifier": {
        "txId": "b70701f4-d7b1-4795-a8ee-b09cdb5b850e"
      },
      "reason": "NOT_LABELLABLE",
      "utxoStatus": "SPENT"
    }
  ]
}

{
  "message": "<string>",
  "code": 123
}

Introduction

Errors & Statuses

Data Objects

API Endpoints

Attach or detach labels to/from UTXOs

Headers

Path Parameters

Body

Response