Commodity Directive¶

Overview¶

The commodity directive declares a currency or commodity and attaches metadata to it. While currencies can be used without declaration, this directive enables documentation and validation.

Syntax¶

commodity = date WHITESPACE "commodity" WHITESPACE currency
            (NEWLINE metadata)*

Components¶

Date¶

The date the commodity is declared. Typically the date it first appears in the ledger or when it was created/issued.

Currency¶

The commodity symbol following currency naming rules: - MUST start with uppercase letter (A-Z) - MUST end with uppercase letter or digit (A-Z, 0-9) - Middle characters may include: uppercase letters, digits, apostrophe, period, underscore, dash - No enforced maximum length (docs mention 24 chars but not enforced)

Examples¶

Basic Declaration¶

2024-01-01 commodity USD
2024-01-01 commodity EUR
2024-01-01 commodity AAPL

With Metadata¶

2024-01-01 commodity USD
  name: "United States Dollar"
  asset-class: "currency"

2024-01-01 commodity AAPL
  name: "Apple Inc."
  asset-class: "stock"
  exchange: "NASDAQ"
  isin: "US0378331005"

2024-01-01 commodity BTC
  name: "Bitcoin"
  asset-class: "cryptocurrency"
  precision: 8

Display Formatting¶

2024-01-01 commodity USD
  name: "US Dollar"
  symbol: "$"
  symbol-position: "prefix"
  precision: 2
  decimal-separator: "."
  group-separator: ","

2024-01-01 commodity EUR
  name: "Euro"
  symbol: "€"
  symbol-position: "suffix"
  precision: 2

Common Metadata Keys¶

Key	Type	Description
`name`	String	Human-readable name
`asset-class`	String	Category (currency, stock, crypto, etc.)
`precision`	Number	Decimal places for display
`symbol`	String	Display symbol ($, €, etc.)
`symbol-position`	String	"prefix" or "suffix"
`exchange`	String	Trading exchange
`isin`	String	International Securities ID
`cusip`	String	CUSIP identifier
`ticker`	String	Exchange ticker symbol
`quote`	Currency	Currency for price quotes

Currency Naming¶

Valid Names¶

USD     ; US Dollar
EUR     ; Euro
GBP     ; British Pound
AAPL    ; Apple stock
BTC     ; Bitcoin
ETH     ; Ethereum
VTSAX   ; Vanguard fund
VACHR   ; Custom (vacation hours)
AU      ; Gold
AG      ; Silver

Invalid Names¶

usd     ; lowercase not allowed (must start with uppercase)
US D    ; spaces not allowed
$USD    ; special characters at start not allowed
123     ; must start with letter, not digit
USD-    ; cannot end with special character (must end with A-Z or 0-9)

Validation¶

Undeclared currencies are allowed without error. The commodity directive is optional and primarily used for attaching metadata to currencies.

Note: There is NO "strict" option in beancount that requires currency declaration. Plugins may implement stricter currency declaration requirements if needed.

Multiple Declarations¶

Multiple declarations of the same commodity produce a validation error:

; Initial declaration
2024-01-01 commodity AAPL
  name: "Apple Inc."

; ERROR: Duplicate commodity directives for 'AAPL'
2024-06-01 commodity AAPL
  split: "4:1"

To add metadata, include all metadata on the single declaration:

2024-01-01 commodity AAPL
  name: "Apple Inc."
  split: "4:1"
  split-date: 2020-08-31

Use Cases¶

Documentation¶

2024-01-01 commodity VTSAX
  name: "Vanguard Total Stock Market Index Fund Admiral"
  asset-class: "mutual-fund"
  expense-ratio: 0.04
  benchmark: "CRSP US Total Market Index"

Custom Units¶

; Track vacation hours
2024-01-01 commodity VACHR
  name: "Vacation Hours"
  unit: "hours"

2024-01-01 open Assets:Vacation VACHR
2024-01-01 open Expenses:TimeOff VACHR
2024-01-01 open Income:Accrued VACHR

2024-01-15 * "Vacation accrual"
  Assets:Vacation  8 VACHR
  Income:Accrued

Price Quote Configuration¶

2024-01-01 commodity AAPL
  name: "Apple Inc."
  quote: USD
  price-source: "yahoo"
  ticker: "AAPL"

Implementation Notes¶

Commodity declarations are optional
Store metadata for later retrieval
Reject duplicate commodity declarations with error
Date is informational (doesn't affect validation)