UTXO Consolidation Guide

Endpoint:
POST https://api-sdk.lmnl.dev/api/wallet/consolidate-transaction

The Consolidate Transaction feature offers a streamlined approach to gather funds from various input addresses within UTXO-based chains and direct them to a specified destination wallet.

Key Points:

• Primary Use Case: Ideal for managing incoming funds on UTXO-based blockchains. It simplifies moving customer deposits from any receiving wallet to a secure wallet of your choice, often a cold wallet for added security.
• Important Pre-requisites:
  • Whitelist the target address. Refer this whitelisting guide.
  • Set an effective consolidation rule. See the Consolidation Rule Configuration Guide.
• Exchanges looking to consolidate can find detailed instructions in our Exchange Guide.

📘

Quick Navigation:

1. Bulk Consolidation with UTXO-Based Chain Wallets
2. Single Address Consolidation with UTXO-Based Chain Wallets

Bulk Consolidation with UTXO-Based Chain Wallets

The Consolidate Transaction feature facilitates the sweeping or consolidation of funds from all input addresses to a chosen destination wallet. The customisation of this process depends on the consolidation rule you've established. If no specific rule is defined, the API will adhere to Liminal's default rule parameters.

Consolidating Bitcoin to a Target Address:

Consolidation is happening from wallet id 1 for coin btc into the target address defined in the below snippet:

{  
   "wallet":{  
      "coin":"btc",  
      "walletId":1  
   },  
   "transactions":{  
      "consolidateOptions":{  
         "targetAddress":"MVXHL4BFiE1BFc98eDoL1wTSXtfcdcSLqj"  
      },  
      "sequenceId":"ca1aa351-a2d8-4dd6-9474-fd7b8b7a5ed9"  
   }  
}

📘

Key Considerations for Transaction Processing on UTXO-Based Chains

1. For UTXO-based chains, be aware that only a single webhook event will be initiated.
2. The Sequence ID acts as a critical unique identifier that is essential for the accurate tracking and processing of transactions. It is compulsory to enter the Sequence ID for processing.
3. The targetAddress refers to the destination wallet's address, which is usually a cold wallet. Make sure that this address is pre-approved and included in the whitelist.

Single Address Consolidation with UTXO-based Chain Wallets

For scenarios where consolidation from a single user deposit address is required, include the fromAddress parameter in the API call.

Consolidating from a Specific Bitcoin Address:

Example request body for consolidating from one address:

{  
   "wallet":{  
      "coin":"btc",  
      "walletId":2  
   },  
   "transactions":{  
      "consolidateOptions":{  
         "targetAddress":"MVXHL4BFiE1BFc98eDoL1wTSXtfcdcSLqj",  
         "fromAddress":"MVXHL4BFiE1BFc24eDoL2wTSXtfcdcSLqj"  
      },  
      "sequenceId":"ca1aa351-a2d8-4dd6-9474-fd7b8b7a5ed9"  
   }  
}

Setting Up Consolidation: CRON Job Example

const cron = require('node-cron');  
const axios = require('axios');

// Define the API endpoint and request body  
const API_ENDPOINT = '<https://api-sdk.lmnl.dev/api/wallet/consolidate-transaction'>;  
const REQUEST_BODY = {  
   "wallet":{  
      "coin":"btc",  
      "walletId":1  
   },  
   "transactions":{  
      "consolidateOptions":{  
         "targetAddress":"MVXHL4BFiE1BFc98eDoL1wTSXtfcdcSLqj"  
      },  
      "sequenceId":"ca1aa351-a2d8-4dd6-9474-fd7b8b7a5ed9"  
   }  
};

// Set up the CRON job to run every 15 minutes  
cron.schedule('_/15 _ \* \* \*', async () => {  
    try {  
        const response = await axios.post(API_ENDPOINT, REQUEST_BODY);  
        console.log('API called successfully:', response.data);  
    } catch (error) {  
        console.error('Error calling the API:', error);  
    }  
});

console.log('CRON job started. API will be called every 15 minutes.');

📘

Note:

The provided CRON job example for setting up consolidation is written in JavaScript. Clients may adapt this example to their preferred programming language as needed.

FAQs:

1. Why are there different examples for consolidation on UTXO and non-UTXO chains?
   The consolidation procedures for UTXO (Unspent Transaction Output) and non-UTXO blockchain networks are distinct due to the inherent differences in how transactions are handled within each type of chain.
   • In the context of UTXO chains, a Sequence ID is required to be input by the user. This is because UTXO chains permit batch transactions within a single transaction, and the Sequence ID is crucial for identifying and tracking each unique transaction within the batch.
   • For non-UTXO chains, the user does not need to input a Sequence ID. Instead, the API call will automatically append a Sequence ID internally. Non-UTXO chains do not support batch transactions in the same way; transactions must be processed individually, necessitating a loop through each transaction separately.
2. Do we require gas station for UTXO chain? If not, then where does gas fee comes from?
   We don't require Gas Station for UTXO chains, the gas fee is deducted from wallet itself.