consolidate_utxos
consolidate_utxos coin merge_conditions
The consolidate_utxos method consolidates unspent transaction outputs (UTXOs) for a specified UTXO-based coin. This operation helps optimize transaction efficiency by reducing wallet fragmentation and lowering the number of UTXOs, which can improve transaction creation speed and reduce fees.
Arguments
| Structure | Type | Description |
|---|---|---|
| coin | string | The name of the UTXO-based coin to consolidate |
| merge_conditions | object | Optional. Configuration object for consolidation behavior |
| merge_conditions.merge_at | integer | Optional. Minimum number of lone UTXOs that triggers automatic consolidation. Default: 100 |
| merge_conditions.max_merge_at_once | integer | Optional. Maximum number of UTXOs to merge in a single transaction. Default: 50 |
Response
| Structure | Type | Description |
|---|---|---|
| tx_hash | string | The hash of the consolidation transaction |
| tx_hex | string | The raw transaction hex that can be broadcast using send_raw_transaction |
| from | array of strings | Source addresses (UTXOs) that were consolidated |
| to | array of strings | Destination address where consolidated funds were sent |
| total_amount | string (numeric) | Total amount consolidated |
| spent_by_me | string (numeric) | Total amount spent including fees |
| received_by_me | string (numeric) | Amount received after consolidation |
| my_balance_change | string (numeric) | Net balance change (typically negative due to transaction fees) |
| fee_details | object | Fee information for the consolidation transaction |
| coin | string | The coin that was consolidated |
| utxos_merged | integer | Number of UTXOs that were successfully merged |
📌 Examples
Basic UTXO Consolidation
POST consolidate_utxos
{
"userpass": "RPC_UserP@SSW0RD",
"method": "consolidate_utxos",
"coin": "KMD"
}curl --url "http://127.0.0.1:7783" --data '{
"userpass": "RPC_UserP@SSW0RD",
"method": "consolidate_utxos",
"coin": "KMD"
}'import requests
import json
url = "http://127.0.0.1:7783"
payload = {
"userpass": "RPC_UserP@SSW0RD",
"method": "consolidate_utxos",
"coin": "KMD"
}
response = requests.post(url, json=payload)
print(json.dumps(response.json(), indent=2))const payload = {
"userpass": "RPC_UserP@SSW0RD",
"method": "consolidate_utxos",
"coin": "KMD"
};
const response = await fetch("http://127.0.0.1:7783", {
method: "POST",
body: JSON.stringify(payload),
});
console.log(await response.json());<?php
$payload = <<<'JSON'
{
"userpass": "RPC_UserP@SSW0RD",
"method": "consolidate_utxos",
"coin": "KMD"
}
JSON;
$ch = curl_init("http://127.0.0.1:7783");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;package main
import (
"bytes"
"fmt"
"io"
"net/http"
)
func main() {
payload := []byte(`{"userpass":"RPC_UserP@SSW0RD","method":"consolidate_utxos","coin":"KMD"}`)
resp, err := http.Post("http://127.0.0.1:7783", "application/json", bytes.NewBuffer(payload))
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}require 'net/http'
require 'json'
require 'uri'
uri = URI("http://127.0.0.1:7783")
payload = {
"userpass": "RPC_UserP@SSW0RD",
"method": "consolidate_utxos",
"coin": "KMD"
}
response = Net::HTTP.post(uri, payload.to_json, 'Content-Type' => 'application/json')
puts JSON.pretty_generate(JSON.parse(response.body))Show Response
Response (success)
{
"tx_hash": "7e0e1b0c8a2f1d9e3c4b5a6789012345678901234567890123456789abcdef01",
"tx_hex": "0400008085202f890312345...abcdef",
"from": [
"RGVd8VTPgKXWo9JGjUSdkkDKFzCUKKXVDJ",
"RGVd8VTPgKXWo9JGjUSdkkDKFzCUKKXVDJ",
"RGVd8VTPgKXWo9JGjUSdkkDKFzCUKKXVDJ"
],
"to": [
"RGVd8VTPgKXWo9JGjUSdkkDKFzCUKKXVDJ"
],
"total_amount": "15.75",
"spent_by_me": "15.75001",
"received_by_me": "15.74999",
"my_balance_change": "-0.00001",
"fee_details": {
"type": "Utxo",
"amount": "0.00001"
},
"coin": "KMD",
"utxos_merged": 25
}UTXO Consolidation with Custom Merge Conditions
POST consolidate_utxos
{
"userpass": "RPC_UserP@SSW0RD",
"method": "consolidate_utxos",
"coin": "BTC",
"merge_conditions": {
"merge_at": 50,
"max_merge_at_once": 25
}
}curl --url "http://127.0.0.1:7783" --data '{
"userpass": "RPC_UserP@SSW0RD",
"method": "consolidate_utxos",
"coin": "BTC",
"merge_conditions": {
"merge_at": 50,
"max_merge_at_once": 25
}
}'import requests
import json
url = "http://127.0.0.1:7783"
payload = {
"userpass": "RPC_UserP@SSW0RD",
"method": "consolidate_utxos",
"coin": "BTC",
"merge_conditions": {
"merge_at": 50,
"max_merge_at_once": 25
}
}
response = requests.post(url, json=payload)
print(json.dumps(response.json(), indent=2))const payload = {
"userpass": "RPC_UserP@SSW0RD",
"method": "consolidate_utxos",
"coin": "BTC",
"merge_conditions": {
"merge_at": 50,
"max_merge_at_once": 25
}
};
const response = await fetch("http://127.0.0.1:7783", {
method: "POST",
body: JSON.stringify(payload),
});
console.log(await response.json());<?php
$payload = <<<'JSON'
{
"userpass": "RPC_UserP@SSW0RD",
"method": "consolidate_utxos",
"coin": "BTC",
"merge_conditions": {
"merge_at": 50,
"max_merge_at_once": 25
}
}
JSON;
$ch = curl_init("http://127.0.0.1:7783");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;package main
import (
"bytes"
"fmt"
"io"
"net/http"
)
func main() {
payload := []byte(`{"userpass":"RPC_UserP@SSW0RD","method":"consolidate_utxos","coin":"BTC","merge_conditions":{"merge_at":50,"max_merge_at_once":25}}`)
resp, err := http.Post("http://127.0.0.1:7783", "application/json", bytes.NewBuffer(payload))
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}require 'net/http'
require 'json'
require 'uri'
uri = URI("http://127.0.0.1:7783")
payload = {
"userpass": "RPC_UserP@SSW0RD",
"method": "consolidate_utxos",
"coin": "BTC",
"merge_conditions": {
"merge_at": 50,
"max_merge_at_once": 25
}
}
response = Net::HTTP.post(uri, payload.to_json, 'Content-Type' => 'application/json')
puts JSON.pretty_generate(JSON.parse(response.body))Show Response
Response (success)
{
"tx_hash": "8f1f2e3d4c5b6a7890123456789012345678901234567890123456789abcdef02",
"tx_hex": "0100000012345...abcdef",
"from": [
"1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
"1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
],
"to": [
"1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
],
"total_amount": "0.5",
"spent_by_me": "0.50001",
"received_by_me": "0.49999",
"my_balance_change": "-0.00001",
"fee_details": {
"type": "Utxo",
"amount": "0.00001"
},
"coin": "BTC",
"utxos_merged": 25
}Response (error - coin not activated)
Show Response
{
"error": "rpc:174] dispatcher_legacy:155] lp_coins:1668] Coin BTC is not activated"
}Response (error - insufficient UTXOs to consolidate)
Show Response
{
"error": "Not enough UTXOs to consolidate. Current UTXO count: 5, minimum required: 50"
}Response (error - non-UTXO coin)
Show Response
{
"error": "UTXO consolidation is not supported for ETH. This method only works with UTXO-based coins."
}Additional Notes
-
Transaction Broadcasting: The
consolidate_utxosmethod only creates the consolidation transaction. You must use thesend_raw_transactionmethod to broadcast the transaction to the network. -
Fee Optimization: Consolidating UTXOs can reduce future transaction fees by minimizing the number of inputs required for subsequent transactions.
-
Timing Considerations: It’s generally best to consolidate UTXOs during periods of low network congestion to minimize transaction fees.
-
Privacy Impact: Consolidation transactions can link multiple addresses/UTXOs together, which may impact privacy. Consider this when deciding whether to consolidate.
-
Automatic Triggering: If you don’t specify
merge_conditions, the default behavior will trigger consolidation when you have 100 or more UTXOs, merging up to 50 at once.