README
¶
bitwave-accounting-sdk
Plain-text double-entry accounting for Go, compatible with the
plain-text-accounting ecosystem (hledger, ledger, beancount).
It speaks the same journal grammar as those tools, so the books you keep with it can be read, audited, and reported on by every other tool in the ecosystem — and it can run against a cloud general ledger over HTTP when you want multi-user persistence.
go get github.com/bitwave-io/bitwave-accounting-sdk
Requires Go 1.25+. No external dependencies.
Stability: v0 — the API may change between minor versions until v1.0.0. Pin a tagged release.
Quick start
Parse a journal (hledger / ledger / beancount syntax all work) and run a balance report:
package main
import (
"log"
"os"
"github.com/bitwave-io/bitwave-accounting-sdk/format"
"github.com/bitwave-io/bitwave-accounting-sdk/report"
)
func main() {
p, err := format.ParseFile("main.journal")
if err != nil {
log.Fatal(err)
}
if err := report.Balance(os.Stdout, p, report.Filter{}); err != nil {
log.Fatal(err)
}
}
Packages
| Package | What it is |
|---|---|
model |
The double-entry domain: Entry, Posting, Amount, Account, Commodity, Price, Project, with balance-checking and base-currency valuation. |
store |
A Store interface with local-file and cloud (HTTP general-ledger) backends. |
report |
ledger-cli-style reports: balance, register, equity, stats, CSV. |
format |
hledger / ledger / beancount read + write interop (incl. a cross-tool compatibility suite under format/compat). |
config |
The per-project .bw-ledger.json local/cloud marker file. |
expense |
Expense-report views over journal entries: filtering, grouping, tag extraction, and CSV/JSON/HTML rendering. |
Why
- Plain text. Every transaction is a line in a journal file — diff it, blame it, branch it, commit it. No opaque blob, no API lock-in.
- Real double-entry. Every entry must balance before it is written.
- Cross-tool compatible. Output is consumable by
hledger,ledger, andbean-check; theformat/compatsuite proves it. - Local or cloud, same surface. The same
Storeinterface targets a directory of journal files or a cloud general ledger.
This SDK is the accounting foundation used by
bitwave-wallet-sdk, which
adds on-chain wallets and an on-chain → journal sync bridge on top.
License
Mozilla Public License 2.0. You can link this SDK into any software, open or closed; modifications to the SDK's own files must be shared under the MPL.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package config handles the per-project .bw-ledger.json file that records whether a directory is a local or cloud-backed ledger project.
|
Package config handles the per-project .bw-ledger.json file that records whether a directory is a local or cloud-backed ledger project. |
|
Package expense implements bwx expense-report tagging, filtering, and rendering.
|
Package expense implements bwx expense-report tagging, filtering, and rendering. |
|
Package format parses and prints the ledger-cli-compatible plain-text accounting format.
|
Package format parses and prints the ledger-cli-compatible plain-text accounting format. |
|
compat
Package compat is the cross-tool compatibility test harness for the plain-text ledger format.
|
Package compat is the cross-tool compatibility test harness for the plain-text ledger format. |
|
Package model defines the in-memory domain types for a plain-text ledger project.
|
Package model defines the in-memory domain types for a plain-text ledger project. |
|
Package report implements all ledger-cli style reports against an in-memory model.Project.
|
Package report implements all ledger-cli style reports against an in-memory model.Project. |
|
Package store abstracts persistence for ledger projects so the same CLI surface can target a local directory of .ledger files or the gl-svc cloud API.
|
Package store abstracts persistence for ledger projects so the same CLI surface can target a local directory of .ledger files or the gl-svc cloud API. |