Balance Monitoring

Balance monitors let you keep track of balances in your Blnk Ledger. This is useful for scenarios where balances should meet specific thresholds. You can monitor all 3 sub-balances of a ledger balance - credit balance (credit_balance), debit balance (debit_balance) and total balance (balance).

Why monitor balances?

Fraud detection: Unusual balance changes can be an early indication of fraudulent activities. Monitoring can trigger alerts for suspicious transactions and ensure timely intervention.
Regulatory compliance: Many financial regulations require institutions to maintain specific balance thresholds. Real-time balance monitoring makes it easy to comply with these regulations.
Customer notifications: Customers can be notified in real-time if their balance crosses a specific threshold. It can also be used for segmenting your customers in your application.
Operational efficiency: Instantly knowing when a balance reaches a certain threshold can trigger automatic actions, such as transferring funds between accounts or purchasing assets.

Set up balance monitors

Define your condition

Choose the balance to watch, the sub-balance field, the comparison operator, and the threshold value. Use the same precision you use when recording transactions for that currency.In this example, you want to get notified when debit_balance is greater than 1,000.00 (value: 100000, precision: 100).

Create the monitor

Call POST /balance-monitors with your condition:

curl -X POST "http://localhost:5001/balance-monitors" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "balance_id": "bln_0be360ca-86fe-457d-be43-daa3f966d8f0",
    "condition": {
      "field": "debit_balance",
      "operator": ">",
      "value": 100000,
      "precision": 100
    },
    "description": "Tier 1 Account"
  }'

const response = await blnk.BalanceMonitor.create({
  balance_id: 'bln_0be360ca-86fe-457d-be43-daa3f966d8f0',
  condition: {
    field: 'debit_balance',
    operator: '>',
    value: 100000,
    precision: 100,
  },
  description: 'Tier 1 Account',
});

monitor, resp, err := client.BalanceMonitor.Create(blnkgo.MonitorData{
    BalanceID: "bln_0be360ca-86fe-457d-be43-daa3f966d8f0",
    Condition: blnkgo.MonitorCondition{
        Field: "debit_balance",
        Operator: blnkgo.OperatorGreaterThan,
        Value: 100000,
        Precision: 100,
    },
    Description: "Tier 1 Account",
})

response = blnk.balance_monitor.create({
  "balance_id": "bln_0be360ca-86fe-457d-be43-daa3f966d8f0",
  "condition": {
    "field": "debit_balance",
    "operator": ">",
    "value": 100000,
    "precision": 100,
  },
  "description": "Tier 1 Account",
})

ApiResponse<JsonNode> response = blnk.balanceMonitor().create(
    MonitorData.create()
        .balanceId("bln_0be360ca-86fe-457d-be43-daa3f966d8f0")
        .condition(MonitorCondition.create()
            .field("debit_balance")
            .operator(">")
            .value(100000)
            .precision(100))
        .description("Tier 1 Account"));

Field	Description
`balance_id`	Unique identifier of the balance to be monitored.
`condition`	Object representing the condition to be satisfied.
`field`	Sub-balance to monitor: `debit_balance`, `credit_balance`, or `balance`.
`operator`	Comparison operator. See Supported operators.
`value`	Threshold the `field` is compared against.
`precision`	Precision applied to `value`. Must match how you record transactions for that currency.
`description`	Label for the monitor. Empty when omitted.

You can include meta_data in the request to attach custom data to the monitor.

Confirm creation

Blnk stores the monitor and returns a unique monitor_id. When the condition is met, you receive a balance.monitor webhook event.

Response

{
  "monitor_id": "mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0",
  "balance_id": "bln_0be360ca-86fe-457d-be43-daa3f966d8f0",
  "condition": {
    "field": "debit_balance",
    "operator": ">",
    "value": 100000,
    "precision": 100
  },
  "description": "Tier 1 Account",
  "created_at": "2024-02-20T05:56:58.257315054Z"
}

Field	Description	Type
`monitor_id`	Unique identifier for your balance monitor.	`string`
`created_at`	Date and time of creation.	`string`

Save the returned monitor_id - you need it to view, update, or delete the monitor later.

Supported operators

This is a list of all supported operators by the Balance monitor:

Operators	Symbol	Description
Greater than	>	Checks if the specified balance in `field` is greater than `value`
Less than	<	Checks if the specified balance in `field` is less than `value`
Equal to	=	Checks if the specified balance in `field` is exactly equal to `value`
Not equal to	!=	Checks if the specified balance in `field` is not equal to `value`
Greater than or equal to	>=	Checks if the specified balance in `field` is greater than or equal to `value`
Less than or equal to	<=	Checks if the specified balance in `field` is less than or equal to `value`

View a balance monitor

Call GET /balance-monitors/{monitor_id} to retrieve one monitor by ID.

curl -X GET "http://YOUR_BLNK_INSTANCE_URL/balance-monitors/{monitor_id}" \
  -H "X-blnk-key: <api-key>"

const response = await blnk.BalanceMonitor.get('{monitor_id}');

monitor, resp, err := client.BalanceMonitor.Get("mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0")

response = blnk.balance_monitor.get("mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0")

ApiResponse<JsonNode> response = blnk.balanceMonitor().get("mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0");

Response

{
  "monitor_id": "mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0",
  "balance_id": "bln_0be360ca-86fe-457d-be43-daa3f966d8f0",
  "condition": {
    "field": "debit_balance",
    "operator": ">",
    "value": 100000
  },
  "description": "Tier 1 Account",
  "created_at": "2024-02-20T05:56:58.257315054Z"
}

List all balance monitors

Call GET /balance-monitors to retrieve every monitor in your ledger.

curl -X GET "http://YOUR_BLNK_INSTANCE_URL/balance-monitors" \
  -H "X-blnk-key: <api-key>"

const response = await blnk.BalanceMonitor.list();

monitors, resp, err := client.BalanceMonitor.List()

response = blnk.balance_monitor.list()

ApiResponse<JsonNode> response = blnk.balanceMonitor().list();

Response

[
  {
    "monitor_id": "mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0",
    "balance_id": "bln_0be360ca-86fe-457d-be43-daa3f966d8f0",
    "condition": {
      "field": "debit_balance",
      "operator": ">",
      "value": 100000
    },
    "description": "Tier 1 Account",
    "created_at": "2024-02-20T05:56:58.257315054Z"
  }
]

List monitors for a balance

Call GET /balance-monitors/balances/{balance_id} to retrieve every monitor attached to a specific balance. The path parameter is the balance ID, not a monitor ID.

curl -X GET "http://YOUR_BLNK_INSTANCE_URL/balance-monitors/balances/{balance_id}" \
  -H "X-blnk-key: <api-key>"

const response = await blnk.BalanceMonitor.listByBalanceId(
  '{balance_id}',
);

monitors, resp, err := client.BalanceMonitor.ListByBalanceID(
    "{balance_id}",
)

response = blnk.balance_monitor.list_by_balance_id(
  "{balance_id}",
)

ApiResponse<JsonNode> response = blnk.balanceMonitor().listByBalanceId(
    "{balance_id}");

Response

[
  {
    "monitor_id": "mon_c33db397-7475-4930-a719-4be110e437f5",
    "balance_id": "bln_71e707a0-f811-43ef-b5ec-2c7445d57d18",
    "condition": {
      "field": "debit_balance",
      "operator": ">",
      "value": 200,
      "precision": 100,
      "precise_value": 10000
    },
    "description": "High debit alert",
    "created_at": "2026-06-13T00:33:25.473364Z"
  }
]

Update a balance monitor

Call PUT /balance-monitors/{monitor_id} and provide the updated conditions in the request body.

curl -X PUT "http://YOUR_BLNK_INSTANCE_URL/balance-monitors/{monitor_id}" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "balance_id": "bln_0be360ca-86fe-457d-be43-daa3f966d8f0",
    "condition": {
      "field": "debit_balance",
      "operator": ">",
      "value": 100000
    },
    "description": "Tier 1 Account"
  }'

const response = await blnk.BalanceMonitor.update(
  'mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0',
  {
    balance_id: 'bln_0be360ca-86fe-457d-be43-daa3f966d8f0',
    condition: {
      field: 'debit_balance',
      operator: '>',
      value: 100000,
    },
    description: 'Tier 1 Account',
  },
);

monitor, resp, err := client.BalanceMonitor.Update("mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0", blnkgo.MonitorData{
    BalanceID: "bln_0be360ca-86fe-457d-be43-daa3f966d8f0",
    Condition: blnkgo.MonitorCondition{
        Field: "debit_balance",
        Operator: blnkgo.OperatorGreaterThan,
        Value: 100000,
    },
    Description: "Tier 1 Account",
})

response = blnk.balance_monitor.update(
  "mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0",
  {
    "balance_id": "bln_0be360ca-86fe-457d-be43-daa3f966d8f0",
    "condition": {
      "field": "debit_balance",
      "operator": ">",
      "value": 100000,
    },
    "description": "Tier 1 Account",
  },
)

ApiResponse<JsonNode> response = blnk.balanceMonitor().update(
    "mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0",
    MonitorData.create()
        .balanceId("bln_0be360ca-86fe-457d-be43-daa3f966d8f0")
        .condition(MonitorCondition.create()
            .field("debit_balance")
            .operator(">")
            .value(100000))
        .description("Tier 1 Account"));

Response

{
  "monitor_id": "mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0",
  "balance_id": "bln_0be360ca-86fe-457d-be43-daa3f966d8f0",
  "condition": {
    "field": "debit_balance",
    "operator": ">",
    "value": 100000
  },
  "description": "Tier 1 Account",
  "created_at": "2024-02-20T05:56:58.257315054Z"
}

Delete a balance monitor

Call DELETE /balance-monitors/{monitor_id} to remove a monitor.

curl -X DELETE "http://YOUR_BLNK_INSTANCE_URL/balance-monitors/{monitor_id}" \
  -H "X-blnk-key: <api-key>"

const response = await blnk.BalanceMonitor.delete('mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0');

deleted, resp, err := client.BalanceMonitor.Delete(
    "mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0",
)

response = blnk.balance_monitor.delete(
  "mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0",
)

ApiResponse<JsonNode> response = blnk.balanceMonitor().delete(
    "mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0");

200 OK

{
  "message": "BalanceMonitor deleted successfully"
}

A subsequent GET /balance-monitors/{monitor_id} returns 404 with BAL_MONITOR_NOT_FOUND. See Delete balance monitor for the full reference.

Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool. To ask questions or discuss issues, please contact us or join our Discord community.

Start Here

Ledgers

Ledger balances

Transactions

Reconciliation

Identities

Metadata

Search

Webhooks

API keys

Guides

Configuration

Advanced

Migration guides

Why monitor balances?

Set up balance monitors

Supported operators

View a balance monitor

List all balance monitors

List monitors for a balance

Update a balance monitor

Delete a balance monitor

Need help?

​Why monitor balances?

​Set up balance monitors

​Supported operators

​View a balance monitor

​List all balance monitors

​List monitors for a balance

​Update a balance monitor

​Delete a balance monitor

​Need help?

Why monitor balances?

Set up balance monitors

Supported operators

View a balance monitor

List all balance monitors

List monitors for a balance

Update a balance monitor

Delete a balance monitor

Need help?