Guides
Start typing to search…

Quick Start

Use the Smart Treasury API to automate wallet funding and ensure constant liquidity without manual intervention. This guide walks you through three key steps to get started:

  1. Add a managed balance: define the wallet you want to automate and create your liquidity sources.
  2. Configure thresholds: set rules for triggering top-ups.
  3. Assign eligible funding sources: link liquidity providers like Kraken or Binance.

Get started with Auto Treasury

Let's configure your first Smart Treasury rule:

  • I want to set up auto-treasury for my TRX balance because TRX is the currency most frequently withdrawn by customers. The balance often becomes depleted in the middle of the night or over weekends, leading to alerts for our treasury team.
  • The minimum balance of the account should be around $5k or 15,000 TRX, and the target balance should be around $50k or 150,000 TRX.
  • The liquidity sources should be:
    • My TRX balance at Kraken
    • My USDT balance at Kraken
  • The intermediary should be my TRX balance at Kraken.

Recommended approach. Create an auto top-up source first

First, create a managed balance for the TRX balance in your Layer1 wallet, for which you set up auto top-ups. As you haven’t created your liquidity sources yet, you won’t configure them yet.

You’ll define the wallet, its asset, metadata, and threshold rules. To set up this auto top-up source, do the following:

  1. Send a POST /treasury/v1/managed-balances request with the following body:

    {
    "entityCode": "Tron",
    "asset": "TRX",
    "name": "TRX master balance",
    "remoteWalletMetadata": {
        "balanceId" : " "
 				"addressId" : " "
   			"address": "0x0a36d17a33e3cb48f3ffc8bc0ae20b9927f087fe",
        "assetPoolId": "d6f49aa3-ff64-4bcd-9a5e-93219d73634a",
        "network": "TRON",
        "tag": " ",
        "type": " "	
    },
    "thresholds": {
    "minBalance": 15000,
    "warningBalance": ,
    "targetBalance": 150000,
    "minBalanceWindowWidth": ,
    "warningBalanceWindowWidth": ,
    "targetBalanceWindowWidth": ,
    "minBalanceBufferFactor": ,
    "transferOperationHardTimeout": "PT1H"
    },
    "monitoringDisabled": false,
    "forecastDisabled": false
}

  2. Create a managed balance for each of your liquidity sources.

    You can start with your TRX balance at Kraken. To do this, send a POST /treasury/v1/managed-balances request with the following body:

    {
    "entityCode": "kraken",
    "asset": "TRX",
    "name": "Kraken TRX balance",
    "remoteWalletMetadata": {
        "blockchainAddresses": [
            {
                "network": "TRON",
                "address": "0x0a36d17a33e3cb48f3ffc8bc0ae20b9927f087ab",
            }
        ]
    },
    "thresholds": {
      "minBalance": 15000,
      "targetBalance": 150000,
      "minBalanceBufferFactor": 0.2
    },
    "monitoringDisabled": false,
    "forecastDisabled": false
}

    In the response, you receive the ID for the managed balance, for example kraken_tron_trx. Save it, as you will need this value later.

  3. Repeat step 2 for your USDT balance at Kraken.
    After this procedure, you have the following liquidity sources IDs:

    • kraken_tron_trx
    • kraken_tron_usdt

  4. Link the IDs to your auto top-up balance by sending a PUT /treasury/v1/managed-balances/{id}/eligible-sources/{sourceId} request.
    In the request, specify your TRX balance (layer1_tron_trx) as the {id} and the relevant liquidity source ID, for example, PUT /treasury/v1/managed-balances/layer1_ethereum_eth/eligible-sources/kraken_tron_trx.
    Also, in the request body, you can specify the priority of the source and the intermediaries, for example:

    {  
  "intermediaries": [  
    "kraken_tron_trx"  
  ],  
  "priority": 1  
}

Now, you are set up and ready to go. Your auto-top-ups will start processing automatically once the minimum balance is reached.

Alternative approach

Alternatively, you can create liquidity sources in the first place:

  1. Create a managed balance for each of your liquidity sources, for example, ETH balance at Kraken. To do this, send a
    POST /treasury/v1/managed-balances request with the following body: 
    {  
       "entityCode": "kraken",  
       "asset": "ETH",  
       "name": "Kraken Eth balance",  
       "remoteWalletMetadata": {  
           "blockchainAddresses"[  
               {  
                   "network": "ETHEREUM",  
                   "address": "0x0a36d17a33e3cb48f3ffc8bc0ae20b9927f087ab",  
               }  
           ]  
       },  
       "thresholds": {  
       "minBalance": 10,  
       "targetBalance": 50,  
       "minBalanceBufferFactor": 0.2  
       },  
       "monitoringDisabled": false,  
       "forecastDisabled": false  
}
    In the response, you receive the id for the managed balance, for example, kraken_ethereum_eth.
  2. Repeat step 1 for your ETH balance at Binance and the USDT balance at Kraken.
  3. Create a managed balance for the ETH balance in your Layer1 Wallet, for which you initiate auto top-ups. Additionally, you can configure the liquidity sources in the priority order you have set up for this balance.
    To do this, send a POST /treasury/v1/managed-balances request with the following body: 
    {  
       "entityCode": "Ethereum",  
       "asset": "ETH",  
       "name": "ETH master balance",  
       "remoteWalletMetadata": {  
           "balanceId" : " "  
    "addressId" : " "  
    "address": "0x0a36d17a33e3cb48f3ffc8bc0ae20b9927f087fe",  
           "assetPoolId": "d6f49aa3-ff64-4bcd-9a5e-93219d73634a",  
           "network": "ETHEREUM",  
           "tag": " ",  
           "type": " "  
       },  
       "thresholds": {  
       "minBalance": 12,  
       "warningBalance": ,  
       "targetBalance": 47,  
       "minBalanceWindowWidth": ,  
       "warningBalanceWindowWidth": ,  
       "targetBalanceWindowWidth": ,  
       "minBalanceBufferFactor": ,  
       "transferOperationHardTimeout": "PT1H"  
       },  
       "monitoringDisabled": false,  
       "forecastDisabled": false  
   },  
   "eligibleSourcesAndIntermediaries": {  
       "kraken_ethereum_eth",  
       "priority": 1  
   },  
   {  
       "binance_ethereum_eth",  
       "priority": 2  
   },  
   {  
       "kraken_ethereum_usdt",  
       "priority": 3  
       "intermediaries": [  
   "kraken_ethereum_eth"  
   ]  
}

Now, you are set up and ready to go. Your auto-top-ups will start processing automatically once the minimum balance is reached.

Update thresholds

Thresholds define when the system should raise alerts or trigger balance top-ups. o update an existing managed balance’s thresholds, send the PATCH /treasury/v1/managed-balances/{id}/thresholds request with the updated parameters in the thresholds object:

"thresholds": {
        "minBalance": 5000,
        "warningBalance": 10000,
        "targetBalance": 25000,
        "minBalanceBufferFactor": 1.2
},

Threshold fields:

  • minBalance: When the balance falls below this amount, a top-up is triggered. 
  • warningBalance: Alert zone before hitting minimum.
  • targetBalance: The desired balance level after the top‑up.
  • bufferFactor: A safety margin to ensure funding sources have sufficient liquidity. The system applies this multiple to funding sources before using them.

Assign eligible funding sources

To enable automated top-ups, you must assign one or more eligible sources that can fund the wallet. For each managed balance, add eligible funding sources (for example, Kraken) by sending a PUT /treasury/v1/managed-balances/{id}/eligible-sources/{sourceId} request with the request body:

{
  "intermediaries": [
    "bvnk_ethereum_usdt"
  ],
  "priority": 2
}

Here,

  • intermediaries are third-party entities (like exchanges or managed balances) used when direct transfers aren’t possible—especially across networks. For example, to move USDT from Tron to Ethereum, an intermediary like Kraken can receive the funds on one chain and issue them on another. They can also be used on the same network for routing, compliance, or control.
  • priority is a numerical ranking of eligible sources (1 is highest). If multiple sources are eligible, the one with the lowest priority number is used first.

Trigger a Manual Top-Up

If needed, you can manually trigger a balance adjustment by sending a POST /treasury/v1/balance-adjustment request with the following body where you specify the desired amount:

{
  "requestId": "0197170c-b71d-70bc-afbe-5dd925c8620d",
  "managedBalanceId": "bvnk_tron_usdt",
  "amount": 100
}

View automated transactions

To view transactions initiated by smart treasury operations, send a GET /treasury/v1/treasury-operations request specifying the page number and page size as required.

In the response, you receive the complete list of all operations and their status.

Updated 15 days ago

What’s Next

See the following guides for more information on each section: