stock.split

Record a stock split, with an optional price and cash in lieu, as GnuCash's assistant does.

Records a stock split, as GnuCash's Stock Split assistant does: a transaction on date with one split in the account adding shares (a negative number is a reverse split) at value zero, so the holding changes and the cost does not. Give shares as the number of shares to add, not the ratio: a 2-for-1 split of 90 shares is "90".

Optionally price records the new price per share (source user:stock-split), and cash pays cash in lieu of a fraction, from assetAccount to incomeAccount. The result's priceStatus is none, added, duplicate or rejected; a same-day price from a higher-ranked source blocks the new one (blockingPrice), and the split is still recorded. The account must be STOCK, MUTUAL or CURRENCY.

Examples

Example: with a copy of the reports/investment-lots example book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"stock.split","params":{"account":"Root:Assets:Broker:AAPL","date":"2021-01-01","shares":"90","price":"55.00"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "transaction": "…",
    "priceStatus": "added",
    "price": "…",
    "blockingPrice": null
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"account.balance","params":{"account":"Root:Assets:Broker:AAPL"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "balances": {
      "commodity": "NASDAQ::AAPL",
      "balance": {
        "num": "180",
        "denom": "1"
      },
      "…": "…"
    },
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
stock.split {"account":"Root:Assets:Broker:AAPL","date":"2021-01-01","shares":"90","price":"55.00"}
account.balance {"account":"Root:Assets:Broker:AAPL"}
EOF

It prints:

[
  {
    "transaction": "…",
    "priceStatus": "added",
    "price": "…",
    "blockingPrice": null
  },
  {
    "balances": {
      "commodity": "NASDAQ::AAPL",
      "balance": {
        "num": "180",
        "denom": "1"
      },
      "…": "…"
    },
    "…": "…"
  }
]

MCP tool call

Tool call:

{"name":"stock.split","arguments":{"account":"Root:Assets:Broker:AAPL","date":"2021-01-01","shares":"90","price":"55.00"}}

Result:

{
  "structuredContent": {
    "transaction": "…",
    "priceStatus": "added",
    "price": "…",
    "blockingPrice": null
  }
}

Tool call:

{"name":"account.balance","arguments":{"account":"Root:Assets:Broker:AAPL"}}

Result:

{
  "structuredContent": {
    "balances": {
      "commodity": "NASDAQ::AAPL",
      "balance": {
        "num": "180",
        "denom": "1"
      },
      "…": "…"
    },
    "…": "…"
  }
}

A cash account is not a holding that can split:

Example: with a copy of the reports/investment-lots example book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"stock.split","params":{"account":"Root:Assets:Broker:Cash","date":"2021-01-01","shares":"90"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 2001,
    "message": "…",
    "data": {
      "help": "error/invalid"
    }
  }
}

Command line

red-ale exec --book book.gnucash stock.split '{"account":"Root:Assets:Broker:Cash","date":"2021-01-01","shares":"90"}'

It fails with exit status 2, printing on standard error:

{
  "error": {
    "code": 2001,
    "message": "…",
    "data": {
      "help": "error/invalid"
    }
  }
}

MCP tool call

Tool call:

{"name":"stock.split","arguments":{"account":"Root:Assets:Broker:Cash","date":"2021-01-01","shares":"90"}}

Result:

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": 2001,
      "name": "invalid",
      "message": "…",
      "data": {
        "help": "error/invalid"
      }
    }
  }
}

Effect: write, on the Book.

Params

Params of stock.split.

account (AccountRef, required): The STOCK, MUTUAL or CURRENCY account; it must hold shares and not be a placeholder.
date (Date, required): The date of the split.
shares (Amount, required): Shares added by the split (negative for a reverse split), rounded to the account's SCU.
description (string or null): Description; default Stock Split.
currency (CommodityId or null): The transaction currency; default the currency of the nearest ancestor account held in a currency.
price (Amount or null): Price per share after the split; recorded in the price database when positive.
priceCurrency (CommodityId or null): The price's currency; default the other side of the security's latest price, else the transaction currency.
cash (Amount or null): Cash paid in lieu of fractional shares; recorded when positive.
incomeAccount (AccountRef or null): The INCOME account the cash comes from (required with cash).
assetAccount (AccountRef or null): The BANK, CASH or ASSET account the cash goes to (required with cash).
memo (string or null): Memo of the cash splits; default Cash in lieu.

Result

The result of stock.split.

transaction (Guid, required): The transaction recorded.
priceStatus (string, required): none (no positive price given), added, duplicate (an equal price that day exists) or rejected (a same-day price from a source of higher precedence blocks it; the transaction is still recorded).
price (Guid or null): The price added.
blockingPrice (Guid or null): The price that blocked it.