Method

account.balance

An account's balance, cleared and reconciled balances, optionally as of a date and with sub-accounts.

Gives an account's balance, with its cleared and reconciled balances, in the account's commodity: today's, or as of a date with asOf, and with its sub-accounts' balances added when includeSubaccounts is true. Balances use the account's raw sign, debits positive and credits negative, so an income account's balance is usually negative.

Examples

Example: with a new, empty book open as book.gnucash, at 2024-07-15T12:00:00Z.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}}

Response:

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

Request:

{"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Salary","type":"INCOME","commodity":"USD"}}

Response:

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

Request:

{"jsonrpc":"2.0","id":3,"method":"transaction.post","params":{"datePosted":"2024-07-01","description":"Pay","splits":[{"account":"Checking","value":"2500.00"},{"account":"Salary","value":"-2500.00"}]}}

Response:

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

Request:

{"jsonrpc":"2.0","id":4,"method":"account.balance","params":{"account":"Checking"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "account": "…",
    "includesSubaccounts": false,
    "balances": {
      "commodity": "CURRENCY::USD",
      "balance": {
        "num": "250000",
        "denom": "100"
      },
      "cleared": {
        "num": "0",
        "denom": "1"
      },
      "reconciled": {
        "num": "0",
        "denom": "1"
      }
    },
    "unconverted": [],
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":5,"method":"account.balance","params":{"account":"Salary"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "balances": {
      "commodity": "CURRENCY::USD",
      "balance": {
        "num": "-250000",
        "denom": "100"
      },
      "…": "…"
    },
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
account.create {"name":"Checking","type":"BANK","commodity":"USD"}
account.create {"name":"Salary","type":"INCOME","commodity":"USD"}
transaction.post {"datePosted":"2024-07-01","description":"Pay","splits":[{"account":"Checking","value":"2500.00"},{"account":"Salary","value":"-2500.00"}]}
account.balance {"account":"Checking"}
account.balance {"account":"Salary"}
EOF

It prints:

[
  "…",
  "…",
  "…",
  {
    "account": "…",
    "includesSubaccounts": false,
    "balances": {
      "commodity": "CURRENCY::USD",
      "balance": {
        "num": "250000",
        "denom": "100"
      },
      "cleared": {
        "num": "0",
        "denom": "1"
      },
      "reconciled": {
        "num": "0",
        "denom": "1"
      }
    },
    "unconverted": [],
    "…": "…"
  },
  {
    "balances": {
      "commodity": "CURRENCY::USD",
      "balance": {
        "num": "-250000",
        "denom": "100"
      },
      "…": "…"
    },
    "…": "…"
  }
]

MCP tool call

Tool call:

{"name":"account.create","arguments":{"name":"Checking","type":"BANK","commodity":"USD"}}

Result:

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

Tool call:

{"name":"account.create","arguments":{"name":"Salary","type":"INCOME","commodity":"USD"}}

Result:

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

Tool call:

{"name":"transaction.post","arguments":{"datePosted":"2024-07-01","description":"Pay","splits":[{"account":"Checking","value":"2500.00"},{"account":"Salary","value":"-2500.00"}]}}

Result:

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

Tool call:

{"name":"account.balance","arguments":{"account":"Checking"}}

Result:

{
  "structuredContent": {
    "account": "…",
    "includesSubaccounts": false,
    "balances": {
      "commodity": "CURRENCY::USD",
      "balance": {
        "num": "250000",
        "denom": "100"
      },
      "cleared": {
        "num": "0",
        "denom": "1"
      },
      "reconciled": {
        "num": "0",
        "denom": "1"
      }
    },
    "unconverted": [],
    "…": "…"
  }
}

Tool call:

{"name":"account.balance","arguments":{"account":"Salary"}}

Result:

{
  "structuredContent": {
    "balances": {
      "commodity": "CURRENCY::USD",
      "balance": {
        "num": "-250000",
        "denom": "100"
      },
      "…": "…"
    },
    "…": "…"
  }
}

Effect: read.

Params

Params of account.balance.

  • account (AccountRef, required): The account.
  • asOf (Date or null): Balances at the end of this day (transactions posted before 23:59:59 local time); by default every transaction.
  • includeSubaccounts (boolean): Add the sub-accounts' balances.

Result

The result of account.balance.

  • account (Guid, required): The account.
  • asOf (Date or null): The date, if one was given.
  • includesSubaccounts (boolean, required): Sub-accounts are included.
  • balances (CommodityBalances or null): The balances, in the account's commodity (amounts, not values).
  • unconverted (array of CommodityBalances, required): Sub-accounts in other commodities, summed by commodity and not converted (GnuCash converts them at the latest price; red-ale v0.1 leaves that to the caller).