Method

account.checkBalanceLimit

Compare an account's balance with its balance limits, as GnuCash's account tree does to warn.

Compares an account's balance with its higher and lower balance limits, as GnuCash's account tree does to show a warning icon. state is above, below, shouldBeZero or null when no limit is crossed. The balance is at the end of asOf (default today); with includeSubaccountBalances set on the account, sub-accounts are converted at their latest price, and the ones without a price are listed in unconverted and counted as zero.

Set limits with account.update (higherBalanceLimit, lowerBalanceLimit).

Examples

Example: with a copy of the reports/test-data example book open as book.gnucash, at 2024-07-01T12:00:00Z.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"account.update","params":{"account":"Root:Asset:Bank","higherBalanceLimit":"1000.00"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":2,"method":"account.checkBalanceLimit","params":{"account":"Root:Asset:Bank"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "asOf": "2024-07-01",
    "balance": {
      "num": "218600",
      "denom": "100"
    },
    "higherLimit": {
      "num": "100000",
      "denom": "100"
    },
    "lowerLimit": null,
    "state": "above",
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
account.update {"account":"Root:Asset:Bank","higherBalanceLimit":"1000.00"}
account.checkBalanceLimit {"account":"Root:Asset:Bank"}
EOF

It prints:

[
  "…",
  {
    "asOf": "2024-07-01",
    "balance": {
      "num": "218600",
      "denom": "100"
    },
    "higherLimit": {
      "num": "100000",
      "denom": "100"
    },
    "lowerLimit": null,
    "state": "above",
    "…": "…"
  }
]

MCP tool call

Tool call:

{"name":"account.update","arguments":{"account":"Root:Asset:Bank","higherBalanceLimit":"1000.00"}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"account.checkBalanceLimit","arguments":{"account":"Root:Asset:Bank"}}

Result:

{
  "structuredContent": {
    "asOf": "2024-07-01",
    "balance": {
      "num": "218600",
      "denom": "100"
    },
    "higherLimit": {
      "num": "100000",
      "denom": "100"
    },
    "lowerLimit": null,
    "state": "above",
    "…": "…"
  }
}

Effect: read.

Params

Params of account.checkBalanceLimit.

  • account (AccountRef, required): The account.
  • asOf (Date or null): The balance at the end of this day, local time; by default today, as GnuCash checks it.

Result

The result of account.checkBalanceLimit.

  • account (Guid, required): The account.
  • asOf (Date, required): The day the balance is taken at the end of.
  • balance (Amount, required): The balance compared, in raw sign, with sub-accounts when the account's flag is set: those in other commodities converted at the latest price and rounded to the account commodity's fraction.
  • higherLimit (Amount or null): The higher limit, if set.
  • lowerLimit (Amount or null): The lower limit, if set.
  • includesSubaccounts (boolean, required): Sub-accounts are included.
  • state (LimitStateWire or null): The limit crossed: above, below, shouldBeZero; null when none is.
  • unconverted (array of Unconverted, required): Sub-accounts in other commodities that no price converts, by commodity; they add nothing to balance.