Method

commodity.create

Create a security, with the security editor's checks.

Creates a security (a stock, fund or other non-currency commodity), with the security editor's checks. Give a namespace (an exchange such as NASDAQ), a mnemonic (the ticker) and a fullname; fraction is the smallest unit (default 10000), and quoteFlag and quoteSource set it up for online prices. Currencies cannot be created: the CURRENCY namespace is refused with invalid, and an existing name with conflict. Names with :: are refused because they would make NAMESPACE::MNEMONIC ambiguous.

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","fraction":10000}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": "NASDAQ::AAPL",
    "fullname": "Apple Inc",
    "fraction": 10000,
    "isCurrency": false,
    "builtIn": false,
    "displaySymbol": "AAPL",
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"commodity.create","params":{"namespace":"CURRENCY","mnemonic":"ZZZ","fullname":"Nope"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "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","fraction":10000}
commodity.create {"namespace":"CURRENCY","mnemonic":"ZZZ","fullname":"Nope"}
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","fraction":10000}}

Result:

{
  "structuredContent": {
    "id": "NASDAQ::AAPL",
    "fullname": "Apple Inc",
    "fraction": 10000,
    "isCurrency": false,
    "builtIn": false,
    "displaySymbol": "AAPL",
    "…": "…"
  }
}

Tool call:

{"name":"commodity.create","arguments":{"namespace":"CURRENCY","mnemonic":"ZZZ","fullname":"Nope"}}

Result:

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

Effect: write, on the Book.

Params

Params of commodity.create.

  • namespace (string, required): Namespace (exchange or type), such as NASDAQ; not CURRENCY or template.
  • mnemonic (string, required): Mnemonic (ticker), unique within the namespace.
  • fullname (string, required): Full name; required.
  • cusip (string or null): Exchange code such as a CUSIP or ISIN.
  • fraction (integer (int64)): Smallest fraction, 1 to 1000000000; default 10000.
  • quoteFlag (boolean): Online quotes are wanted.
  • quoteSource (string or null): Quote source internal name, such as yahoo_json; unknown names are kept.
  • quoteTz (string or null): Quote time zone, such as America/New_York; absent means local time.
  • userSymbol (string or null): Display symbol.

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.