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:

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

Add a managed balance

A managed balance is a wallet configured for automatic monitoring and top-ups. You’ll define the wallet, its asset, metadata, and threshold rules. Send a POST /treasury/v1/managed-balances request with the following body:

The system supports two wallet types:

LAYER1_MASTER_ADDRESS: A standard Layer1 cryptocurrency master address that consolidates all incoming deposits and serves as the primary source for withdrawals.
LAYER1_TRADE_VENUE: your balance in a connected third-party exchange, such as Binance or Kraken.

In this request, you must also specify thresholds to trigger notifications or top-ups. They determine when and how balance adjustments occur and are set in the native asset of the managed balance wallet.

{
    "entityCode": "kraken",
    "asset": "USDT",
    "name": "Main Bitcoin Wallet",
    "remoteWalletMetadata": {
        "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
        "assetPoolId": "550e8400-e29b-41d4-a716-446655440000",
        "network": "BITCOIN",
        "tag": 12345,
        "type": "LAYER1_MASTER_ADDRESS"
    },
    "thresholds": {
        "minBalance": 500000,
        "targetBalance": 1000000,
    },
    "monitoringDisabled": false,
    "forecastDisabled": false
}

{
    "entityCode": "bg",
    "asset": "USDT",
    "remoteWalletMetadata": {
        "type": "LAYER1_TRADE_VENUE",
        "managedBalanceId": "bg_kraken_usdt",
        "blockchainAddresses": [
            {
                "network": "ETHEREUM",
                "address": "0x456...",
                "valid": true
            }
        ]
    },
    "thresholds": {
        "minBalance": 20000,
        "warningBalance": 30000,
        "targetBalance": 100000
    },
    "monitoringDisabled": false,
    "forecastDisabled": false
}

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
}