49 posts tagged with "Beancount"

Choosing a personal accounting system involves trade-offs between performance, data architecture, and extensibility. For engineers and other technical users, the choice often comes down to which system provides the most robust, predictable, and programmable foundation.

Drawing from a detailed comparative report, let's analyze the technical specifics of Beancount versus its popular open-source counterparts: Ledger-CLI, hledger, and GnuCash.

Speed and Performance: Quantitative Benchmarks 🚀​

For any serious dataset, performance is non-negotiable. Beancount is architected to handle decades of transactional data without compromising on speed. Despite being implemented in Python (v2), its highly optimized parser is remarkably efficient.

• Beancount: Real-world usage shows it can load and process ledgers with hundreds of thousands of transactions in approximately 2 seconds. Memory usage is modest; parsing ~100k transactions converts the source text into in-memory objects using only tens of megabytes of RAM.
• The 1M Transaction Stress Test: A benchmark using a synthetic ledger of 1 million transactions, 1,000 accounts, and 1 million price entries revealed significant architectural differences:
  • hledger (Haskell): Successfully completed a full parse and report in ~80.2 seconds, processing ~12,465 txns/sec while using ~2.58 GB of RAM.
  • Ledger-CLI (C++): The process was terminated after 40 minutes without completion, likely due to a known regression causing excessive memory and CPU usage with highly complex ledgers.
  • Beancount: While not included in that specific 1M test, its performance curve suggests it would handle the task efficiently. Furthermore, the upcoming Beancount v3, with its new C++ core and Python API, is expected to deliver another order-of-magnitude improvement in throughput.
• GnuCash (C/Scheme): As a GUI application loading its entire dataset into memory, performance degrades noticeably with size. A ~50 MB XML file (representing 100k+ transactions) took 77 seconds to open. Switching to the SQLite backend only marginally improved this to ~55 seconds.

Conclusion: Beancount provides exceptional performance that scales predictably, a crucial feature for long-term data management. It avoids the performance cliffs seen in Ledger and the UI-bound latency of GnuCash.

Data Architecture: Plain Text vs. Opaque Databases 📄​

The way a system stores your data dictates its transparency, portability, and durability. Beancount uses a clean, human-readable plain text format that is superior for technical users.

• Compact & Efficient: A 100,000-transaction Beancount file is only ~8.8 MB. This is more compact than the equivalent Ledger file (~10 MB) partly because Beancount's syntax allows for the inference of the final balancing amount in a transaction, reducing redundancy.
• Structurally Enforced: Beancount mandates explicit YYYY-MM-DD\ open\ Account directives. This disciplined approach prevents account name typos from silently creating new, incorrect accounts—a common pitfall in systems like Ledger and hledger which create accounts on-the-fly. This structure makes the data more reliable for programmatic manipulation.
• Version Control Ready: A plain text ledger is perfectly suited for version control with Git. You get a complete, auditable history of every financial change you make.
• Contrast with GnuCash: GnuCash defaults to a gzip-compressed XML file, where data is verbose and wrapped in tags with GUIDs for every entity. While it offers SQLite, MySQL, and PostgreSQL backends, this abstracts the data away from simple, direct text manipulation and versioning. Editing the raw XML is possible but far more cumbersome than editing a Beancount file.

Conclusion: Beancount's data format is not just text; it's a well-defined language that maximizes clarity, enforces correctness, and integrates seamlessly with developer tools like git and grep.

The Killer Feature: A True Python API and Plugin Architecture 🐍​

This is Beancount's defining technical advantage. It is not a monolithic application but a library with a stable, first-class Python API. This design decision unlocks limitless automation and integration possibilities.

• Direct Programmatic Access: You can read, query, and manipulate your ledger data directly in Python. This is why developers migrate. As one user noted, the frustration of trying to script against Ledger's poorly documented internal bindings evaporates with Beancount.
• Plugin Pipeline: Beancount's loader allows you to insert custom Python functions directly into the processing pipeline. This enables arbitrary transformations and validations on the data stream as it's being loaded—for instance, writing a plugin to enforce that every expense from a specific vendor must have a certain tag.
• Powerful Importer Framework: Move beyond clunky CSV import wizards. With Beancount, you write Python scripts to parse financial statements from any source (OFX, QFX, CSV). Community tools like smart_importer even leverage machine learning models to automatically predict and assign posting accounts, turning hours of manual categorization into a seconds-long, one-command process.
• How Others Compare:
  • Ledger/hledger: Extensibility is primarily external. You pipe data to/from the executable. While they can output JSON/CSV, you cannot inject logic into their core processing loop without modifying the C++/Haskell source.
  • GnuCash: Extensibility is handled via a steep learning curve with Guile (Scheme) for custom reports or via Python bindings (using SWIG and libraries like PieCash) that interact with the GnuCash engine. It's powerful but less direct and "Pythonic" than Beancount's native library approach.

Conclusion: Beancount is architected for the programmer. Its library-first design and deep integration with Python make it the most flexible and automatable system of the four.

Philosophy: A Strict Compiler for Your Finances 🤓​

Beancount's learning curve is a direct result of its core philosophy: your financial data is a formal language, and it must be correct.

Beancount's parser functions like a strict compiler. It performs robust syntactical and logical validation. If a transaction doesn't balance or an account hasn't been opened, it will refuse to process the file and will return a descriptive error with a line number. This is a feature, not a bug. It guarantees that if your file "compiles," the underlying data is structurally sound.

This deterministic approach ensures a level of data integrity that is invaluable for building reliable automated systems on top of it. You can write scripts that consume Beancount's output with confidence, knowing the data has already been rigorously validated.

Who is Beancount For?​

Based on this technical analysis, Beancount is the optimal choice for:

• Developers and Engineers who want to treat their finances as a version-controlled, programmable dataset.
• Data Tinkers who want to write custom queries, build unique visualizations with tools like Fava, or feed their financial data into other analytical models.
• Anyone who values demonstrable correctness and automation over the convenience of a GUI or the leniency of a less-structured format.

If you desire raw C++ performance for standard reports, Ledger is a contender. For exceptional scalability in a functional programming paradigm, hledger is impressive. For a feature-packed GUI with minimal setup, GnuCash excels.

But if you want to build a truly robust, automated, and deeply customized financial management system, Beancount provides the superior technical foundation.

Running a small business is already a constant juggle of cash flow, suppliers, and customers—tax surprises shouldn’t be another bowling pin in the air. The good news: with a simple framework and a few Beancount tricks, you can translate “I hope the tax bill isn’t huge” into a predictable monthly transfer.

1. Know What You’re Really Paying For​

Before you can set money aside, you need to know where it’s going. For most U.S. small businesses (especially sole proprietorships and partnerships), the total tax liability is a combination of several distinct obligations.

• Federal Income Tax: This is a progressive tax, meaning the rate increases as your income does. For 2025, brackets go up to 37% for single incomes above $626,350 and married-filing-jointly (MFJ) incomes above $751,600.
• Self-Employment (SE) Tax: This is the entrepreneur's version of FICA taxes (Social Security and Medicare) that W-2 employees pay. It’s a flat 15.3% on your first chunk of net earnings. The 12.4% Social Security portion stops once your profit hits the annual wage base, which is projected to be $176,100 in 2025. The remaining 2.9% for Medicare continues on all profits.
• State & Local Income Tax: This varies wildly by location, ranging from 0% in states like Wyoming and Texas to over 13% in California's top bracket.
• Quarterly Underpayment Penalties: The IRS wants its money throughout the year, not all at once. To avoid penalties, you generally must pre-pay at least 90% of your current year's tax liability or 100% of your previous year's tax bill (this threshold rises to 110% if your adjusted gross income, or AGI, is over $150,000).

Quick heuristic: Most U.S. solopreneurs who live in an average-tax state end up owing 25% - 30% of net profit once federal, SE, and state taxes are combined.

2. A Three-Step Estimate You Can Update Monthly​

You don’t need complex software to get a handle on this. A simple, repeatable process is all it takes.

1. Project Annual Profit: Look at your year-to-date performance and make a reasonable forecast for the full year. The basic formula is your friend: Projected Revenue - Projected Deductible Expenses = Projected Profit.
2. Apply an Effective Tax Rate: Start with a reasonable percentage. If you have last year’s tax return, you can calculate your effective rate from that. If you're new to this, the 30% heuristic is a safe starting point.
3. Divide by 12 (or 52): Take your total estimated annual tax and divide it by the number of pay periods you want to use. We recommend monthly. Move that amount into a dedicated tax-reserve bank account every month. If your cash flow is more volatile, a weekly transfer might feel more manageable.

3. Implement It in Beancount​

Plain-text accounting makes this process transparent and auditable. Here’s how to manage your tax savings in Beancount.

First, create a routine transaction to move your monthly savings from your primary checking account to a separate, dedicated savings account for taxes.

; Reserve July's taxes
2025-07-31 * "Tax reserve transfer"
  Assets:Bank:Checking          -3000 USD
  Assets:Bank:TaxReserve         3000 USD
  Equity:Opening-Balances

When you make a quarterly estimated payment to the government, you record the actual liability. The payment comes directly from your reserve account.

; Record liability when you file the quarterly payment
2025-09-15 * "Q3 estimated tax payment"
  Assets:Bank:TaxReserve        -9000 USD
  Liabilities:Taxes:Federal      6000 USD
  Liabilities:Taxes:State        3000 USD

This simple system buys you three powerful advantages:

• Immediate Visibility: Your Assets:Bank:TaxReserve balance always shows what’s already “spoken for.” You know at a glance that this cash isn't available for other business expenses.
• Accurate Profit: Because the reserve is treated as a transfer between asset accounts, your Profit & Loss statement isn’t distorted. You only record the tax liability when you actually file and pay it.
• Audit Trail: Every payment to the IRS or your state treasury ties back to a clearly tagged movement from your reserve account, creating a clean paper trail.

4. Fine-Tuning Your Percentage​

The initial 25% - 30% estimate is a great start, but you should adjust it based on your specific business model.

• High-Margin Consultants / Agencies: If you clear well above the Social Security wage base ($176,100), your effective tax rate will climb. A rate of 30% - 35% is likely more accurate.
• Product Businesses with Heavy Deductions: If you have significant costs of goods sold (COGS), inventory, or other deductions, your net profit margin is lower. A rate of 20% - 25% may suffice. Use Form 1040-ES worksheets each quarter to confirm.
• S-Corp Owners: Your situation is different. The "reasonable salary" you pay yourself is subject to standard payroll withholding (FICA and income taxes). Your distributions (profits paid out beyond salary) still require quarterly estimated payments, but often at a lower marginal rate since they aren't subject to SE tax.
• Multi-State Sellers: If you have "nexus" (a significant business presence) in multiple states, you may owe income tax in each. This can stack your liabilities. For clarity, create separate liability accounts in Beancount, such as Liabilities:Taxes:State:CA and Liabilities:Taxes:State:NY.

5. Automate, Review, Repeat​

A system only works if you use it. Make it effortless.

• Automate: Link your main operating account to a high-yield savings account named something like "TaxReserve." Schedule an automatic transfer to occur right after you close your books each month.
• Review: Re-forecast your annual profit quarterly. If Q2 sales blew past expectations, increase your monthly reserve amount immediately. Don't wait until January to discover you've under-saved.
• Repeat: Keep key documents organized within your Beancount directory. Saving last year’s final tax return (document: "2024/Taxes/Form1040.pdf") gives you one-click context when discussing numbers with your CPA or planning for the next year.

Closing Thoughts​

Tax bills feel random only when the set-aside process is. By baking a percentage-based reserve directly into your double-entry accounting flow, you trade anxiety for algebra—and Beancount makes the math (and the audit trail) trivial. Review your rate each quarter, keep Assets:Bank:TaxReserve funded, and April 15th turns back into just another day of business as usual.

Disclaimer: This article is for educational purposes only and isn’t tax advice. Always confirm numbers with a qualified professional for your jurisdiction and entity type.

When you're running a business or managing your personal finances, the terms bookkeeping and accounting often blur together. But understanding their differences—especially when using a plain-text tool like Beancount—can help you build better systems and make smarter financial decisions.

In this guide, we’ll explore the roles of bookkeeping and accounting, and how Beancount supports both (yes, really).

📘 Bookkeeping: The Art of Daily Tracking​

Bookkeeping is the foundational layer of financial management. It’s about recording what actually happened—no assumptions, no forecasts.

Bookkeeping includes:

• Recording income and expenses
• Keeping track of assets and liabilities
• Tagging transactions for later use
• Maintaining a general ledger

In Beancount, this looks like:

2025-06-27 * "Stripe Payout"
  Assets:Bank:Checking     1,200.00 USD
  Income:Sales

Each transaction is a building block. You’re not analyzing yet—you’re simply recording the truth, one line at a time.

If you're just starting out, Beancount encourages good bookkeeping habits through its explicit structure and readable syntax. You’ll be forced (in a good way!) to track every cent and explain every transaction.

📊 Accounting: Turning Data Into Insight​

Accounting builds on your bookkeeping records to answer deeper questions:

• Are we profitable?
• How much cash runway do we have?
• Should we prepay for that software or expense it monthly?
• How do we minimize taxes?

In accounting, you:

• Reconcile accounts and adjust entries
• Generate reports like profit/loss statements
• Depreciate assets
• Plan for taxes and future expenses

With Beancount, you can analyze your records using tools like beancount.io:

• Navigate balance sheets, income statements, and cash flow charts
• Visualize income by category
• Annotate decisions using metadata (e.g., tag:business-trip)

Want to track that annual Zoom subscription?

2025-01-15 * "Zoom Annual Plan"
  Expenses:Software     149.90 USD
  Assets:Bank:Checking
  tag:business-tools

You can later amortize it monthly or analyze it during budgeting sessions.

👩‍💼 Bookkeeper vs. Accountant: Who Does What?​

• Bookkeeper: Focuses on precision. Records, categorizes, and organizes.
• Accountant: Adds interpretation. Advises, plans, and models outcomes.

Beancount empowers you to be both, or to cleanly hand off one layer to a professional.

For example:

• As a founder, you may do your own bookkeeping with Beancount.
• At tax season, you export reports or raw data for your accountant to finalize.

🛠️ Bookkeeping and Accounting Software: Where Does Beancount Belong?​

Most mainstream tools (e.g., QuickBooks, Xero) blur the line between bookkeeping and accounting. Beancount takes a different approach:

• You manage everything through plain text, stored in version control if you like.
• There's no hiding of transactions or behind-the-scenes magic.
• You're encouraged to understand your own books.

Beancount is ideal for those who value transparency, data integrity, and automation through open-source tools.

🧠 Why This Distinction Matters​

Knowing the difference between bookkeeping and accounting helps you:

• Stay compliant and audit-ready
• Understand where to invest time (daily tracking vs. monthly insights)
• Communicate clearly with financial professionals
• Scale your financial systems without drowning in complexity

🪄 Final Thought: Your Ledger, Your Rules​

Whether you're a solo creator or a small business owner, Beancount gives you the power to manage your books with precision—and eventually make strategic decisions like a CFO.

Remember:

• Bookkeeping = what happened
• Accounting = what it means

With Beancount, you’re building both layers with clarity and confidence.

Let me know if you'd like a printable version or a tutorial follow-up.

Every financial transaction your business makes needs to be recorded—and in the world of plain-text accounting, this starts with journal entries. If you're using Beancount, understanding journal entries is key to building accurate, auditable, and clean financial records.

This guide will walk you through:

• What a journal entry is
• Why journal entries matter
• How to write them in Beancount syntax
• How to use them effectively
• Examples of real-world transactions (client payments, purchases, loans, etc.)

🧾 What is a Journal Entry in Beancount?​

In Beancount, a journal entry is a dated transaction written in a human-readable plain-text format. Each entry follows the principles of double-entry accounting—you record where money comes from (credit) and where it goes (debit), ensuring your books always balance.

Example:

2024-06-01 * "Client payment for invoice #123"
  Assets:Bank:Checking     600.00 USD
  Income:Sales

• The * indicates a cleared transaction.
• The description shows context for the entry.
• Assets:Bank:Checking is debited.
• Income:Sales is credited (value implied).

Every entry lives inside a .beancount file—just a text file you can version, back up, and even edit in Vim or VSCode.

📒 Why Journal Entries Matter​

Journal entries are the atomic unit of your ledger.

They:

• Feed into your General Ledger and Account Balances
• Drive all reports: Income Statements, Balance Sheets, Cash Flows
• Let you trace every dollar, line by line, to its source

With the right tools, you'll see these transactions rendered in a UI—categorized, searchable, and filterable. But it all starts with that simple plain-text entry.

📚 How Double-Entry Works in Beancount​

Beancount enforces double-entry accounting. Every transaction must be balanced: total debits = total credits.

Quick rule:

• Debit assets and expenses (you gain cash or incur a cost)
• Credit income and liabilities (you earn money or take on debt)

Example – Office Supplies Purchase:

2024-06-02 * "Bought printer ink"
  Expenses:OfficeSupplies   100.00 USD
  Assets:Bank:Checking

🧠 Visualizing Entries​

Once you save, on the left side navigation of https://beancount.io/ledger/0/income_statement/ you will see ...

• Journal View: See transactions with search, tags, and filtering
• Account Filter Dropdown: See running balances and per-account entries
• Income Statement: Sum of your Income:* and Expenses:* accounts
• Balance Sheet: Your assets minus liabilities

Fava helps turn your raw Beancount entries into actionable reports—with zero database setup.

💡 Common Journal Entry Examples​

✅ You get paid by a client​

2024-06-05 * "Payment for invoice #456"
  Assets:Bank:Checking     1,200.00 USD
  Income:Consulting

Optional: If you use Accounts Receivable:

2024-05-20 * "Invoice #456 sent"
  Assets:AccountsReceivable   1,200.00 USD
  Income:Consulting

2024-06-05 * "Payment for invoice #456"
  Assets:Bank:Checking        1,200.00 USD
  Assets:AccountsReceivable  -1,200.00 USD

🖨️ You buy office supplies​

2024-06-07 * "Staples run"
  Expenses:OfficeSupplies     85.00 USD
  Assets:Bank:Checking

🏦 You make a loan payment​

Let’s say you pay $1,000, with $200 in interest and $800 toward principal:

2024-06-10 * "Loan repayment"
  Liabilities:Loan           -800.00 USD
  Expenses:LoanInterest       200.00 USD
  Assets:Bank:Checking      -1,000.00 USD

🔒 Closing Entries at Year-End​

To “close the books,” you typically transfer all Income and Expenses accounts into Equity.

2024-12-31 close Income:*
2024-12-31 close Expenses:*

Or, manually:

2024-12-31 * "Close books"
  Equity:RetainedEarnings     45,000.00 USD
  Income:Consulting          -45,000.00 USD

🛠️ Adjusting Entries​

If you're doing accrual accounting, you’ll want to add adjusting entries—for prepaid expenses, accrued revenue, etc.

Example: $100 monthly software subscription paid annually

2024-01-01 * "Annual software payment"
  Assets:Prepaid             1,200.00 USD
  Assets:Bank:Checking      -1,200.00 USD

2024-01-31 * "Monthly amortization"
  Expenses:Software           100.00 USD
  Assets:Prepaid             -100.00 USD

Automate with scripts or available Beancount tools.

🧰 Beancount: Lightweight, Auditable, Powerful​

Beancount isn't just an accounting tool—it's an idea: transparent, plaintext financial truth. It's a modern ledgering system that's:

• Easy to version-control (Git!)
• Fully portable (no proprietary database)
• Great for devs, freelancers, and small businesses

Ready to Start?​

Start your Beancount file with:

option "title" "My Business Ledger"
option "operating_currency" "USD"

2024-01-01 open Assets:Bank:Checking USD
2024-01-01 open Income:Sales USD
2024-01-01 open Expenses:OfficeSupplies USD
2024-01-01 open Equity:OpeningBalances USD

2024-01-01 * "Initial balance"
  Assets:Bank:Checking     10,000.00 USD
  Equity:OpeningBalances

Then load your file with your preferred visualization tool to see the magic.

Want an easier start? Try templates, importers, or community tools like bean-extract.

With Beancount, your books are finally your own—simple, scriptable, and audit-proof.

Let me know if you’d like a downloadable PDF version or small business–specific variations of the examples.

Bookkeeping Basics You Can Actually Understand—and Own​

Managing your own books doesn’t have to mean spreadsheets, stress, or expensive software. Beancount gives you a minimalist, auditable, and powerful way to do bookkeeping using just plain text and a double-entry accounting system.

This guide is your complete introduction to getting your small business books in order with Beancount—with real examples and step-by-step direction.

🧾 What Is Beancount?​

Beancount is an open-source plain-text accounting system built around double-entry bookkeeping. You write your transactions in .beancount files and use tools like bean-doctor, bean-report, or Fava to analyze and visualize your books.

Here’s a basic transaction:

2025-06-01 * "Client Payment: Invoice #123"
  Assets:Bank:Business:Checking      1,200.00 USD
  Income:Consulting                 -1,200.00 USD

It's readable, scriptable, and version-controllable—perfect for business owners who want transparency and control.

📌 Why Bookkeeping Matters (and Why Beancount)​

• You need it for taxes
• You need it for clarity
• You need it for funding
• You need it to catch mistakes early

And with Beancount, you can do all of this with just a text editor and a few tools.

🪜 8 Steps to Start Doing Your Own Bookkeeping with Beancount​

1. Separate Business & Personal Finances​

Open a separate business checking account and credit card. Reflect that in Beancount:

2025-06-01 open Assets:Bank:Business:Checking USD
2025-06-01 open Liabilities:CreditCard:Business USD

This keeps your books clean and protects you legally (especially if you're an LLC or corporation).

2. Use Double-Entry Bookkeeping​

Every financial event affects two accounts. Beancount forces this balance by design:

2025-06-05 * "Web hosting payment"
  Expenses:Hosting                  15.00 USD
  Assets:Bank:Business:Checking    -15.00 USD

This guarantees mathematical integrity across your ledger.

3. Choose Cash or Accrual Basis​

• Cash Basis: Only record income/expenses when money is received/spent.
• Accrual Basis: Track obligations (Accounts Payable/Receivable).

Cash basis example:

2025-06-10 * "Client payment received"
  Assets:Bank:Business:Checking     800.00 USD
  Income:Sales                     -800.00 USD

Accrual basis example (invoice sent, then payment received):

2025-06-01 * "Invoice #2001 issued"
  Assets:AccountsReceivable         800.00 USD
  Income:Sales                     -800.00 USD

2025-06-15 * "Payment received for Invoice #2001"
  Assets:Bank:Business:Checking     800.00 USD
  Assets:AccountsReceivable        -800.00 USD

4. Set Up Your Chart of Accounts​

Define your categories clearly. A minimalist example:

2025-01-01 open Income:Sales USD
2025-01-01 open Expenses:Software USD
2025-01-01 open Expenses:Meals USD
2025-01-01 open Equity:Owner USD

Tailor these to your business. Keep it consistent and descriptive.

5. Categorize Transactions (with Metadata)​

Use metadata to track context. This helps with deductions, audits, and clarity.

2025-06-18 * "Team lunch after Q2 milestone"
  Expenses:Meals                    90.00 USD
  Assets:Bank:Business:Checking    -90.00 USD
  ; business_purpose: Q2 celebration
  ; attendees: Alice, Bob, Tian

Add tags or links to receipts:

  ; receipt: ./receipts/2025-06-18-lunch.jpg

6. Store Supporting Documents​

Use Dropbox, Google Drive, or a receipts/ folder. Then link them in Beancount like:

2025-06-02 * "Domain Renewal - GoDaddy"
  Expenses:Hosting                  20.00 USD
  Assets:Bank:Business:Checking    -20.00 USD
  ; receipt: ./receipts/domain-godaddy.pdf

Auditors and tax professionals will love you.

7. Organize for Deductions​

Mark deductible expenses clearly:

2025-06-03 * "Adobe Creative Cloud Subscription"
  Expenses:Software                60.00 USD
  Assets:Bank:Business:Checking   -60.00 USD
  ; deductible: true
  ; usage: 100% business

Use custom metadata or tags like #deductible to track potential write-offs.

8. Make It a Habit​

Create a workflow. Example:

# Weekly bookkeeping routine
git pull origin main
bean-extract transactions.csv >> ledger.beancount
bean-doctor ledger.beancount
bean-check ledger.beancount
fava ledger.beancount

Or just commit to a "Beancount Friday" and reconcile everything weekly.

💼 DIY or Hire Help?​

You can do it all yourself with Beancount. But even power users should:

• Consult a CPA during setup
• Hire an accountant at tax time if needed
• Use Fava for monthly reports

You get all the power of an accounting system without vendor lock-in or subscription fees.

🛠️ Recommended Tools for Beancount Users​

• Fava – beautiful web dashboard for Beancount files
• bean-doctor – health checks for your ledger
• bean-query – run SQL-like reports
• beancount-import / beanie – automated bank import
• Version control – use Git to track changes to your books

✅ Final Example: Complete Transaction Flow​

2025-06-20 * "Consulting payment from Acme Inc."
  Assets:Bank:Business:Checking        3,000.00 USD
  Income:Consulting                  -3,000.00 USD
  ; invoice: 2025-06-acme
  ; project: "Backend API redesign"

2025-06-21 * "Notion Pro Plan"
  Expenses:Software                     10.00 USD
  Assets:Bank:Business:Checking        -10.00 USD
  ; purpose: project documentation
  ; receipt: ./receipts/notion-june.pdf

🎯 Summary​

Beancount is perfect for small business owners who want to:

• Keep costs low
• Stay fully in control of their finances
• Avoid the bloat of legacy software
• Embrace transparency and plain-text simplicity

Would you like a downloadable .bean starter template for your business? Let me know your business type, and I’ll build one tailored for you.

In today's world, Environmental, Social, and Governance (ESG) metrics are no longer just buzzwords; they're essential indicators of a company's health and future viability. But how do you integrate these crucial sustainability insights with traditional financial accounting? Enter Beancount, an open-source, plain-text double-entry ledger that offers a surprisingly powerful and flexible solution for bridging this gap.

Imagine transforming your fragmented sustainability reporting into a streamlined, automated system that tracks everything from carbon emissions to supplier diversity, all within your existing financial workflow. Beancount makes this possible by treating ESG data as "first-class citizens alongside financial transactions."

Modeling ESG Data: The Beancount Way​

Beancount's inherent flexibility is its superpower when it comes to ESG. Instead of siloed spreadsheets, you can embed sustainability metrics directly into your financial structure using a few key techniques:

• Dedicated Accounts and Commodities: Think of your environmental footprint like another currency. You can create accounts like Metrics:Emissions:CO2e to track carbon emissions. These emissions can even be treated as a commodity (e.g., a unit of CO2 equivalent, tCO2e), allowing you to record specific quantities in your transactions. For instance, a flight purchase could credit an Emissions:CO2e account with +0.3 tCO2e alongside the monetary cost.
• Custom Metadata Tags: Beancount's key-value metadata is perfect for adding context. You can tag a transaction with CO2e: 0.3 t or Scope: 3 to denote its carbon impact or GHG Protocol scope. This links financial outlays directly to their environmental consequences, providing a richer, more complete picture.
• Structured Tags for Categories: Aligning with standards like the Greenhouse Gas Protocol (GHGP) is crucial. You can use consistent tags or account naming conventions, such as Metrics:Emissions:Scope1, Metrics:Emissions:Scope2, and Metrics:Emissions:Scope3 to easily categorize and report on direct, energy-related, and value chain emissions.

This adaptable approach means that as ESG standards evolve, you can adjust your ledger structure without a complete overhaul.

Beancount vs. Specialized ESG Tools: A Strategic Choice​

While dedicated ESG platforms like Persefoni or SAP Green Ledger offer highly automated, purpose-built solutions, Beancount presents a compelling alternative, particularly for those seeking transparency and control.

Beancount is a DIY powerhouse: It gives you unparalleled flexibility and transparency, making it ideal for individuals or technically savvy small organizations. You own your data completely, avoiding vendor lock-in.

Specialized tools offer turnkey solutions: They excel at automated data collection, built-in emission factor databases, and ready-made compliance reports, often at a higher cost and with less flexibility.

A hybrid approach is also viable: use Beancount for detailed internal tracking and reconciliation, then export summary data to an external platform for high-level stakeholder reporting.

Real-World Applications: ESG in Action with Beancount​

Beancount’s versatility makes it suitable for several key ESG use cases:

• Tracking Scope 3 Emissions: The most challenging emissions to track (from your value chain) can be integrated by linking supplier emissions data to purchase transactions. Beancount provides a clear audit trail for these complex figures, enabling better analysis and pinpointing data sources.
• Sustainability Audits and Assurance: Like financial data, ESG figures need to be verifiable. Beancount allows you to link each ESG entry to source documents (e.g., utility bills, third-party verification statements), providing a meticulous audit trail for transparency and assurance.
• EU CSRD/ESRS Compliance Reporting: For companies facing stringent regulations like CSRD, Beancount can serve as a central repository for quantitative disclosures. While it won't automatically format reports into XBRL, it provides the granular, auditable data needed to generate compliance-ready figures.
• Carbon Footprint Analysis & Management Accounting: Treat carbon as another dimension of management accounting. By allocating emissions to profit centers or product codes, you can calculate metrics like "emissions per dollar of revenue" and identify carbon hotspots, driving more informed sustainability decisions.

Best Practices for Your Beancount ESG Ledger​

To maximize the effectiveness of Beancount for ESG, consider these best practices:

1. Design a Clear Chart of Accounts for ESG: Structure your ESG accounts thoughtfully (e.g., Metrics:Emissions:Scope1:Fuel), just like your financial accounts.
2. Use Metadata Consistently: Leverage tags (e.g., Scope: 3, FactorSource: EPA2024) for consistent context and easier querying.
3. Balance Granularity with Manageability: Focus on material metrics to avoid overwhelming your ledger with unnecessary detail.
4. Automate with Caution: Use Python scripts for data import and validation, but ensure robust error checking and clear documentation of your automation processes.
5. Leverage Version Control: Use Git to track every change to your ledger, providing a transparent and auditable history of your ESG data.
6. Connect to Documents and Evidence: Link source files (e.g., PDFs of utility bills) to ledger entries for easy verification during audits.
7. Utilize Fava for Insights: Configure Fava to display custom ESG charts and reports, making your sustainability data actionable and accessible to non-technical stakeholders.
8. Stay Updated on Standards: ESG reporting is dynamic; be prepared to adapt your Beancount structure as new regulations and frameworks emerge.

The Future is Green, and Plain-Text​

While Beancount currently lacks native ESG intelligence or plug-and-play reporting, its open-source nature presents immense opportunities for enhancement. Community-driven plugins for carbon accounting, standardized ESG ledger templates, and better integration with emission factor APIs could significantly boost its capabilities.

As the corporate world increasingly embraces "green ledgers," Beancount stands ready as a flexible, transparent, and auditable solution. By integrating ESG data with the same rigor as financial data, Beancount empowers organizations to not only meet compliance demands but also drive meaningful sustainability initiatives.

Are you ready to bring your ESG data into the plain-text revolution?

Are you drowning in crypto transactions across multiple exchanges, struggling with DeFi complexity, or panicking about tax season? You're not alone. The cryptocurrency landscape has exploded from simple Bitcoin purchases to a sophisticated ecosystem of DeFi protocols, staking rewards, yield farming, and cross-chain activities that challenge traditional accounting methods.

Here's the harsh reality: every crypto transaction is potentially taxable, and the IRS is watching. Whether you're a casual Bitcoin holder or a DeFi power user managing positions across dozens of protocols, maintaining accurate financial records isn't optional—it's essential for compliance and financial clarity.

The problem? Traditional accounting software has limited native support for crypto's complexity. While tools like QuickBooks can handle crypto with additional plugins, and Excel can import blockchain data with scripts, most solutions require significant customization for comprehensive crypto accounting.

The solution? Beancount.io's plain-text accounting system built on the powerful open-source Beancount language. Important note: Beancount is an open-source double-entry accounting language created by Martin Blais, while Beancount.io is a commercial hosting service that provides a user-friendly interface and cloud infrastructure for Beancount. This guide covers both the underlying Beancount principles and how to use them effectively through the Beancount.io platform.

The Cryptocurrency Accounting Nightmare (And Why It's Getting Worse)​

Your Crypto Portfolio is Scattered Everywhere​

Let's be honest about your setup. You probably have:

• 3-5 different exchanges (Coinbase for easy buys, Binance for altcoins, Kraken for that one token...)
• Multiple wallets (MetaMask for DeFi, Ledger for long-term holds, that old wallet you forgot about...)
• DeFi positions across 10+ protocols (Uniswap, Compound, Aave, and whatever new yield farm caught your attention)
• Staking rewards trickling in from various validators
• Random airdrops appearing in your wallet like crypto Christmas presents

Each platform speaks a different language. Coinbase gives you a CSV that looks nothing like Binance's export. Uniswap doesn't even have exports. And don't get me started on tracking your DeFi positions across Layer 2 networks.

Transaction Types That Challenge Traditional Accounting​

Your crypto activities include transaction types that traditional accounting systems weren't originally designed to handle:

• Impermanent loss from liquidity providing (try explaining that to QuickBooks)
• Flash loans that borrow and repay millions in a single transaction
• Yield farming where you earn 5 different tokens for providing liquidity
• Cross-chain bridges that make assets disappear on one network and appear on another
• Staking derivatives like stETH that accrue value differently than the underlying asset
• DAO governance tokens that you received for using protocols

The Tax Compliance Minefield​

Here's what keeps crypto investors awake at night:

• Every single trade is taxable (yes, even that ETH-to-USDC swap)
• Cost basis tracking becomes impossible with hundreds of micro-transactions
• Staking rewards are income the moment you receive them (at fair market value)
• DeFi rewards are income even if you can't sell them yet
• The IRS wants Form 8949 with every single transaction listed
• Penalties are severe for getting it wrong

Traditional accounting software requires significant customization for this complexity. While solutions exist, they often require additional plugins, scripts, or manual processes to handle the full scope of cryptocurrency activities.

Enter Beancount.io: The Crypto Accounting Solution You've Been Waiting For​

What if I told you there's an accounting system designed for exactly this chaos? Beancount.io isn't just another accounting tool—it's a plain-text accounting revolution that handles cryptocurrency complexity like it was born for it.

Why Beancount.io Dominates Crypto Accounting​

🔍 Complete Transparency: Every calculation is visible. No black boxes, no "trust us" algorithms. You see exactly how your cost basis is calculated, how gains are computed, and where every satoshi went.

📊 Unlimited Flexibility: Create any account structure you need. Track DeFi positions, staking derivatives, cross-chain assets, or that weird token you got from a DAO vote. If you can imagine it, you can track it.

🎯 Precise Cost Basis: Lot-based tracking with specific identification. Choose exactly which Bitcoin you're selling for optimal tax outcomes. FIFO, LIFO, or cherry-pick your lots—your choice.

🔗 Future-Proof: Plain-text format means your data is yours forever. No vendor lock-in, no proprietary formats, no "sorry, we're shutting down" emails.

⚡ Scriptable Power: Automate imports, generate custom reports, and integrate with any tool. Because your crypto portfolio is unique, your accounting should be too.

Setting Up Your Crypto Command Center​

Building Your Account Architecture​

Think of this as designing the blueprint for your crypto empire. We're creating a structure that can handle everything from your first Bitcoin purchase to complex multi-protocol DeFi strategies:

Note: The examples use 1970-01-01 as a placeholder opening date. For actual use, replace with your real account opening dates, especially if using automated import tools that filter transactions by date.

; Exchange Accounts
1970-01-01 open Assets:Crypto:Coinbase:USD
1970-01-01 open Assets:Crypto:Coinbase:BTC
1970-01-01 open Assets:Crypto:Coinbase:ETH
1970-01-01 open Assets:Crypto:Binance:USD
1970-01-01 open Assets:Crypto:Binance:BTC
1970-01-01 open Assets:Crypto:Binance:ETH
1970-01-01 open Assets:Crypto:Binance:ADA

; Wallet Accounts
1970-01-01 open Assets:Crypto:Wallet:MetaMask:ETH
1970-01-01 open Assets:Crypto:Wallet:MetaMask:USDC
1970-01-01 open Assets:Crypto:Wallet:MetaMask:UNI
1970-01-01 open Assets:Crypto:Wallet:Ledger:BTC
1970-01-01 open Assets:Crypto:Wallet:Ledger:ETH

; DeFi Protocol Accounts
1970-01-01 open Assets:DeFi:Compound:cUSDC
1970-01-01 open Assets:DeFi:Uniswap:ETH-USDC-LP
1970-01-01 open Assets:Staking:Ethereum:ETH
1970-01-01 open Assets:Crypto:Mining:BTC

; Income Accounts
1970-01-01 open Income:Crypto:Staking:ETH
1970-01-01 open Income:Crypto:Mining:BTC
1970-01-01 open Income:Crypto:Airdrops
1970-01-01 open Income:Crypto:DeFi:Yield
1970-01-01 open Income:CapitalGains:Crypto
1970-01-01 open Income:Crypto:Trading:Margin

; Expense Accounts
1970-01-01 open Expenses:Crypto:Fees:Trading
1970-01-01 open Expenses:Crypto:Fees:Network
1970-01-01 open Expenses:Crypto:Fees:Withdrawal

; Additional accounts for advanced scenarios
1970-01-01 open Assets:Crypto:Binance:BTC-Margin
1970-01-01 open Liabilities:Crypto:Binance:Borrowed
1970-01-01 open Liabilities:Crypto:Binance:BTC
1970-01-01 open Assets:Checking
1970-01-01 open Expenses:Crypto:Mining:Electricity

Commodity Definitions​

Define your cryptocurrencies as commodities with proper metadata:

1970-01-01 commodity BTC
  name: "Bitcoin"
  asset-class: "cryptocurrency"
  price-source: "coinbase"

1970-01-01 commodity ETH
  name: "Ethereum"
  asset-class: "cryptocurrency"
  price-source: "coinbase"

1970-01-01 commodity ADA
  name: "Cardano"
  asset-class: "cryptocurrency"
  price-source: "binance"

1970-01-01 commodity USDC
  name: "USD Coin"
  asset-class: "stablecoin"
  price-source: "coinbase"

1970-01-01 commodity UNI
  name: "Uniswap"
  asset-class: "cryptocurrency"
  price-source: "coinbase"

1970-01-01 commodity UNI-V2-ETH-USDC
  name: "Uniswap V2 ETH-USDC LP Token"
  asset-class: "liquidity-pool"

Mastering Crypto Transactions: From Simple to Sophisticated​

Ready to see Beancount.io in action? Let's walk through real-world scenarios that would break other accounting systems but are handled elegantly here.

1. Your First Bitcoin Purchase (The Gateway Drug)​

Every crypto journey starts somewhere. Here's how to record that life-changing moment when you bought your first Bitcoin:

2024-01-15 * "Buy 0.5 BTC on Coinbase"
  Assets:Crypto:Coinbase:BTC     0.5 BTC {30000.00 USD}
  Assets:Crypto:Coinbase:USD  -15025.00 USD
  Expenses:Crypto:Fees:Trading    25.00 USD

2. Taking Profits (Or Cutting Losses) Like a Pro​

The moment of truth: selling your crypto. This is where most accounting systems fall apart, but Beancount.io shines with precise cost basis tracking:

2024-03-20 * "Sell 0.3 BTC on Coinbase"
  Assets:Crypto:Coinbase:BTC    -0.3 BTC {30000.00 USD}
  Assets:Crypto:Coinbase:USD   10470.00 USD
  Expenses:Crypto:Fees:Trading    30.00 USD
  Income:CapitalGains:Crypto   1440.00 USD  ; 10470 - (0.3 × 30000) - 30 = 1440

3. Staking Rewards: Earning While You Sleep​

Passive income at its finest. But remember, the IRS requires staking rewards to be reported as taxable income when received, based on fair market value at the time of receipt (per IRS Digital Assets guidance, 2024). While there is ongoing litigation (Jarrett v. United States), the current official position requires immediate reporting. Here's how to track them properly:

2024-02-01 * "ETH Staking Rewards"
  Assets:Staking:Ethereum:ETH      0.05 ETH {2500.00 USD}
  Income:Crypto:Staking:ETH      125.00 USD

4. DeFi Yield Farming: Where Things Get Spicy 🌶️​

Welcome to advanced DeFi accounting. DeFi yield farming involves complex multi-token transactions that require sophisticated tracking. Here's how to properly account for a Uniswap liquidity position:

; Initial liquidity provision
2024-01-10 * "Add liquidity to ETH-USDC pool"
  Assets:Crypto:Wallet:MetaMask:ETH    -10 ETH {2500.00 USD}
  Assets:Crypto:Wallet:MetaMask:USDC -25000 USDC {1.00 USD}
  Assets:DeFi:Uniswap:ETH-USDC-LP     100 UNI-V2-ETH-USDC {500.00 USD}

; Claiming rewards
2024-02-10 * "Claim Uniswap LP rewards"
  Assets:Crypto:Wallet:MetaMask:UNI    50 UNI {8.00 USD}
  Income:Crypto:DeFi:Yield           400.00 USD

5. Cross-Exchange Transfers​

Moving Bitcoin from Coinbase to Ledger wallet:

2024-01-20 * "Transfer BTC from Coinbase to Ledger"
  Assets:Crypto:Coinbase:BTC      -1.0 BTC {30000.00 USD}
  Assets:Crypto:Wallet:Ledger:BTC  0.9995 BTC {30000.00 USD}
  Expenses:Crypto:Fees:Withdrawal  0.0005 BTC {30000.00 USD}

Advanced Cryptocurrency Scenarios​

Margin Trading​

Recording leveraged positions:

; Opening a leveraged long position (borrowing BTC)
2024-02-15 * "Open 2x leveraged BTC position"
  Assets:Crypto:Binance:BTC-Margin      1.0 BTC {35000.00 USD}
  Liabilities:Crypto:Binance:BTC       -1.0 BTC {35000.00 USD}
  Expenses:Crypto:Fees:Trading            50.00 USD
  Assets:Crypto:Binance:USD              -50.00 USD

; Closing the position with profit
2024-02-20 * "Close leveraged BTC position"
  Assets:Crypto:Binance:BTC-Margin   -1.0 BTC {35000.00 USD}
  Assets:Crypto:Binance:USD          37950.00 USD
  Liabilities:Crypto:Binance:BTC      1.0 BTC {35000.00 USD}
  Income:Crypto:Trading:Margin       -2900.00 USD
  Expenses:Crypto:Fees:Trading          50.00 USD

Airdrops and Forks​

Recording free token distributions:

2024-03-01 * "Received UNI airdrop"
  Assets:Crypto:Wallet:MetaMask:UNI   400 UNI {8.00 USD}
  Income:Crypto:Airdrops             3200.00 USD

Mining Operations​

For cryptocurrency miners:

2024-01-01 * "Bitcoin mining reward"
  Assets:Crypto:Mining:BTC    0.1 BTC {45000.00 USD}
  Income:Crypto:Mining:BTC   4500.00 USD

; Mining expenses
2024-01-31 * "Mining electricity costs"
  Expenses:Crypto:Mining:Electricity  800.00 USD
  Assets:Checking                    -800.00 USD

Tax Reporting and Compliance​

Cost Basis Tracking​

Beancount.io automatically tracks cost basis using the lot-based system:

; Multiple purchases at different prices
2024-01-01 * "Buy BTC batch 1"
  Assets:Crypto:Coinbase:BTC  1.0 BTC {40000.00 USD}
  Assets:Crypto:Coinbase:USD -40000.00 USD

2024-02-01 * "Buy BTC batch 2"
  Assets:Crypto:Coinbase:BTC  1.0 BTC {45000.00 USD}
  Assets:Crypto:Coinbase:USD -45000.00 USD

; Selling specific lots (FIFO, LIFO, or specific identification)
2024-03-01 * "Sell BTC using FIFO"
  Assets:Crypto:Coinbase:BTC    -0.5 BTC {40000.00 USD}
  Assets:Crypto:Coinbase:USD   22470.00 USD
  Expenses:Crypto:Fees:Trading    30.00 USD
  Income:CapitalGains:Crypto    2440.00 USD  ; 22470 - 20000 - 30 = 2440

Generating Tax Reports​

Use Beancount's query system and plugins to generate tax reports:

• Form 8949: Capital gains and losses (via bean-query or third-party plugins)
• Schedule D: Summary of capital gains (requires additional scripting)
• Form 1040: Income from staking, mining, airdrops (via custom reports)
• Detailed transaction logs: For audit purposes

Note: Tax report generation requires additional plugins, scripts, or integration with specialized tax software. Beancount provides the data foundation, but specific tax forms typically require custom development or third-party tools.

Best Practices for Crypto Accounting​

1. Regular Reconciliation​

• Import exchange data weekly
• Verify wallet balances monthly
• Cross-check with blockchain explorers

2. Proper Documentation​

• Save all transaction confirmations
• Document the purpose of each transaction
• Maintain records of market prices at transaction time

3. Separate Business and Personal​

; Personal crypto investments
Assets:Personal:Crypto:Coinbase:BTC

; Business crypto operations
Assets:Business:Crypto:Treasury:BTC

4. Track All Income Sources​

• Staking rewards (taxable as income)
• Mining rewards (taxable as income)
• Airdrops (taxable at fair market value)
• DeFi yield (taxable as income)

5. Fee Management​

Track all fees separately for proper tax deduction:

Expenses:Crypto:Fees:Trading     ; Exchange trading fees
Expenses:Crypto:Fees:Network     ; Blockchain network fees
Expenses:Crypto:Fees:Withdrawal  ; Withdrawal fees

Integration with Popular Crypto Tools​

Exchange API Integration​

Beancount.io can integrate with major exchanges:

• Coinbase Pro API: Automatic transaction import
• Binance API: Real-time balance updates
• Kraken API: Historical data synchronization

Blockchain Analysis​

Connect with blockchain explorers:

• Etherscan: Ethereum transaction verification
• Blockchain.info: Bitcoin transaction tracking
• BscScan: Binance Smart Chain monitoring

Portfolio Tracking​

Sync with portfolio management tools:

• CoinTracker: Tax report generation
• Koinly: Multi-exchange aggregation
• Blockfolio: Mobile portfolio tracking

Important Disclaimers​

Tax and Legal Notice: This guide provides general information about cryptocurrency accounting using Beancount and does not constitute professional tax, legal, or financial advice. Tax treatment of cryptocurrency transactions varies by jurisdiction and individual circumstances. Complex scenarios like cross-chain bridges, impermanent loss, and flash loans may have unclear tax implications under current regulations. For specific guidance on whether transactions constitute taxable dispositions, refer to IRS FAQ Q-15 through Q-18 (2024) or consult local tax regulations. Always consult with a qualified tax professional or CPA familiar with cryptocurrency taxation in your jurisdiction before making tax-related decisions.

Software Clarification: Examples in this guide use standard Beancount syntax. While Beancount.io provides a user-friendly interface for Beancount, the underlying accounting principles apply to any Beancount implementation.

Conclusion​

Cryptocurrency accounting doesn't have to be overwhelming. With Beancount's powerful plain-text accounting system, accessible through Beancount.io's platform, you can:

• Maintain Complete Transparency: Every transaction is visible and auditable
• Ensure Tax Compliance: Proper cost basis tracking and income reporting
• Scale with Your Portfolio: Handle simple trades to complex DeFi strategies
• Integrate Seamlessly: Connect with exchanges, wallets, and tax tools
• Future-Proof Your Records: Plain-text format ensures long-term accessibility

Whether you're a casual Bitcoin holder or a sophisticated DeFi yield farmer, Beancount provides the foundation and flexibility needed to master cryptocurrency accounting. Start with basic transactions and gradually incorporate more complex scenarios as your crypto journey evolves.

The examples in this guide provide a solid foundation, but remember that cryptocurrency accounting is an evolving field. Stay informed about regulatory changes, consult with tax professionals, and adapt your accounting practices as needed.

Ready to take control of your cryptocurrency finances? Sign up for Beancount.io and experience the power of transparent, scriptable crypto accounting built on the robust Beancount foundation.

Cryptocurrency taxation has evolved from a niche concern to a critical compliance requirement for millions of investors. With the IRS increasing enforcement and requiring detailed reporting, accurate record-keeping isn't just good practice—it's essential for avoiding penalties and optimizing your tax liability.

This comprehensive guide shows you how to achieve complete cryptocurrency tax compliance using Beancount.io's powerful plain-text accounting system, ensuring you meet all IRS requirements while maximizing tax efficiency.

Understanding Cryptocurrency Tax Requirements​

IRS Treatment of Cryptocurrency​

The IRS treats cryptocurrency as property, not currency, which creates specific tax implications:

• Every transaction is potentially taxable: Trading, selling, spending, or exchanging crypto
• Cost basis must be tracked: For every unit of cryptocurrency owned
• Holding period determines tax rate: Short-term vs. long-term capital gains
• Income recognition required: For mining, staking, airdrops, and DeFi rewards
• Detailed records mandatory: Transaction-level documentation for audits

Key Tax Forms for Cryptocurrency​

Form 1040 - Individual Income Tax Return​

• Line 1: Report crypto income (staking, mining, airdrops)
• Schedule 1: Additional income sources
• Digital Asset Question: Must answer "Yes" if you had crypto transactions

Form 8949 - Sales and Other Dispositions of Capital Assets​

• Part I: Short-term capital gains/losses (held ≤ 1 year)
• Part II: Long-term capital gains/losses (held > 1 year)
• Detailed transaction reporting: Date acquired, date sold, proceeds, cost basis

Schedule D - Capital Gains and Losses​

• Summary of Form 8949: Aggregated capital gains/losses
• Net capital gain/loss: Final calculation for tax liability

Setting Up Tax-Compliant Crypto Accounting​

Account Structure for Tax Reporting​

Design your account hierarchy to align with tax requirements:

; Assets - Organized by holding period and source
1970-01-01 open Assets:Crypto:ShortTerm:Coinbase:BTC
1970-01-01 open Assets:Crypto:LongTerm:Coinbase:BTC
1970-01-01 open Assets:Crypto:Trading:Binance:ETH
1970-01-01 open Assets:Crypto:Investment:Ledger:BTC

; Income - Separated by tax treatment
1970-01-01 open Income:Crypto:Staking:Ordinary        ; Taxed as ordinary income
1970-01-01 open Income:Crypto:Mining:Ordinary         ; Taxed as ordinary income
1970-01-01 open Income:Crypto:Airdrops:Ordinary       ; Taxed as ordinary income
1970-01-01 open Income:CapitalGains:ShortTerm         ; Short-term capital gains
1970-01-01 open Income:CapitalGains:LongTerm          ; Long-term capital gains

; Expenses - Tax deductible categories
1970-01-01 open Expenses:Crypto:Fees:Deductible       ; Trading fees
1970-01-01 open Expenses:Crypto:Mining:Equipment      ; Mining equipment
1970-01-01 open Expenses:Crypto:Mining:Electricity    ; Mining electricity
1970-01-01 open Expenses:CapitalLoss:ShortTerm        ; Short-term capital losses
1970-01-01 open Expenses:CapitalLoss:LongTerm         ; Long-term capital losses

Metadata for Tax Compliance​

Use metadata to track tax-relevant information:

2024-01-15 * "Buy BTC for long-term investment" ^investment-btc #long-term
  purchase-date: "2024-01-15"
  intended-holding: "long-term"
  tax-lot-id: "BTC-001"
  Assets:Crypto:LongTerm:Coinbase:BTC  1.0 BTC {45000.00 USD}
  Assets:Crypto:Coinbase:USD         -45000.00 USD
  Expenses:Crypto:Fees:Deductible        50.00 USD
  Assets:Crypto:Coinbase:USD            -50.00 USD

Recording Taxable Cryptocurrency Events​

1. Cryptocurrency Sales​

Short-term Capital Gains (≤ 1 year)​

2024-06-15 * "Sell BTC - Short-term capital gain" ^btc-sale-001
  date-acquired: "2024-01-15"
  holding-period: "151 days"
  form-8949-code: "A"
  Assets:Crypto:ShortTerm:Coinbase:BTC  -0.5 BTC {45000.00 USD}
  Assets:Crypto:Coinbase:USD           24000.00 USD
  Expenses:Crypto:Fees:Deductible         30.00 USD
  Assets:Crypto:Coinbase:USD             -30.00 USD
  Income:CapitalGains:ShortTerm         1470.00 USD  ; 24000 - 22500 - 30

Long-term Capital Gains (> 1 year)​

2025-02-01 * "Sell BTC - Long-term capital gain" ^btc-sale-002
  date-acquired: "2024-01-15"
  holding-period: "382 days"
  form-8949-code: "D"
  Assets:Crypto:LongTerm:Coinbase:BTC   -0.5 BTC {45000.00 USD}
  Assets:Crypto:Coinbase:USD           28000.00 USD
  Expenses:Crypto:Fees:Deductible         35.00 USD
  Assets:Crypto:Coinbase:USD             -35.00 USD
  Income:CapitalGains:LongTerm          5465.00 USD  ; 28000 - 22500 - 35

2. Cryptocurrency-to-Cryptocurrency Trades​

Every crypto-to-crypto trade is taxable:

2024-03-20 * "Trade BTC for ETH - Taxable exchange"
  ; Dispose of BTC (taxable event)
  Assets:Crypto:Trading:Binance:BTC     -1.0 BTC {46000.00 USD}
  Income:CapitalGains:ShortTerm        2000.00 USD  ; 48000 - 46000
  
  ; Acquire ETH (new cost basis)
  Assets:Crypto:Trading:Binance:ETH      20 ETH {2400.00 USD}
  
  ; Trading fees
  Expenses:Crypto:Fees:Deductible        40.00 USD
  Assets:Crypto:Trading:Binance:USD     -40.00 USD

3. Staking Rewards (Ordinary Income)​

2024-01-31 * "ETH Staking Rewards - January"
  reward-type: "staking"
  fair-market-value: "2500.00 USD per ETH"
  taxable-income: "200.00 USD"
  Assets:Staking:Ethereum:ETH           0.08 ETH {2500.00 USD}
  Income:Crypto:Staking:Ordinary       200.00 USD

4. Mining Income​

2024-01-15 * "Bitcoin Mining Reward"
  mining-pool: "Slush Pool"
  block-height: "825000"
  fair-market-value: "45000.00 USD per BTC"
  Assets:Crypto:Mining:BTC              0.01 BTC {45000.00 USD}
  Income:Crypto:Mining:Ordinary        450.00 USD
  
  ; Mining expenses (deductible)
  Expenses:Crypto:Mining:Electricity    120.00 USD
  Assets:Checking                      -120.00 USD

5. Airdrops and Hard Forks​

2024-03-01 * "UNI Token Airdrop"
  airdrop-source: "Uniswap Protocol"
  fair-market-value: "8.00 USD per UNI"
  taxable-amount: "3200.00 USD"
  Assets:Crypto:Wallet:MetaMask:UNI    400 UNI {8.00 USD}
  Income:Crypto:Airdrops:Ordinary     3200.00 USD

6. DeFi Activities​

Yield Farming Rewards​

2024-02-28 * "Compound Protocol Yield"
  protocol: "Compound"
  reward-token: "COMP"
  fair-market-value: "85.00 USD per COMP"
  Assets:Crypto:Wallet:MetaMask:COMP    12 COMP {85.00 USD}
  Income:Crypto:DeFi:Ordinary         1020.00 USD

Liquidity Pool Fees​

2024-02-15 * "Uniswap LP Fees Claimed"
  protocol: "Uniswap V3"
  pool: "ETH-USDC"
  Assets:Crypto:Wallet:MetaMask:ETH     0.2 ETH {2600.00 USD}
  Assets:Crypto:Wallet:MetaMask:USDC    300 USDC
  Income:Crypto:DeFi:Ordinary          820.00 USD

Tax Optimization Strategies​

1. Tax Loss Harvesting​

Systematically realize losses to offset gains:

; Identify losing positions
2024-12-15 * "Tax Loss Harvesting - Sell ADA at loss"
  purchase-date: "2024-06-01"
  purchase-price: "0.60 USD per ADA"
  sale-price: "0.45 USD per ADA"
  Assets:Crypto:Trading:Binance:ADA    -1000 ADA {0.60 USD}
  Assets:Crypto:Trading:Binance:USD     445.00 USD
  Expenses:Crypto:Fees:Deductible         5.00 USD
  Assets:Crypto:Trading:Binance:USD      -5.00 USD
  Expenses:CapitalLoss:ShortTerm       150.00 USD  ; Realized loss

2. Wash Sale Considerations​

While wash sale rules don't officially apply to crypto, avoid potential issues:

; Wait 31 days before repurchasing
2025-01-16 * "Repurchase ADA after wash sale period"
  wash-sale-safe: "31+ days elapsed"
  Assets:Crypto:Trading:Binance:ADA    1000 ADA {0.45 USD}
  Assets:Crypto:Trading:Binance:USD    -450.00 USD
  Expenses:Crypto:Fees:Deductible         5.00 USD
  Assets:Crypto:Trading:Binance:USD      -5.00 USD

3. Specific Identification Method​

Choose which lots to sell for optimal tax outcomes:

; High-cost basis lot for loss harvesting
2024-11-30 * "Sell high-cost ETH lot for tax loss"
  lot-selection: "specific-identification"
  cost-basis: "3500.00 USD per ETH"
  sale-price: "2400.00 USD per ETH"
  Assets:Crypto:Trading:Coinbase:ETH    -5 ETH {3500.00 USD}
  Assets:Crypto:Trading:Coinbase:USD  11950.00 USD
  Expenses:Crypto:Fees:Deductible        50.00 USD
  Assets:Crypto:Trading:Coinbase:USD    -50.00 USD
  Expenses:CapitalLoss:ShortTerm      5500.00 USD  ; Significant loss

4. Long-term vs Short-term Planning​

Strategically time sales for favorable tax treatment:

; Hold for long-term treatment
2024-12-20 * "BTC approaching long-term status"
  purchase-date: "2024-01-01"
  days-held: "354"
  long-term-date: "2025-01-02"
  note: "Hold 11 more days for long-term treatment"

Automated Tax Reporting​

Form 8949 Generation​

Use Beancount.io queries to generate Form 8949 data:

-- Short-term capital gains/losses
SELECT 
  date,
  narration,
  -position as quantity_sold,
  cost(position) as cost_basis,
  value(position) as proceeds,
  value(position) + cost(position) as gain_loss
WHERE account ~ "Income:CapitalGains:ShortTerm" 
   OR account ~ "Expenses:CapitalLoss:ShortTerm"
ORDER BY date;

Schedule D Summary​

-- Capital gains summary
SELECT 
  'Short-term' as type,
  sum(position) as total_gain_loss
WHERE account ~ "Income:CapitalGains:ShortTerm" 
   OR account ~ "Expenses:CapitalLoss:ShortTerm"

UNION ALL

SELECT 
  'Long-term' as type,
  sum(position) as total_gain_loss
WHERE account ~ "Income:CapitalGains:LongTerm" 
   OR account ~ "Expenses:CapitalLoss:LongTerm";

Ordinary Income Reporting​

-- Crypto ordinary income
SELECT 
  account,
  sum(position) as total_income
WHERE account ~ "Income:Crypto.*:Ordinary"
GROUP BY account
ORDER BY total_income DESC;

Record Keeping and Documentation​

Essential Documentation​

Maintain comprehensive records for each transaction:

2024-01-15 * "BTC Purchase - Complete Documentation" ^btc-001
  exchange: "Coinbase Pro"
  transaction-id: "abc123def456"
  confirmation-hash: "0x789..."
  ip-address: "192.168.1.100"
  timestamp: "2024-01-15T14:30:00Z"
  market-price-source: "CoinGecko"
  Assets:Crypto:LongTerm:Coinbase:BTC  1.0 BTC {45000.00 USD}
  Assets:Crypto:Coinbase:USD         -45000.00 USD

Audit Trail Maintenance​

Create detailed audit trails:

; Link related transactions
2024-01-15 * "BTC Purchase" ^btc-purchase-001
2024-01-20 * "BTC Transfer to Wallet" ^btc-purchase-001
2024-06-15 * "BTC Sale" ^btc-purchase-001

Price Verification​

Document price sources for fair market value:

2024-01-15 price BTC 45000.00 USD
  source: "CoinGecko"
  timestamp: "2024-01-15T14:30:00Z"
  verification: "Multiple exchange average"

Common Tax Compliance Mistakes​

1. Missing Transactions​

• Problem: Not reporting all taxable events
• Solution: Comprehensive transaction tracking in Beancount.io

2. Incorrect Cost Basis​

• Problem: Using wrong cost basis calculation method
• Solution: Lot-based tracking with specific identification

3. Missing Income Reporting​

• Problem: Not reporting staking, mining, or airdrop income
• Solution: Separate income accounts for all sources

4. Inadequate Documentation​

• Problem: Insufficient records for audit defense
• Solution: Detailed metadata and transaction linking

5. Timing Issues​

• Problem: Incorrect holding period calculations
• Solution: Automated date tracking and alerts

Integration with Tax Software​

Export to Popular Tax Tools​

Generate reports compatible with major tax software:

# Export to TurboTax format
def export_turbotax_format():
    return {
        'form_8949_short_term': query_short_term_gains(),
        'form_8949_long_term': query_long_term_gains(),
        'schedule_1_income': query_ordinary_income(),
        'deductible_expenses': query_deductible_expenses()
    }

Professional Tax Preparation​

Provide CPAs with comprehensive reports:

-- Complete tax package for CPA
SELECT 
  'Capital Gains Summary' as report_type,
  account,
  sum(position) as amount
WHERE account ~ "Income:CapitalGains" 
   OR account ~ "Expenses:CapitalLoss"
GROUP BY account

UNION ALL

SELECT 
  'Ordinary Income Summary' as report_type,
  account,
  sum(position) as amount
WHERE account ~ "Income:Crypto.*:Ordinary"
GROUP BY account;

Year-End Tax Planning​

December Tax Strategies​

Implement year-end tax optimization:

; December tax planning checklist
2024-12-01 * "Year-end tax planning review"
  unrealized-gains: "Calculate unrealized positions"
  loss-harvesting: "Identify loss harvesting opportunities"
  income-timing: "Consider deferring income to next year"
  expense-timing: "Accelerate deductible expenses"

Quarterly Estimated Taxes​

Track quarterly tax obligations:

2024-01-15 * "Q1 Estimated Tax Payment"
  Expenses:Taxes:Estimated:Federal     5000.00 USD
  Expenses:Taxes:Estimated:State       1200.00 USD
  Assets:Checking                     -6200.00 USD

Conclusion​

Cryptocurrency tax compliance doesn't have to be overwhelming. With Beancount.io's comprehensive plain-text accounting system, you can:

• Ensure Complete Compliance: Meet all IRS reporting requirements
• Optimize Tax Liability: Implement sophisticated tax strategies
• Maintain Audit-Ready Records: Comprehensive documentation and audit trails
• Automate Reporting: Generate tax forms and reports automatically
• Scale with Complexity: Handle simple trades to complex DeFi strategies

Key benefits for crypto tax compliance:

• Transparent Calculations: See exactly how tax numbers are computed
• Flexible Reporting: Generate any report format needed
• Professional Integration: Work seamlessly with CPAs and tax software
• Future-Proof Records: Plain-text format ensures long-term accessibility

Start implementing proper crypto tax compliance today. The investment in accurate record-keeping will save you time, money, and stress during tax season while ensuring you're fully compliant with IRS requirements.

Ready to master cryptocurrency tax compliance? Get started with Beancount.io and take control of your crypto tax obligations.

Decentralized Finance (DeFi) has revolutionized how we interact with financial services, offering unprecedented opportunities for yield generation, liquidity provision, and decentralized trading. However, with these opportunities comes the challenge of accurately tracking complex transactions for tax compliance and portfolio management.

Traditional accounting methods struggle with DeFi's unique characteristics: automated market makers, liquidity mining, impermanent loss, and multi-token rewards. This comprehensive guide shows you how to master DeFi accounting using Beancount.io's powerful plain-text accounting system.

Understanding DeFi Accounting Challenges​

The Complexity of DeFi Transactions​

DeFi protocols create accounting challenges that don't exist in traditional finance:

• Multi-token transactions: Single operations involving multiple cryptocurrencies
• Automated compounding: Rewards automatically reinvested
• Impermanent loss: Value changes due to price divergence in liquidity pools
• Gas fee optimization: Complex fee structures across different networks
• Protocol governance: Voting rights and governance token distributions
• Cross-protocol interactions: Transactions spanning multiple DeFi platforms

Tax Implications of DeFi Activities​

The IRS treats DeFi activities as taxable events:

• Liquidity provision: May trigger taxable events when depositing assets
• Yield farming rewards: Taxable as ordinary income at fair market value
• Impermanent loss: Potential tax implications when withdrawing from pools
• Governance tokens: Airdrops and rewards taxable as income
• Staking rewards: Taxable as income when received

Setting Up DeFi Accounts in Beancount.io​

Comprehensive Account Structure​

Create a detailed account hierarchy that captures all DeFi activities:

; Wallet Accounts
1970-01-01 open Assets:Crypto:Wallet:MetaMask:ETH
1970-01-01 open Assets:Crypto:Wallet:MetaMask:USDC
1970-01-01 open Assets:Crypto:Wallet:MetaMask:DAI
1970-01-01 open Assets:Crypto:Wallet:MetaMask:WBTC

; Uniswap V3 Liquidity Pools
1970-01-01 open Assets:DeFi:Uniswap:ETH-USDC-LP
1970-01-01 open Assets:DeFi:Uniswap:DAI-USDC-LP
1970-01-01 open Assets:DeFi:Uniswap:WBTC-ETH-LP

; Compound Protocol
1970-01-01 open Assets:DeFi:Compound:cUSDC
1970-01-01 open Assets:DeFi:Compound:cETH
1970-01-01 open Assets:DeFi:Compound:cDAI

; Aave Protocol
1970-01-01 open Assets:DeFi:Aave:aUSDC
1970-01-01 open Assets:DeFi:Aave:aETH
1970-01-01 open Assets:DeFi:Aave:DebtETH

; Staking Protocols
1970-01-01 open Assets:Staking:Ethereum:ETH
1970-01-01 open Assets:Staking:Lido:stETH
1970-01-01 open Assets:Staking:RocketPool:rETH

; Income Accounts
1970-01-01 open Income:DeFi:Yield:Uniswap
1970-01-01 open Income:DeFi:Yield:Compound
1970-01-01 open Income:DeFi:Yield:Aave
1970-01-01 open Income:DeFi:Staking:Ethereum
1970-01-01 open Income:DeFi:Governance:Tokens
1970-01-01 open Income:DeFi:Airdrops

; Expense Accounts
1970-01-01 open Expenses:DeFi:Gas:Ethereum
1970-01-01 open Expenses:DeFi:Gas:Polygon
1970-01-01 open Expenses:DeFi:Gas:Arbitrum
1970-01-01 open Expenses:DeFi:ImpermanentLoss

DeFi-Specific Commodities​

Define tokens and LP tokens with proper metadata:

1970-01-01 commodity UNI-V3-ETH-USDC
  name: "Uniswap V3 ETH-USDC LP Token"
  asset-class: "liquidity-pool"
  protocol: "uniswap-v3"

1970-01-01 commodity cUSDC
  name: "Compound USDC"
  asset-class: "lending-token"
  protocol: "compound"

1970-01-01 commodity stETH
  name: "Lido Staked Ethereum"
  asset-class: "staking-derivative"
  protocol: "lido"

Tracking Common DeFi Activities​

1. Uniswap Liquidity Provision​

Adding Liquidity to a Pool​

2024-01-15 * "Add liquidity to ETH-USDC Uniswap V3 pool"
  Assets:Crypto:Wallet:MetaMask:ETH     -5.0 ETH {2500.00 USD}
  Assets:Crypto:Wallet:MetaMask:USDC  -12500 USDC
  Assets:DeFi:Uniswap:ETH-USDC-LP        100 UNI-V3-ETH-USDC {250.00 USD}
  Expenses:DeFi:Gas:Ethereum            0.01 ETH {2500.00 USD}
  Assets:Crypto:Wallet:MetaMask:ETH    -0.01 ETH {2500.00 USD}

Claiming LP Fees​

2024-02-15 * "Claim Uniswap LP fees"
  Assets:Crypto:Wallet:MetaMask:ETH     0.2 ETH {2600.00 USD}
  Assets:Crypto:Wallet:MetaMask:USDC    300 USDC
  Income:DeFi:Yield:Uniswap            820.00 USD
  Expenses:DeFi:Gas:Ethereum           0.005 ETH {2600.00 USD}
  Assets:Crypto:Wallet:MetaMask:ETH   -0.005 ETH {2600.00 USD}

Removing Liquidity with Impermanent Loss​

2024-03-15 * "Remove liquidity from ETH-USDC pool"
  Assets:DeFi:Uniswap:ETH-USDC-LP       -100 UNI-V3-ETH-USDC {250.00 USD}
  Assets:Crypto:Wallet:MetaMask:ETH      4.8 ETH {2800.00 USD}
  Assets:Crypto:Wallet:MetaMask:USDC   12800 USDC
  Expenses:DeFi:ImpermanentLoss         240.00 USD  ; IL calculation
  Expenses:DeFi:Gas:Ethereum           0.008 ETH {2800.00 USD}
  Assets:Crypto:Wallet:MetaMask:ETH   -0.008 ETH {2800.00 USD}

2. Compound Protocol Lending​

Supplying Assets to Compound​

2024-01-20 * "Supply USDC to Compound"
  Assets:Crypto:Wallet:MetaMask:USDC  -10000 USDC
  Assets:DeFi:Compound:cUSDC            500 cUSDC {20.00 USD}
  Expenses:DeFi:Gas:Ethereum           0.008 ETH {2500.00 USD}
  Assets:Crypto:Wallet:MetaMask:ETH   -0.008 ETH {2500.00 USD}

Earning Compound Interest​

2024-02-20 * "Compound interest accrual"
  Assets:DeFi:Compound:cUSDC             5.2 cUSDC {20.50 USD}
  Income:DeFi:Yield:Compound           106.60 USD

Claiming COMP Rewards​

2024-02-20 * "Claim COMP governance tokens"
  Assets:Crypto:Wallet:MetaMask:COMP     12 COMP {85.00 USD}
  Income:DeFi:Governance:Tokens        1020.00 USD
  Expenses:DeFi:Gas:Ethereum           0.006 ETH {2600.00 USD}
  Assets:Crypto:Wallet:MetaMask:ETH   -0.006 ETH {2600.00 USD}

3. Aave Protocol Operations​

Depositing and Borrowing​

; Deposit ETH as collateral
2024-01-25 * "Deposit ETH to Aave"
  Assets:Crypto:Wallet:MetaMask:ETH    -10 ETH {2500.00 USD}
  Assets:DeFi:Aave:aETH                 10 aETH {2500.00 USD}
  Expenses:DeFi:Gas:Ethereum          0.01 ETH {2500.00 USD}
  Assets:Crypto:Wallet:MetaMask:ETH  -0.01 ETH {2500.00 USD}

; Borrow USDC against ETH collateral
2024-01-25 * "Borrow USDC from Aave"
  Assets:Crypto:Wallet:MetaMask:USDC  15000 USDC
  Liabilities:DeFi:Aave:DebtUSDC     -15000 USDC
  Expenses:DeFi:Gas:Ethereum          0.008 ETH {2500.00 USD}
  Assets:Crypto:Wallet:MetaMask:ETH  -0.008 ETH {2500.00 USD}

Repaying Loans with Interest​

2024-03-25 * "Repay USDC loan to Aave"
  Liabilities:DeFi:Aave:DebtUSDC      15000 USDC
  Expenses:DeFi:Interest:Aave           450 USDC  ; Interest accrued
  Assets:Crypto:Wallet:MetaMask:USDC -15450 USDC
  Expenses:DeFi:Gas:Ethereum          0.008 ETH {2700.00 USD}
  Assets:Crypto:Wallet:MetaMask:ETH  -0.008 ETH {2700.00 USD}

4. Ethereum Staking​

Direct Ethereum Staking​

2024-01-10 * "Stake ETH on Ethereum 2.0"
  Assets:Crypto:Wallet:MetaMask:ETH    -32 ETH {2500.00 USD}
  Assets:Staking:Ethereum:ETH           32 ETH {2500.00 USD}
  Expenses:DeFi:Gas:Ethereum          0.01 ETH {2500.00 USD}
  Assets:Crypto:Wallet:MetaMask:ETH  -0.01 ETH {2500.00 USD}

Staking Rewards​

2024-02-10 * "ETH staking rewards"
  Assets:Staking:Ethereum:ETH          0.15 ETH {2600.00 USD}
  Income:DeFi:Staking:Ethereum        390.00 USD

Liquid Staking with Lido​

2024-01-12 * "Stake ETH with Lido"
  Assets:Crypto:Wallet:MetaMask:ETH    -10 ETH {2500.00 USD}
  Assets:Staking:Lido:stETH             10 stETH {2500.00 USD}
  Expenses:DeFi:Gas:Ethereum          0.008 ETH {2500.00 USD}
  Assets:Crypto:Wallet:MetaMask:ETH  -0.008 ETH {2500.00 USD}

Advanced DeFi Scenarios​

Yield Farming Strategies​

Multi-Protocol Yield Farming​

; Step 1: Deposit USDC to Compound
2024-01-30 * "Deposit USDC to Compound for yield farming"
  Assets:Crypto:Wallet:MetaMask:USDC  -20000 USDC
  Assets:DeFi:Compound:cUSDC            1000 cUSDC {20.00 USD}

; Step 2: Borrow DAI against cUSDC
2024-01-30 * "Borrow DAI from Compound"
  Assets:Crypto:Wallet:MetaMask:DAI    15000 DAI
  Liabilities:DeFi:Compound:DebtDAI   -15000 DAI

; Step 3: Provide DAI-USDC liquidity to Uniswap
2024-01-30 * "Add DAI-USDC liquidity for farming"
  Assets:Crypto:Wallet:MetaMask:DAI   -15000 DAI
  Assets:Crypto:Wallet:MetaMask:USDC   -5000 USDC  ; Additional USDC
  Assets:DeFi:Uniswap:DAI-USDC-LP        200 UNI-V3-DAI-USDC {100.00 USD}

Cross-Chain DeFi Operations​

Bridging Assets​

2024-02-05 * "Bridge ETH to Polygon"
  Assets:Crypto:Wallet:MetaMask:ETH    -5 ETH {2600.00 USD}
  Assets:Crypto:Wallet:Polygon:ETH      5 ETH {2600.00 USD}
  Expenses:DeFi:Bridge:Fees           0.01 ETH {2600.00 USD}
  Assets:Crypto:Wallet:MetaMask:ETH  -0.01 ETH {2600.00 USD}

Flash Loans and Arbitrage​

2024-02-10 * "Flash loan arbitrage opportunity"
  ; Flash loan
  Assets:Crypto:Temp:FlashLoan       100000 USDC
  Liabilities:DeFi:Aave:FlashLoan   -100000 USDC
  
  ; Arbitrage trade
  Assets:Crypto:Temp:FlashLoan      -100000 USDC
  Assets:Crypto:Temp:Arbitrage       101500 USDC
  
  ; Repay flash loan
  Liabilities:DeFi:Aave:FlashLoan    100000 USDC
  Assets:Crypto:Temp:Arbitrage      -100090 USDC  ; Including fees
  
  ; Profit
  Assets:Crypto:Wallet:MetaMask:USDC   1410 USDC
  Income:DeFi:Arbitrage:Profit        1410.00 USD

DeFi Tax Reporting Considerations​

Income Recognition​

All DeFi rewards are taxable as ordinary income:

; Track all income sources separately
Income:DeFi:Yield:Uniswap           ; LP fees
Income:DeFi:Yield:Compound          ; Interest earned
Income:DeFi:Staking:Ethereum        ; Staking rewards
Income:DeFi:Governance:Tokens       ; Governance token airdrops
Income:DeFi:Airdrops               ; Protocol airdrops

Expense Deductions​

Track deductible expenses:

Expenses:DeFi:Gas:Ethereum          ; Gas fees
Expenses:DeFi:Gas:Polygon           ; Layer 2 fees
Expenses:DeFi:Interest:Aave         ; Borrowing costs
Expenses:DeFi:ImpermanentLoss       ; IL from LP positions

Capital Gains Tracking​

Use lot-based accounting for accurate capital gains:

; Different cost basis for same token
Assets:DeFi:Compound:cUSDC   100 cUSDC {20.00 USD}  ; Batch 1
Assets:DeFi:Compound:cUSDC   100 cUSDC {21.00 USD}  ; Batch 2

Best Practices for DeFi Accounting​

1. Real-Time Transaction Recording​

• Record transactions immediately after execution
• Use transaction hashes for verification
• Monitor mempool for pending transactions

2. Gas Fee Optimization Tracking​

; Track gas optimization strategies
Expenses:DeFi:Gas:Ethereum:Standard    ; Standard gas price
Expenses:DeFi:Gas:Ethereum:Fast        ; Fast gas price
Expenses:DeFi:Gas:Ethereum:Instant     ; Instant gas price

3. Protocol Risk Management​

; Track protocol-specific risks
Expenses:DeFi:Risk:SmartContract      ; Smart contract failures
Expenses:DeFi:Risk:Liquidation        ; Liquidation events
Expenses:DeFi:Risk:Slippage          ; Slippage costs

4. Automated Reconciliation​

• Set up automated price feeds
• Use protocol APIs for balance verification
• Implement automated transaction imports

5. Documentation Standards​

• Maintain detailed transaction notes
• Document strategy rationale
• Keep protocol interaction records

Integration with DeFi Tools​

Portfolio Tracking​

• DeBank: DeFi portfolio overview
• Zapper: Multi-protocol dashboard
• Zerion: DeFi wallet and tracker

Tax Reporting​

• Koinly: DeFi tax calculations
• CoinTracker: Multi-protocol support
• TokenTax: Specialized DeFi reporting

Analytics Platforms​

• DeFi Pulse: Protocol analytics
• DeFiLlama: TVL and yield tracking
• APY.vision: Impermanent loss tracking

Conclusion​

DeFi accounting complexity shouldn't prevent you from participating in the decentralized finance revolution. With Beancount.io's powerful plain-text accounting system, you can:

• Track Complex Transactions: Handle multi-protocol interactions seamlessly
• Ensure Tax Compliance: Proper income recognition and expense tracking
• Monitor Portfolio Performance: Real-time insights into DeFi positions
• Manage Risk: Track impermanent loss and protocol risks
• Scale Operations: From simple staking to complex yield farming strategies

The key to successful DeFi accounting is consistency, accuracy, and proper categorization. Start with basic protocols and gradually expand to more complex strategies as you become comfortable with the accounting patterns.

Ready to master DeFi accounting? Start your Beancount.io journey and take control of your decentralized finance portfolio today.

Beancount version 3, released in mid-2024, marks a significant architectural evolution for the popular plain-text accounting tool. While it maintains backward compatibility for user ledger files, the underlying structure and accompanying tools have undergone substantial changes. Here’s a breakdown of what’s new in Beancount v3.

A More Modular and Streamlined Architecture​

The most significant change in Beancount v3 is the move to a more modular ecosystem. Several key functionalities that were previously bundled with the core have been spun off into separate, independent projects. This makes the core of Beancount leaner and allows for more focused development on individual components.

The key components that are now separate packages include:

• beanquery: The powerful SQL-like query tool for your ledger files is now in its own package.
• beangulp: This is the new home for the data importing framework, replacing the former beancount.ingest module.
• beanprice: A dedicated tool for fetching prices of commodities and stocks.

This separation means that users will need to install these packages in addition to beancount itself to retain the full functionality they were used to in version 2.

Changes to Command-Line Tools and Workflows​

Reflecting the new modular architecture, there are some notable changes to the command-line tools:

• bean-report is gone: This tool has been removed. Users are now encouraged to use bean-query (from the beanquery package) for their reporting needs.
• New Importer Workflow: The bean-extract and bean-identify commands have been removed from the core. The new approach with beangulp is script-based. Users will now create their own Python scripts to handle the importing of data from external sources like bank statements.

Syntax and Feature Enhancements​

While the core accounting principles remain the same, Beancount v3 introduces some welcome flexibility to its syntax:

• More Flexible Currency Codes: The previous restrictions on the length and characters for currency names have been relaxed. Single-character currency symbols are now supported.
• Expanded Transaction Flags: Users can now use any capital letter from A to Z as a flag for transactions, allowing for more granular categorization.

Importantly, these changes are backward-compatible, so your existing Beancount v2 ledger files will work without any modifications.

The C++ Rewrite and Performance​

One of the long-term goals for Beancount has been a rewrite of its performance-critical components in C++. While this work is ongoing, the initial release of Beancount v3 does not include the C++-based core. This means that for now, the performance of v3 is comparable to v2. The C++ code remains in a separate development branch for future integration.

Migrating from v2 to v3​

For most users, the migration from Beancount v2 to v3 is relatively straightforward:

1. Ledger Files: No changes are needed for your .beancount files.
2. Installation: You will need to install the new, separate packages like beanquery and beangulp using pip.
3. Importer Scripts: If you have custom importers, you will need to update them to use the new beangulp API. This mainly involves changing the base class your importers inherit from and adjusting some method signatures.
4. Fava: The popular web interface for Beancount, Fava, has been updated to be compatible with v3. Ensure you have the latest version of Fava for a seamless experience.

In essence, Beancount v3 is a foundational release that streamlines the project's architecture, making it more modular and easier to maintain and extend in the long run. While it requires some adjustments to user workflows, especially around data importing, it sets the stage for the future development of this powerful accounting tool.