Method

commodity.update

Edit a security (any field, including a rename) or a currency's quote flag, quote time zone and symbol.

Edits a security (any field, including its namespace and mnemonic) or a currency's quote flag, quote time zone and symbol. Fields you leave out are kept; null clears cusip, quoteSource, quoteTz or userSymbol. A currency's other fields are fixed and a change is refused with invalid.

Renaming a security changes every account, transaction and price that names it. Changing a commodity's fraction does not re-round amounts already stored.

Examples

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

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"commodity.create","params":{"namespace":"NASDAQ","mnemonic":"AAPL","fullname":"Apple Inc"}}

Response:

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

Request:

{"jsonrpc":"2.0","id":2,"method":"commodity.update","params":{"commodity":"NASDAQ::AAPL","fullname":"Apple Inc.","quoteFlag":true,"quoteSource":"yahoo_json"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "id": "NASDAQ::AAPL",
    "fullname": "Apple Inc.",
    "quoteFlag": true,
    "quoteSource": "yahoo_json",
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":3,"method":"commodity.update","params":{"commodity":"EUR","fullname":"Euro, renamed"}}

Response:

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

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
commodity.create {"namespace":"NASDAQ","mnemonic":"AAPL","fullname":"Apple Inc"}
commodity.update {"commodity":"NASDAQ::AAPL","fullname":"Apple Inc.","quoteFlag":true,"quoteSource":"yahoo_json"}
commodity.update {"commodity":"EUR","fullname":"Euro, renamed"}
EOF

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

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

MCP tool call

Tool call:

{"name":"commodity.create","arguments":{"namespace":"NASDAQ","mnemonic":"AAPL","fullname":"Apple Inc"}}

Result:

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

Tool call:

{"name":"commodity.update","arguments":{"commodity":"NASDAQ::AAPL","fullname":"Apple Inc.","quoteFlag":true,"quoteSource":"yahoo_json"}}

Result:

{
  "structuredContent": {
    "id": "NASDAQ::AAPL",
    "fullname": "Apple Inc.",
    "quoteFlag": true,
    "quoteSource": "yahoo_json",
    "…": "…"
  }
}

Tool call:

{"name":"commodity.update","arguments":{"commodity":"EUR","fullname":"Euro, renamed"}}

Result:

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

Effect: write, on the Book.

Params

Params of commodity.update. Absent fields are kept; null clears an optional one.

  • commodity (CommodityId, required): The commodity to edit.
  • namespace (string or null): New namespace (securities only); renames it everywhere in the book.
  • mnemonic (string or null): New mnemonic (securities only); renames it everywhere in the book.
  • fullname (string or null): New full name (securities only).
  • cusip (string or null): New exchange code (securities only); null or empty clears it.
  • fraction (integer (int64) or null): New smallest fraction (securities only). Stored amounts keep their denominators.
  • quoteFlag (boolean or null): Online quotes wanted. For a currency, a choice that differs from the automatic one is remembered.
  • quoteSource (string or null): New quote source (securities only); null clears it.
  • quoteTz (string or null): New quote time zone; null means local time.
  • userSymbol (string or null): New display symbol; null or empty removes it.

Result

A commodity as GnuCash sees it once the book is loaded.

  • id (CommodityId, required): NAMESPACE::MNEMONIC.
  • namespace (string, required): Namespace.
  • mnemonic (string, required): Mnemonic (ticker or ISO code).
  • fullname (string or null): Full name.
  • cusip (string or null): Exchange code (CUSIP, ISIN; the ISO numeric code for a currency).
  • fraction (integer (int64), required): Smallest fraction (SCU).
  • isCurrency (boolean, required): In the CURRENCY namespace.
  • builtIn (boolean, required): One of GnuCash's built-in ISO 4217 currencies.
  • defined (boolean, required): Stored in the book file (a security, or a currency with quotes on or slots).
  • quoteFlag (boolean, required): Online quotes are wanted. For a currency an account uses this is on unless the user turned it off.
  • quoteSource (string or null): Quote source internal name; currencies report currency.
  • quoteSourceType (string or null): single, multi, currency, or unknown for a source GnuCash 5.17 does not know (kept as read).
  • quoteTz (string or null): Quote time zone; null means local time.
  • userSymbol (string or null): The user's display symbol.
  • defaultSymbol (string or null): A currency's built-in symbol.
  • displaySymbol (string, required): The symbol GnuCash shows amounts with: the user symbol, else the default symbol, else the mnemonic.
  • usage (UsageInfo, required): How much of the book refers to it.