Ledger balances

Balance monitoring

Get a webhook when a balance crosses a threshold you set.

A balance monitor watches one amount on a balance, such as what it holds or what it has sent. Blnk sends you a webhook when that amount crosses a threshold you set.

Use it for a low balance, a spending cap, or money on hold past a limit. You choose the threshold, and whether the webhook arrives once or on every update while the amount stays past it.

How monitors work

You set trigger to edge or level. That choice decides how often Blnk sends the balance.monitor webhook.

Trigger	When Blnk notifies you
`edge`	Once, the first time your rule matches. Quiet until the amount no longer matches, then again on the next match.
`level`	On every transaction that updates the balance while your rule still matches.

A monitor on balance matches when the balance is below 100.00. As transactions land, the two triggers notify you like this:

Balance	`edge`	`level`
150.00	No webhook	No webhook
80.00	Webhook	Webhook
60.00	No webhook	Webhook
120.00	No webhook	No webhook
90.00	Webhook	Webhook

Create a monitor

To create a new monitor, call Create balance monitor.

This example watches debit_balance (the total the balance has sent), and notifies you once when that total goes above 1,000.00.

Write value in the currency’s normal units, and set precision to the scale you already use for that currency. 1000 at precision 100 is 1,000.00.

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",
    "trigger": "edge",
    "condition": {
      "field": "debit_balance",
      "operator": ">",
      "value": 1000,
      "precision": 100
    },
    "description": "Spending above 1000"
  }'

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

monitor, _, _ := client.BalanceMonitor.Create(blnkgo.MonitorData{
    BalanceID: "bln_0be360ca-86fe-457d-be43-daa3f966d8f0",
    Condition: blnkgo.MonitorCondition{
        Field: "debit_balance",
        Operator: blnkgo.OperatorGreaterThan,
        Value: 1000,
        Precision: 100,
    },
    Description: "Spending above 1000",
})

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

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

Field	Description	Required
`balance_id`	Balance to watch.	Yes
`condition`	The amount, the comparison, the threshold, and the precision.	Yes
`field`	Which amount. `balance` is what it holds now. `credit_balance` is the total received. `debit_balance` is the total sent. `inflight_balance`, `inflight_credit_balance`, and `inflight_debit_balance` are amounts still on hold. See Balances overview.	Yes
`operator`	How to compare the amount with the threshold. See Operators.	Yes
`value`	Threshold in the currency. `0` and amounts such as `100.50` are valid.	Yes
`precision`	Scale for `value`, the same one you use when you record that currency. Greater than `0`.	Yes
`trigger`	`edge` or `level`. Leave it out on 0.15.7 and the monitor notifies you once per crossing.	No
`description`	A label for the monitor. Empty when you leave it out.	No

{
  "monitor_id": "mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0",
  "balance_id": "bln_0be360ca-86fe-457d-be43-daa3f966d8f0",
  "condition": {
    "field": "debit_balance",
    "operator": ">",
    "value": 1000,
    "precision": 100,
    "precise_value": 100000
  },
  "description": "Spending above 1000",
  "trigger": "edge",
  "condition_state": false,
  "created_at": "2024-02-20T05:56:58.257315054Z"
}

Field	Description
`monitor_id`	Id of the monitor. Save it to view, update, or delete the monitor.
`precise_value`	The same threshold in the currency’s smallest unit. Here, 1,000.00 is `100000`.
`trigger`	`edge` or `level`.
`condition_state`	Whether your rule matches right now. An `edge` monitor includes this.
`description`	The label on the monitor.
`created_at`	When the monitor was created.

Supported operators

A symbol outside this list returns 400 GEN_VALIDATION_ERROR.

Operator	Symbol	Description
Greater than	`>`	The amount is above the threshold.
Less than	<	The amount is below the threshold.
Greater than or equal to	`>=`	The amount is at or above the threshold.
Less than or equal to	<=	The amount is at or below the threshold.
Equal to	`=`	The amount matches the threshold.
Not equal to	`!=`	The amount is different from the threshold.