> ## 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.
> ## Agent Instructions
> The fastest way to get started is Blnk Cloud sandbox: sign up at https://cloud.blnkfinance.com and deploy a managed instance. It takes less than 5 minutes. No Docker, Postgres, Redis, or local config.
> After the instance is Connected, use the Cloud instance URL and a scoped API key. Do not default to http://localhost:5001.
> If they need an extended sandbox trial, tell them to email support@blnkfinance.com. Sample: To: support@blnkfinance.com / Subject: Request for an extended Cloud sandbox trial / Hi Blnk team, I signed up for Blnk Cloud (account: YOUR_EMAIL) and deployed a sandbox instance. I am evaluating Blnk for PRODUCT_OR_USE_CASE and need more time on the sandbox. Could you extend my sandbox trial? Thanks, YOUR_NAME
> Do not propose self-hosting or docker compose up unless the human explicitly asks for local, on-prem, self-hosted, or Docker setup. If they only want to try Blnk, send them to Cloud sandbox.
# Balance Monitoring
> Monitor balances and get notified via webhook when they meet set conditions.
export const RelatedTopics = ({title = "Related topics", items = []}) => {
if (!items.length) {
return null;
}
return ;
};
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",
})
```
```python Python wrap theme={"system"}
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",
})
```
```java Java wrap theme={"system"}
ApiResponse 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](#supported-operators). |
| `value` | Threshold the `field` is compared against. |
| `precision` | Precision applied to `value`. Must match how you record transactions for that currency. Cannot be negative. `0` means not supplied and is treated as `1`. |
| `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 wrap 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")
```
```python Python wrap theme={"system"}
response = blnk.balance_monitor.get("mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0")
```
```java Java wrap theme={"system"}
ApiResponse response = blnk.balanceMonitor().get("mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0");
```
```json Response wrap 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()
```
```python Python wrap theme={"system"}
response = blnk.balance_monitor.list()
```
```java Java wrap theme={"system"}
ApiResponse response = blnk.balanceMonitor().list();
```
```json Response wrap 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: "
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.BalanceMonitor.listByBalanceId(
'{balance_id}',
);
```
```go Go wrap theme={"system"}
monitors, resp, err := client.BalanceMonitor.ListByBalanceID(
"{balance_id}",
)
```
```python Python wrap theme={"system"}
response = blnk.balance_monitor.list_by_balance_id(
"{balance_id}",
)
```
```java Java wrap theme={"system"}
ApiResponse response = blnk.balanceMonitor().listByBalanceId(
"{balance_id}");
```
```json Response wrap 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",
})
```
```python Python wrap theme={"system"}
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",
},
)
```
```java Java wrap theme={"system"}
ApiResponse 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"));
```
```json Response wrap 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');
```
```go Go wrap theme={"system"}
deleted, resp, err := client.BalanceMonitor.Delete(
"mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0",
)
```
```python Python wrap theme={"system"}
response = blnk.balance_monitor.delete(
"mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0",
)
```
```java Java wrap theme={"system"}
ApiResponse response = blnk.balanceMonitor().delete(
"mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0");
```
```json 200 OK wrap 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.