> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blnkfinance.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Balance Monitoring
> Monitor balances and get notified via webhook when they meet set conditions.
export const CtaCallout = props => {
const {title, buttonLabel, href, trackingEvent, buttonTarget, rel = "noopener noreferrer", children} = props;
const handleCtaClick = () => {
if (typeof window === "undefined" || !trackingEvent) {
return;
}
try {
window.dispatchEvent(new CustomEvent("blnk:docs-cta", {
detail: {
name: trackingEvent,
href
}
}));
} catch {}
try {
window.posthog?.capture?.(trackingEvent, {
href
});
} catch {}
const gaPayload = {
cta_href: href
};
try {
window.gtag?.("event", trackingEvent, gaPayload);
} catch {}
try {
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: trackingEvent,
...gaPayload
});
} catch {}
};
const isExternal = typeof href === "string" && (/^https?:\/\//i).test(href);
const target = buttonTarget ?? (isExternal ? "_blank" : undefined);
const linkRel = isExternal ? rel : undefined;
return ;
};
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
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`).
Call `POST /balance-monitors` with your condition:
```bash cURL wrap theme={"system"}
curl -X POST "http://localhost:5001/balance-monitors" \
-H "X-blnk-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"
}'
```
```typescript TypeScript wrap theme={"system"}
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',
});
```
```go Go wrap theme={"system"}
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",
})
```
| 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](#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.
Blnk stores the monitor and returns a unique `monitor_id`. When the condition is met, you receive a `balance.monitor` webhook event.
```json Response theme={"system"}
{
"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.
```bash cURL wrap theme={"system"}
curl -X GET "http://YOUR_BLNK_INSTANCE_URL/balance-monitors/{monitor_id}" \
-H "X-blnk-key: "
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.BalanceMonitor.get('{monitor_id}');
```
```go Go wrap theme={"system"}
monitor, resp, err := client.BalanceMonitor.Get("mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0")
```
```json Response theme={"system"}
{
"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.
```bash cURL wrap theme={"system"}
curl -X GET "http://YOUR_BLNK_INSTANCE_URL/balance-monitors" \
-H "X-blnk-key: "
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.BalanceMonitor.list();
```
```go Go wrap theme={"system"}
monitors, resp, err := client.BalanceMonitor.List()
```
```json Response theme={"system"}
[
{
"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.
```bash cURL wrap theme={"system"}
curl -X GET "http://YOUR_BLNK_INSTANCE_URL/balance-monitors/balances/{balance_id}" \
-H "X-blnk-key: "
```
```json Response theme={"system"}
[
{
"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.
```bash cURL wrap theme={"system"}
curl -X PUT "http://YOUR_BLNK_INSTANCE_URL/balance-monitors/{monitor_id}" \
-H "X-blnk-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"
}'
```
```typescript TypeScript wrap theme={"system"}
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',
},
);
```
```go Go wrap theme={"system"}
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",
})
```
```json Response theme={"system"}
{
"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.
```bash cURL wrap theme={"system"}
curl -X DELETE "http://YOUR_BLNK_INSTANCE_URL/balance-monitors/{monitor_id}" \
-H "X-blnk-key: "
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.BalanceMonitor.delete('mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0');
```
```json 200 OK theme={"system"}
{
"message": "BalanceMonitor deleted successfully"
}
```
A subsequent `GET /balance-monitors/{monitor_id}` returns `404` with `BAL_MONITOR_NOT_FOUND`. See [Delete balance monitor](/reference/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](mailto:support@blnkfinance.com) or [join our Discord community](https://discord.gg/7WNv94zPpx).
Sign up and manage your ledger with our back-office dashboard. You can invite teammates to collaborate and manage your ledger operations directly from the dashboard.