price.add

Add a price; a same-day price of the pair is replaced or wins by source precedence, as GnuCash does.

Adds a price: value units of currency per unit of commodity on a date (or at an exact time), kept exactly as given, so "1.0850" is stored as 10850/10000. The source defaults to user:price-editor, the price editor's, and must be one of GnuCash's eleven source strings (Finance::Quote, user:price, user:xfer-dialog, …) so that GnuCash reads it back the same.

A same-day price of the pair (in either direction) is handled as GnuCash does. One with a better-ranked source blocks the new one: outcome is rejected and existing names it. Otherwise it is replaced (outcome replaced, with the old GUID in replaced). Adding the same price twice therefore replaces the first, as in GnuCash, which removes the old price before it looks for an identical one. outcome is duplicate only when another identical price of that day is still there, which only a book GnuCash wrote can hold.

Examples

Example: with a new, empty book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"price.add","params":{"commodity":"EUR","currency":"USD","value":"1.0850","date":"2024-06-28"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "outcome": "added",
    "price": {
      "commodity": "CURRENCY::EUR",
      "currency": "CURRENCY::USD",
      "date": "2024-06-28",
      "source": "user:price-editor",
      "value": {
        "num": "10850",
        "denom": "10000"
      },
      "…": "…"
    },
    "replaced": null,
    "existing": null
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"price.add","params":{"commodity":"EUR","currency":"USD","value":"1.0900","date":"2024-06-28","source":"Finance::Quote"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "outcome": "rejected",
    "price": null,
    "replaced": null,
    "existing": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":3,"method":"price.add","params":{"commodity":"EUR","currency":"USD","value":"1.0850","date":"2024-06-28"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "outcome": "replaced",
    "price": {
      "date": "2024-06-28",
      "value": {
        "num": "10850",
        "denom": "10000"
      },
      "…": "…"
    },
    "replaced": "…",
    "existing": null
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
price.add {"commodity":"EUR","currency":"USD","value":"1.0850","date":"2024-06-28"}
price.add {"commodity":"EUR","currency":"USD","value":"1.0900","date":"2024-06-28","source":"Finance::Quote"}
price.add {"commodity":"EUR","currency":"USD","value":"1.0850","date":"2024-06-28"}
EOF

It prints:

[
  {
    "outcome": "added",
    "price": {
      "commodity": "CURRENCY::EUR",
      "currency": "CURRENCY::USD",
      "date": "2024-06-28",
      "source": "user:price-editor",
      "value": {
        "num": "10850",
        "denom": "10000"
      },
      "…": "…"
    },
    "replaced": null,
    "existing": null
  },
  {
    "outcome": "rejected",
    "price": null,
    "replaced": null,
    "existing": "…"
  },
  {
    "outcome": "replaced",
    "price": {
      "date": "2024-06-28",
      "value": {
        "num": "10850",
        "denom": "10000"
      },
      "…": "…"
    },
    "replaced": "…",
    "existing": null
  }
]

MCP tool call

Tool call:

{"name":"price.add","arguments":{"commodity":"EUR","currency":"USD","value":"1.0850","date":"2024-06-28"}}

Result:

{
  "structuredContent": {
    "outcome": "added",
    "price": {
      "commodity": "CURRENCY::EUR",
      "currency": "CURRENCY::USD",
      "date": "2024-06-28",
      "source": "user:price-editor",
      "value": {
        "num": "10850",
        "denom": "10000"
      },
      "…": "…"
    },
    "replaced": null,
    "existing": null
  }
}

Tool call:

{"name":"price.add","arguments":{"commodity":"EUR","currency":"USD","value":"1.0900","date":"2024-06-28","source":"Finance::Quote"}}

Result:

{
  "structuredContent": {
    "outcome": "rejected",
    "price": null,
    "replaced": null,
    "existing": "…"
  }
}

Tool call:

{"name":"price.add","arguments":{"commodity":"EUR","currency":"USD","value":"1.0850","date":"2024-06-28"}}

Result:

{
  "structuredContent": {
    "outcome": "replaced",
    "price": {
      "date": "2024-06-28",
      "value": {
        "num": "10850",
        "denom": "10000"
      },
      "…": "…"
    },
    "replaced": "…",
    "existing": null
  }
}

Effect: write, on the Book.

Params

Params of price.add.

commodity (CommodityId, required): The commodity priced.
currency (CommodityId, required): The currency (or commodity) the value is in.
value (Amount, required): Units of currency per unit of commodity; stored exactly as given.
date (Date or null): The day it applies, stored at its day-neutral time as the price editor does. Give this or time.
time (Timestamp or null): The exact time it applies. Give this or date.
source (string or null): One of GnuCash's price sources; default user:price-editor.
type (string or null): Its type, such as last, bid, ask, nav or unknown.

Result

What price.add did.

outcome (string, required): added, replaced (added, removing a same-day price), rejected (a same-day price with a better source is kept) or duplicate (another identical same-day price is still there once replaced is removed; nothing added).
price (PriceInfo or null): The price added.
replaced (Guid or null): The same-day price removed.
existing (Guid or null): The price that made this one rejected or a duplicate.