Skip to main content
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?

  1. Fraud detection: Unusual balance changes can be an early indication of fraudulent activities. Monitoring can trigger alerts for suspicious transactions and ensure timely intervention.
  2. Regulatory compliance: Many financial regulations require institutions to maintain specific balance thresholds. Real-time balance monitoring makes it easy to comply with these regulations.
  3. 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.
  4. 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

1

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).
2

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"
  }'
FieldDescription
balance_idUnique identifier of the balance to be monitored.
conditionObject representing the condition to be satisfied.
fieldSub-balance to monitor: debit_balance, credit_balance, or balance.
operatorComparison operator. See Supported operators.
valueThreshold the field is compared against.
precisionPrecision applied to value. Must match how you record transactions for that currency.
descriptionLabel for the monitor. Empty when omitted.
You can include meta_data in the request to attach custom data to the monitor.
3

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"
}
FieldDescriptionType
monitor_idUnique identifier for your balance monitor.string
created_atDate 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:
OperatorsSymbolDescription
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>"
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>"
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>"
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"
  }'
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>"
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.