scrub.imbalance

Balance unbalanced transactions with an Imbalance-<CUR> split, after fixing orphans and split amounts.

Balances unbalanced transactions the way GnuCash does: it adds a split in an Imbalance-<CUR> account (made under the root if missing) for the difference, after fixing orphan splits and split amounts. Scope it with transaction, or account (and subaccounts: true); with neither it covers the whole book. Each change is listed in repairs.

red-ale never creates imbalances itself: it refuses an unbalanced transaction with unbalanced. This is for books that arrive unbalanced, from GnuCash or an import. GnuCash runs scrubs when it loads a book; red-ale keeps a book as read and scrubs only on request. The account is named Imbalance-<CUR> in English even if your GnuCash runs in another language.

Examples

Example: with a copy of the gnucash/taxreport example book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"scrub.imbalance","params":{"transaction":"80f52bea76850f1d0563e43e87c1c109"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "repairs": [
      {
        "kind": "accountCreated",
        "account": "…",
        "name": "Imbalance-USD",
        "commodity": "CURRENCY::USD"
      },
      {
        "kind": "balanceSplitAdded",
        "transaction": "80f52bea76850f1d0563e43e87c1c109",
        "split": "…",
        "account": "…",
        "value": {
          "num": "2345",
          "denom": "100"
        }
      }
    ]
  }
}

Command line

red-ale exec --book book.gnucash scrub.imbalance '{"transaction":"80f52bea76850f1d0563e43e87c1c109"}'

It prints:

{
  "repairs": [
    {
      "kind": "accountCreated",
      "account": "…",
      "name": "Imbalance-USD",
      "commodity": "CURRENCY::USD"
    },
    {
      "kind": "balanceSplitAdded",
      "transaction": "80f52bea76850f1d0563e43e87c1c109",
      "split": "…",
      "account": "…",
      "value": {
        "num": "2345",
        "denom": "100"
      }
    }
  ]
}

MCP tool call

Tool call:

{"name":"scrub.imbalance","arguments":{"transaction":"80f52bea76850f1d0563e43e87c1c109"}}

Result:

{
  "structuredContent": {
    "repairs": [
      {
        "kind": "accountCreated",
        "account": "…",
        "name": "Imbalance-USD",
        "commodity": "CURRENCY::USD"
      },
      {
        "kind": "balanceSplitAdded",
        "transaction": "80f52bea76850f1d0563e43e87c1c109",
        "split": "…",
        "account": "…",
        "value": {
          "num": "2345",
          "denom": "100"
        }
      }
    ]
  }
}

Effect: destructive, on the Book.

Params

Params of the scrubs. Give a transaction, or an account (with or without its sub-accounts); give neither for the whole book.

transaction (Guid or null): Scrub this transaction only.
account (AccountRef or null): Scrub the transactions with a split in this account.
subaccounts (boolean): With account: its sub-accounts too.

Result

What a scrub did.

repairs (array of RepairWire, required): Every change, in the order made. Empty when there was nothing to repair.