Skip to main content
Version: 2.4.2

Adding Accounts and Commodities

To keep your ledger organized, you must explicitly declare the accounts and commodities (currencies, stocks, crypto) that you use in your transactions.

🏦 Managing Accounts​

Beancount requires you to open an account before you can post transactions to it. If you try to write a transaction using an undeclared account, Beancount will raise an error.

Account Types​

Beancount supports five root account types:

  • Assets: Money you own (e.g. Assets:Checking, Assets:Brokerage).
  • Liabilities: Money you owe (e.g. Liabilities:CreditCard, Liabilities:CarLoan).
  • Equity: Represents net worth initialization (e.g. Equity:OpeningBalances).
  • Income: Revenue sources (e.g. Income:Salary, Income:Interest).
  • Expenses: Outflows (e.g. Expenses:Food:Groceries, Expenses:Housing:Rent).

Open and Close Directives​

To declare an account, use the open directive with a date. You can also specify the currencies the account is allowed to hold:

2020-01-01 open Assets:Checking USD, EUR

To close an account (preventing future transactions on it), use the close directive:

2026-05-30 close Assets:Checking

Managing Accounts via UI​

You don't have to write these directives manually. You can manage accounts directly from the dashboard:

  1. Open the Unified Dashboard and navigate to the Accounts & Balances tab.
  2. In the top right header controls, click:
    • ➕ Open Account: Launches a modal where you enter the new account name (with autocomplete prefixes), select the opening date, list allowed currencies, and optionally set a reconciliation interval (in days).
    • ❌ Close Account: Launches a modal where you select an active account and the closing date.
  3. The plugin appends the appropriate directive to accounts.beancount in your structured layout folder.
  4. The dashboard refreshes automatically, updating your account lists.

🪙 Declaring Commodities​

A commodity is any unit of currency or asset tracked in your ledger (e.g., USD, EUR, AAPL, BTC). While Beancount can use currencies without explicit declaration, declaring them allows you to attach useful metadata.

Commodity Syntax​

Declare a commodity with the commodity directive:

2020-01-01 commodity AAPL

Metadata Annotations​

Our plugin recognizes specific metadata key-value pairs indented under the commodity directive to customize the dashboard display:

  • name: The full display name of the commodity (e.g., "Apple Inc.").
  • logo: A URL to an icon/image of the commodity (displays as an avatar in the Commodities tab).
  • price: The automated price source for the commodity (see Adding Price Metadata).

Example:​

2020-01-01 commodity BTC
  name: "Bitcoin"
  logo: "https://cryptologos.cc/logos/bitcoin-btc-logo.png"
  price: "USD:coinbase/BTC-USD"

Sourcing Logo URLs​

If you want to add logos to your commodities but aren't sure where to host or find them, you can use several free public services and CDNs:

  • Stocks / Companies: Use Logo.dev, which replaced the now-discontinued Clearbit Logo API. It provides logo images by company domain; check their site for the current URL format and free public token.
  • Fiat Currencies: Use Flagpedia or Flagcdn. They provide flag images based on country codes (e.g., https://flagcdn.com/w40/us.png for USD).
  • Cryptocurrencies: Use public repositories like TrustWallet Assets or search on sites like CryptoLogos.

Simply copy the image link from these sources and paste it into the logo metadata field!

Declaring Commodities via UI​

You can configure and declare commodities directly from the dashboard:

  1. Open the Unified Dashboard and navigate to the Commodities tab.
  2. Click the + Add Commodity button in the header to create a new one. Fill in:
    • Symbol: The ticker/currency symbol (e.g., AAPL, EUR).
    • Date: When the commodity was first introduced.
    • Price Source (optional): The automated price source (see Adding Price Metadata) — has a Test button to verify it resolves before saving.
    • Logo URL (optional): Image link for the icon — also has a Test button that previews the image.
  3. Click on an existing commodity's row to open its detail view, where you can edit its Price Source or Logo in place and see its price history.
  4. The plugin writes the commodity directive and any price/logo metadata to commodities.beancount in your structured layout.

Note: the name metadata key (display name) is read and shown by the dashboard if present, but there's currently no UI field to set it — add it by editing the commodity directive directly, as shown in the example above.