Method

commodity.get

Describe one commodity, with how much of the book uses it.

Describes one commodity by its NAMESPACE::MNEMONIC name (a bare USD names a currency): fullname, exchange code, fraction (its smallest unit, 100 for cents), quote settings, symbols and how much of the book uses it. The displaySymbol is what GnuCash prints amounts with: the user symbol, else the default symbol, else the mnemonic.

Examples

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

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"commodity.get","params":{"commodity":"USD"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": "CURRENCY::USD",
    "mnemonic": "USD",
    "fullname": "US Dollar",
    "cusip": "840",
    "fraction": 100,
    "isCurrency": true,
    "builtIn": true,
    "displaySymbol": "$",
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash commodity.get '{"commodity":"USD"}'

It prints:

{
  "id": "CURRENCY::USD",
  "mnemonic": "USD",
  "fullname": "US Dollar",
  "cusip": "840",
  "fraction": 100,
  "isCurrency": true,
  "builtIn": true,
  "displaySymbol": "$",
  "…": "…"
}

MCP tool call

Tool call:

{"name":"commodity.get","arguments":{"commodity":"USD"}}

Result:

{
  "structuredContent": {
    "id": "CURRENCY::USD",
    "mnemonic": "USD",
    "fullname": "US Dollar",
    "cusip": "840",
    "fraction": 100,
    "isCurrency": true,
    "builtIn": true,
    "displaySymbol": "$",
    "…": "…"
  }
}

Effect: read.

Params

Params naming one commodity.

  • commodity (CommodityId, required): The commodity, NAMESPACE::MNEMONIC (a bare code is a currency).

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.