Manage Balances

This guide provide a detailed description of all operations involving managed balances.

In Layer1, a manages balance wallet is always a master wallet.

List all managed balances

To list all managed balances, send a GET /treasury/v1/managed-balances request.

In the response, you receive the complete list of detailed balances:

Example Response: 200 OK

{
    "content": [
        {
            "id": "bvnk_tron_usdt",
            "name": "Main USDT Wallet",
            "remoteWalletMetadata": {
                "balanceId": "550e8400-e29b-41d4-a716-446655440000",
                "addressId": "550e8400-e29b-41d4-a716-446655440000",
                "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
                "assetPoolId": "550e8400-e29b-41d4-a716-446655440000",
                "network": "TRON",
                "tag": 12345,
                "type": "LAYER1_MASTER_ADDRESS"
            },
            "eligibleSourcesAndIntermediaries": {
                "bvnk_ethereum_usdt": [
                    "bvnk_tron_usdt"
                ],
                "bvnk_kraken_btc": []
            },
            "thresholds": {
                "minBalance": 500000,
                "warningBalance": 800000,
                "targetBalance": 1000000,
                "minBalanceWindowWidth": 2,
                "warningBalanceWindowWidth": 3,
                "targetBalanceWindowWidth": 6,
                "minBalanceBufferFactor": 0.2,
                "transferOperationHardTimeout": "PT1H"
            },
            "monitoringEnabled": true,
            "forecastEnabled": true
        }
    ],
    "totalElements": 1,
    "totalPages": 1,
    "pageNumber": 0,
    "pageSize": 50
}

Parameter	Required	Description
pageNumber	✓	Page index (starts at 0).
pageSize	✓	Number of items per page (minimum 1, default 50).

---

Create a managed balance

To create a managed balance, send a POST /treasury/v1/managed-balances request with JSON body:

Example Body Parameters

{
  "entityCode": "kraken",
  "asset": "USDT",
  "name": "Main Bitcoin Wallet",
  "remoteWalletMetadata": {
    "balanceId": "550e8400-e29b-41d4-a716-446655440000",
    "addressId": "550e8400-e29b-41d4-a716-446655440000",
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "assetPoolId": "550e8400-e29b-41d4-a716-446655440000",
    "network": "BITCOIN",
    "tag": 12345,
    "type": "LAYER1_MASTER_ADDRESS"
  },
  "thresholds": {
    "minBalance": 500000,
    "warningBalance": 800000,
    "targetBalance": 1000000,
    "minBalanceWindowWidth": 2,
    "warningBalanceWindowWidth": 3,
    "targetBalanceWindowWidth": 6,
    "minBalanceBufferFactor": 0.2,
    "transferOperationHardTimeout": "PT1H"
  },
  "monitoringDisabled": false,
  "forecastDisabled": false
}

📘

Thresholds are denominated in the asset of the wallet. Here, in USDT (as in the asset field).

In the response, you receive the detailed information on the new managed balance:

Example Response

{
  "id": "bvnk_tron_usdt",
  "name": "Main USDT Wallet",
  "remoteWalletMetadata": {
    "balanceId": "550e8400-e29b-41d4-a716-446655440000",
    "addressId": "550e8400-e29b-41d4-a716-446655440000",
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "assetPoolId": "550e8400-e29b-41d4-a716-446655440000",
    "network": "TRON",
    "tag": 12345,
    "type": "LAYER1_MASTER_ADDRESS"
  },
  "eligibleSourcesAndIntermediaries": {
    "bvnk_ethereum_usdt": [
      "bvnk_tron_usdt"
    ],
    "bvnk_kraken_btc": []
  },
  "thresholds": {
    "minBalance": 500000,
    "warningBalance": 800000,
    "targetBalance": 1000000,
    "minBalanceWindowWidth": 2,
    "warningBalanceWindowWidth": 3,
    "targetBalanceWindowWidth": 6,
    "minBalanceBufferFactor": 0.2,
    "transferOperationHardTimeout": "PT1H"
  },
  "monitoringEnabled": true,
  "forecastEnabled": true
}

---

Get details of a specific managed balance

To retrieve details of a specific managed balance, send a
GET /treasury/v1/managed-balances/{managedBalanceId} request with path parameter:

Parameter	Required	Description
managedBalanceId	✓	Unique ID of the managed balance.

In the response, you receive the detailed information on the wallet:

Example Response: 200 OK

{
  "id": "bvnk_tron_usdt",
  "name": "Main USDT Wallet",
  "remoteWalletMetadata": {
    "balanceId": "550e8400-e29b-41d4-a716-446655440000",
    "addressId": "550e8400-e29b-41d4-a716-446655440000",
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "assetPoolId": "550e8400-e29b-41d4-a716-446655440000",
    "network": "TRON",
    "tag": 12345,
    "type": "LAYER1_MASTER_ADDRESS"
  },
  "eligibleSourcesAndIntermediaries": {
    "bvnk_ethereum_usdt": [
      "bvnk_tron_usdt"
    ],
    "bvnk_kraken_btc": []
  },
  "thresholds": {
    "minBalance": 500000,
    "warningBalance": 800000,
    "targetBalance": 1000000,
    "minBalanceWindowWidth": 2,
    "warningBalanceWindowWidth": 3,
    "targetBalanceWindowWidth": 6,
    "minBalanceBufferFactor": 0.2,
    "transferOperationHardTimeout": "PT1H"
  },
  "monitoringEnabled": true,
  "forecastEnabled": true
}

---

Update an existing managed balance

To update the parameters of an existing managed balance (for example, change thresholds or source of funds), send a PUT /treasury/v1/managed-balances/{managedBalanceId} request with balance's managedBalanceId in the path and the following body parameters:

Path parameter	Required	Description
managedBalanceId	✓	Unique ID of the managed balance.

Example Body Parameters

{
  "name": "Main Bitcoin Wallet",
  "remoteWalletMetadata": {
    "balanceId": "550e8400-e29b-41d4-a716-446655440000",
    "addressId": "550e8400-e29b-41d4-a716-446655440000",
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "assetPoolId": "550e8400-e29b-41d4-a716-446655440000",
    "network": "BITCOIN",
    "tag": 12345,
    "type": "LAYER1_MASTER_ADDRESS"
  },
  "thresholds": {
    "minBalance": 500000,
    "warningBalance": 800000,
    "targetBalance": 1000000,
    "minBalanceWindowWidth": 2,
    "warningBalanceWindowWidth": 3,
    "targetBalanceWindowWidth": 6,
    "minBalanceBufferFactor": 0.2,
    "transferOperationHardTimeout": "PT1H"
  },
  "monitoringDisabled": false,
  "forecastDisabled": false
}

In the response, you receive the updated information on the managed balance.

Example Response

{
  "id": "bvnk_tron_usdt",
  "name": "Main USDT Wallet",
  "remoteWalletMetadata": {
    "balanceId": "550e8400-e29b-41d4-a716-446655440000",
    "addressId": "550e8400-e29b-41d4-a716-446655440000",
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "assetPoolId": "550e8400-e29b-41d4-a716-446655440000",
    "network": "TRON",
    "tag": 12345,
    "type": "LAYER1_MASTER_ADDRESS"
  },
  "eligibleSourcesAndIntermediaries": {
    "bvnk_ethereum_usdt": [
      "bvnk_tron_usdt"
    ],
    "bvnk_kraken_btc": []
  },
  "thresholds": {
    "minBalance": 500000,
    "warningBalance": 800000,
    "targetBalance": 1000000,
    "minBalanceWindowWidth": 2,
    "warningBalanceWindowWidth": 3,
    "targetBalanceWindowWidth": 6,
    "minBalanceBufferFactor": 0.2,
    "transferOperationHardTimeout": "PT1H"
  },
  "monitoringEnabled": true,
  "forecastEnabled": true
}

---

Update thresholds for a managed balance

To update thresholds only, send a PATCH /treasury/v1/managed-balances/{id}/thresholds request with the balance's managedBalanceId in the path and the following body parameters:

Example Body Parameters

{
  "minBalance": 12000,
  "warningBalance": 18000,
  "targetBalance": 60000,
  "minBalanceBufferFactor": 1.5
}

In the response, you receive the updated information on the wallet:

Example Response

{
  "id": "bvnk_tron_usdt",
  "name": "Main USDT Wallet",
  "remoteWalletMetadata": {
    "balanceId": "550e8400-e29b-41d4-a716-446655440000",
    "addressId": "550e8400-e29b-41d4-a716-446655440000",
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "assetPoolId": "550e8400-e29b-41d4-a716-446655440000",
    "network": "TRON",
    "tag": 12345,
    "type": "LAYER1_MASTER_ADDRESS"
  },
  "eligibleSourcesAndIntermediaries": {
    "bvnk_ethereum_usdt": [
      "bvnk_tron_usdt"
    ],
    "bvnk_kraken_btc": []
  },
  "thresholds": {
    "minBalance": 500000,
    "warningBalance": 800000,
    "targetBalance": 1000000,
    "minBalanceWindowWidth": 2,
    "warningBalanceWindowWidth": 3,
    "targetBalanceWindowWidth": 6,
    "minBalanceBufferFactor": 0.2,
    "transferOperationHardTimeout": "PT1H"
  },
  "monitoringEnabled": true,
  "forecastEnabled": true
}

---

Remove a managed balance

To delete a managed balance, send a DELETE /treasury/v1/managed-balances/{managedBalanceId} request with path parameter:

Parameter	Required	Description
managedBalanceId	✓	Unique ID of the managed balance.

Successful deletion returns HTTP 204 No Content.