devaccuracy/ledgerforge

The ledger for AI-native money movement

The system of record for fintech wallets, payouts, marketplaces and billing — with spending limits that keep AI agents in check and an audit trail you can prove.

Website · Docs · Cloud · Changelog · Roadmap

Open-source core (Apache 2.0) · Managed with LedgerForge Cloud · Enterprise

LedgerForge is an open-source double-entry ledger. It records wallet transfers, payouts, billing activity, reservations and refunds in exact integer units, backs that history with a verifiable audit chain, and enforces spending policies on every API key, including the keys your AI agents use. Use it through an HTTP API, a Go library or a local MCP server.

PostgreSQL stores the financial records and Redis runs queues and background workers; search and observability services are optional. LedgerForge records money movement. Connecting payment rails and defining your accounting model remain application responsibilities.

Use cases

• Wallets and stored value: a balance per customer or account, inflight

holds that reduce spendable funds, bounded overdrafts and linked refunds.

• Payouts and disbursements: reserve funds while a payout is in flight,

commit or void the reservation when the rail reports back, and reconcile against external records.

• Marketplaces: split one payment across seller, fee and platform balances

with deterministic allocation, so the legs always sum to the total.

• Usage-based billing: record metered charges in exact units, queue or

schedule them, and retry safely with idempotent references.

• AI agents moving money: give each agent its own API key with currency

limits, allowlists, daily budgets and approval holds that the server enforces, and connect agents through the MCP server.

Why LedgerForge

• Exact money: integer postings, explicit precision and deterministic

splits; see the accounting guarantees.

• A verifiable ledger: read-only ledgerforge verify replays accounting

evidence. Versioned audit chains and exportable checkpoints support audit verify --anchor against independently retained roots. See the verification guide for coverage and legacy limits.

• Agent guardrails: per-key currency and precision limits, balance and

ledger allowlists, durable daily reservations and approval holds, enforced by the server rather than the client. Delegated keys inherit restrictions and share ancestor budgets. Bind MCP to an API key and keep independent approver credentials outside the agent's authority. See agent safety and the executable policy example.

• A hardened API: owner-bound key management, constrained delegation,

authoritative revocation checks, bounded input and sanitized backend errors. Dedicated webhook signing secrets and destination controls protect outbound integrations. See security operations.

• Tested invariants: exact-amount and allocation fuzz targets, generated

PostgreSQL operation sequences, balance conservation checks and race tests for financial lifecycle and spending-capacity transitions.

• Operational workflows: inflight reservations, partial settlement,

refunds, split and bulk transfers, reconciliation, lineage, snapshots and optional search, metrics and OpenTelemetry.

• Traceable releases: binaries for Linux, macOS and Windows, multi-platform

images, checksums, SPDX SBOMs and image attestations, published only after the test, vulnerability and fuzz gates pass.

Accounting guarantees

• Exact amounts: postings and balance arithmetic use integer units. Supply

precise_amount with an explicit precision to avoid floating-point input loss; 1250 at precision 100 represents 12.50.

• Double entry: each applied transfer debits its source and credits its

destination by the same amount. Split transfers distribute that amount across their legs.

• Immutable postings: corrections and refunds create linked transactions.

Financial postings and accepted execution controls are preserved; customer metadata can be updated.

• Idempotency by reference: reuse the same unique transaction reference

after a timeout. Duplicate references are rejected; look up the original outcome instead of retrying with a new reference.

See ledger concepts for amount handling, balance semantics and asynchronous transaction states.

Quickstart: a balanced transfer

Requires Docker with Compose and Python 3:

git clone https://github.com/devaccuracy/ledgerforge.git
cd ledgerforge
./examples/quickstart/start.sh
./examples/quickstart/transfer.sh

This local-only demo builds the current checkout, generates a random master key, runs migrations and binds the API to 127.0.0.1:5001. It creates two USD balances and posts 12.50 synchronously using integer units. The source gets a bounded demo overdraft of 12.50; the result is -1250 and 1250 units, with equal total debits and credits. A retry with the same reference must leave those balances unchanged.

source: -1250 units
destination: 1250 units
total debits = total credits = 1250 units
reference retry: balances unchanged

Stop it with docker compose -p ledgerforge-demo -f examples/quickstart/compose.yaml down. The example guide covers the API payload, credentials and cleanup. These credentials and database defaults are for local use only; read the deployment guide before exposing a service.

Install

• Release binaries: download ledgerforge and ledgerforge-mcp for Linux,

macOS or Windows from GitHub Releases, then check the archive against checksums.txt (sha256sum -c checksums.txt --ignore-missing).

• Container image: docker pull ghcr.io/devaccuracy/ledgerforge:1.0.0. The

image contains both binaries; the release lists its digest and SBOMs.

• From source: go install github.com/devaccuracy/ledgerforge/cmd/ledgerforge@v1.0.0

(Go 1.26.9 or later).

Run ledgerforge version to confirm what you installed, then follow the deployment guide and run ledgerforge migrate up before starting the server. Before upgrading an existing database, read the integrity upgrade notes.

Run the published image locally

cp ledgerforge.example.json ledgerforge.json
Replace server.secret_key with a random secret before starting.
For example, generate one with: openssl rand -hex 32
docker compose up -d

The config explicitly enables authentication. API requests use the X-LedgerForge-Key header. Keep ledgerforge.json private and out of version control. The :main image tracks tested main-branch commits; pin a release tag or digest in production with LEDGERFORGE_IMAGE.

Open source and LedgerForge Cloud

Everything in this repository is free and open source under Apache 2.0: the ledger, verification and audit tooling, agent spending policies and approvals, the MCP server and the release artifacts. There are no license keys or feature gates, and you can run it in production yourself.

LedgerForge Cloud is a service, not different software: it operates the same open-source core for you.

| | Open source | LedgerForge Cloud | Enterprise | | --- | --- | --- | --- | | What it is | The software in this repository | Managed LedgerForge deployments, operated per customer | Contracted deployment, support and review services | | Ledger, verification, agent policies, MCP server | Included | Same open-source core | Same open-source core | | Who operates it | You | The LedgerForge team (dedicated infrastructure per customer) | You or the LedgerForge team, per contract, including in-VPC deployments | | Upgrades, backups and monitoring | You | Operated for you | Agreed per contract, with migration and integration assistance | | Verification and audit checkpoints | You run ledgerforge verify and audit export | Scheduled ledgerforge verify runs with audit checkpoints exported and anchored for each deployment | Architecture and audit reviews | | Support | Community, through GitHub | Onboarding and support | SLA and support plan agreed per contract; priority security response | | Hosted multi-tenant service with a dashboard | — | Planned (roadmap) | — | | Price | Free | Request access | Contact sales | | Get started | Quickstart | Request access | Contact sales |

Documentation

The documentation index lists every guide. Start with:

• Concepts: amounts, balances and transaction states
• Deployment: secrets, TLS, limits and webhook verification
• Verification: accounting replay and external audit anchoring
• Agent safety: spending policies and independent approval
• Security operations: API keys, delegation and rotation
• MCP server: connect AI agents to the ledger
• Architecture: package layout and trust boundaries

Online documentation is at ledgerforge.io/docs. The roadmap describes what is planned and the changelog records what has shipped.

Development

make verify
make test-integration
make vuln
make cover

CONTRIBUTING.md covers prerequisites, isolated integration tests and pull request expectations.

Community, support and license

• Bugs and proposals: use the

issue forms.

• Questions: start with the documentation, then open a

question if it does not help. SUPPORT.md covers community and commercial support.

• Contributing: read CONTRIBUTING.md and follow the

Code of Conduct. GOVERNANCE.md explains how decisions are made.

• Security: report vulnerabilities privately to

security@ledgerforge.io; see the security policy.

Licensed under Apache 2.0. Required notices are in NOTICE.md.