Skip to content
Back to search

ledgerforge

The ledger for AI-native money movement. An open-source double-entry ledger for wallets, payouts, marketplaces and billing, with exact integer money, a verifiable audit chain, server-enforced spending limits and approvals for AI agents, and an MCP server. Apache 2.0.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/devaccuracy--ledgerforge/badge.svg)](/listings/devaccuracy--ledgerforge)

HTML

<a href="/listings/devaccuracy--ledgerforge"><img src="/api/listings/devaccuracy--ledgerforge/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](examples/quickstart/README.md) covers the API payload, credentials and cleanup. These credentials and database defaults are for local use only; read the [deployment guide](docs/deployment.md) before exposing a service.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 238 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <a href="https://ledgerforge.io">
  3. <picture>
  4. <source media="(prefers-color-scheme: dark)" srcset="docs/assets/wordmark-dark.png">
  5. <img src="docs/assets/wordmark-light.png" alt="LedgerForge" width="300">
  6. </picture>
  7. </a>
  8. </p>
  9. <h1 align="center">The ledger for AI-native money movement</h1>
  10. <p align="center">
  11. The system of record for fintech wallets, payouts, marketplaces and billing —
  12. with spending limits that keep AI agents in check and an audit trail you can prove.
  13. </p>
  14. <p align="center">
  15. <a href="https://github.com/devaccuracy/ledgerforge/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/devaccuracy/ledgerforge?sort=semver"></a>
  16. <a href="https://github.com/devaccuracy/ledgerforge/actions/workflows/go.yml"><img alt="Build and Test" src="https://github.com/devaccuracy/ledgerforge/actions/workflows/go.yml/badge.svg?branch=main"></a>
  17. <a href="LICENSE.md"><img alt="License: Apache 2.0" src="https://img.shields.io/github/license/devaccuracy/ledgerforge"></a>
  18. <a href="go.mod"><img alt="Go 1.26.9 or later" src="https://img.shields.io/badge/Go-1.26.9%2B-00ADD8?logo=go&amp;logoColor=white"></a>
  19. <a href="https://pkg.go.dev/github.com/devaccuracy/ledgerforge"><img alt="Go Reference" src="https://pkg.go.dev/badge/github.com/devaccuracy/ledgerforge.svg"></a>
  20. </p>
  21. <p align="center">
  22. <a href="https://ledgerforge.io"><strong>Website</strong></a> ·
  23. <a href="https://ledgerforge.io/docs"><strong>Docs</strong></a> ·
  24. <a href="https://ledgerforge.io/cloud"><strong>Cloud</strong></a> ·
  25. <a href="CHANGELOG.md"><strong>Changelog</strong></a> ·
  26. <a href="ROADMAP.md"><strong>Roadmap</strong></a>
  27. </p>
  28. <p align="center">
  29. <a href="#open-source-and-ledgerforge-cloud">Open-source core (Apache 2.0)</a> ·
  30. Managed with <a href="https://ledgerforge.io/cloud">LedgerForge Cloud</a> ·
  31. <a href="https://ledgerforge.io/contact/us?interest=enterprise">Enterprise</a>
  32. </p>
  33. LedgerForge is an open-source double-entry ledger. It records wallet transfers,
  34. payouts, billing activity, reservations and refunds in exact integer units,
  35. backs that history with a verifiable audit chain, and enforces spending
  36. policies on every API key, including the keys your AI agents use. Use it
  37. through an HTTP API, a Go library or a local MCP server.
  38. PostgreSQL stores the financial records and Redis runs queues and background
  39. workers; search and observability services are optional. LedgerForge records
  40. money movement. Connecting payment rails and defining your accounting model
  41. remain application responsibilities.
  42. ## Use cases
  43. - **Wallets and stored value:** a balance per customer or account, inflight
  44. holds that reduce spendable funds, bounded overdrafts and linked refunds.
  45. - **Payouts and disbursements:** reserve funds while a payout is in flight,
  46. commit or void the reservation when the rail reports back, and reconcile
  47. against external records.
  48. - **Marketplaces:** split one payment across seller, fee and platform balances
  49. with deterministic allocation, so the legs always sum to the total.
  50. - **Usage-based billing:** record metered charges in exact units, queue or
  51. schedule them, and retry safely with idempotent references.
  52. - **AI agents moving money:** give each agent its own API key with currency
  53. limits, allowlists, daily budgets and approval holds that the server
  54. enforces, and connect agents through the [MCP server](docs/mcp.md).
  55. ## Why LedgerForge
  56. - **Exact money:** integer postings, explicit precision and deterministic
  57. splits; see the [accounting guarantees](#accounting-guarantees).
  58. - **A verifiable ledger:** read-only `ledgerforge verify` replays accounting
  59. evidence. Versioned audit chains and exportable checkpoints support
  60. `audit verify --anchor` against independently retained roots. See the
  61. [verification guide](docs/verification.md) for coverage and legacy limits.
  62. - **Agent guardrails:** per-key currency and precision limits, balance and
  63. ledger allowlists, durable daily reservations and approval holds, enforced by
  64. the server rather than the client. Delegated keys inherit restrictions and
  65. share ancestor budgets. Bind MCP to an API key and keep independent approver
  66. credentials outside the agent's authority. See
  67. [agent safety](docs/agent-safety.md) and the
  68. [executable policy example](examples/agent-policy/README.md).
  69. - **A hardened API:** owner-bound key management, constrained delegation,
  70. authoritative revocation checks, bounded input and sanitized backend errors.
  71. Dedicated webhook signing secrets and destination controls protect outbound
  72. integrations. See [security operations](docs/security.md).
  73. - **Tested invariants:** exact-amount and allocation fuzz targets, generated
  74. PostgreSQL operation sequences, balance conservation checks and race tests
  75. for financial lifecycle and spending-capacity transitions.
  76. - **Operational workflows:** inflight reservations, partial settlement,
  77. refunds, split and bulk transfers, reconciliation, lineage, snapshots and
  78. optional search, metrics and OpenTelemetry.
  79. - **Traceable releases:** binaries for Linux, macOS and Windows, multi-platform
  80. images, checksums, SPDX SBOMs and image attestations, published only after
  81. the test, vulnerability and fuzz gates pass.
  82. ## Accounting guarantees
  83. - **Exact amounts:** postings and balance arithmetic use integer units. Supply
  84. `precise_amount` with an explicit `precision` to avoid floating-point input
  85. loss; `1250` at precision `100` represents `12.50`.
  86. - **Double entry:** each applied transfer debits its source and credits its
  87. destination by the same amount. Split transfers distribute that amount
  88. across their legs.
  89. - **Immutable postings:** corrections and refunds create linked transactions.
  90. Financial postings and accepted execution controls are preserved; customer
  91. metadata can be updated.
  92. - **Idempotency by reference:** reuse the same unique transaction `reference`
  93. after a timeout. Duplicate references are rejected; look up the original
  94. outcome instead of retrying with a new reference.
  95. See [ledger concepts](docs/concepts.md) for amount handling, balance semantics
  96. and asynchronous transaction states.
  97. ## Quickstart: a balanced transfer
  98. Requires Docker with Compose and Python 3:
  99. ```sh
  100. git clone https://github.com/devaccuracy/ledgerforge.git
  101. cd ledgerforge
  102. ./examples/quickstart/start.sh
  103. ./examples/quickstart/transfer.sh
  104. ```
  105. This **local-only demo** builds the current checkout, generates a random master
  106. key, runs migrations and binds the API to `127.0.0.1:5001`. It creates two USD
  107. balances and posts `12.50` synchronously using integer units. The source gets a
  108. bounded demo overdraft of `12.50`; the result is `-1250` and `1250` units, with
  109. equal total debits and credits. A retry with the same reference must leave
  110. those balances unchanged.
  111. ```text
  112. source: -1250 units
  113. destination: 1250 units
  114. total debits = total credits = 1250 units
  115. reference retry: balances unchanged
  116. ```
  117. Stop it with `docker compose -p ledgerforge-demo -f examples/quickstart/compose.yaml down`.
  118. The [example guide](examples/quickstart/README.md) covers the API payload,
  119. credentials and cleanup. These credentials and database defaults are for local
  120. use only; read the [deployment guide](docs/deployment.md) before exposing a
  121. service.
  122. ## Install
  123. - **Release binaries:** download `ledgerforge` and `ledgerforge-mcp` for Linux,
  124. macOS or Windows from [GitHub Releases](https://github.com/devaccuracy/ledgerforge/releases),
  125. then check the archive against `checksums.txt` (`sha256sum -c checksums.txt --ignore-missing`).
  126. - **Container image:** `docker pull ghcr.io/devaccuracy/ledgerforge:1.0.0`. The
  127. image contains both binaries; the release lists its digest and SBOMs.
  128. - **From source:** `go install github.com/devaccuracy/ledgerforge/cmd/ledgerforge@v1.0.0`
  129. (Go 1.26.9 or later).
  130. Run `ledgerforge version` to confirm what you installed, then follow the
  131. [deployment guide](docs/deployment.md) and run `ledgerforge migrate up` before
  132. starting the server. Before upgrading an existing database, read the
  133. [integrity upgrade notes](docs/upgrade-notes.md).
  134. ### Run the published image locally
  135. ```sh
  136. cp ledgerforge.example.json ledgerforge.json
  137. # Replace server.secret_key with a random secret before starting.
  138. # For example, generate one with: openssl rand -hex 32
  139. docker compose up -d
  140. ```
  141. The config explicitly enables authentication. API requests use the
  142. `X-LedgerForge-Key` header. Keep `ledgerforge.json` private and out of version
  143. control. The `:main` image tracks tested main-branch commits; pin a release tag
  144. or digest in production with `LEDGERFORGE_IMAGE`.
  145. ## Open source and LedgerForge Cloud
  146. Everything in this repository is free and open source under
  147. [Apache 2.0](LICENSE.md): the ledger, verification and audit tooling, agent
  148. spending policies and approvals, the MCP server and the release artifacts.
  149. There are no license keys or feature gates, and you can run it in production
  150. yourself.
  151. LedgerForge Cloud is a service, not different software: it operates the same
  152. open-source core for you.
  153. | | Open source | LedgerForge Cloud | Enterprise |
  154. | --- | --- | --- | --- |
  155. | What it is | The software in this repository | Managed LedgerForge deployments, operated per customer | Contracted deployment, support and review services |
  156. | Ledger, verification, agent policies, MCP server | Included | Same open-source core | Same open-source core |
  157. | Who operates it | You | The LedgerForge team (dedicated infrastructure per customer) | You or the LedgerForge team, per contract, including in-VPC deployments |
  158. | Upgrades, backups and monitoring | You | Operated for you | Agreed per contract, with migration and integration assistance |
  159. | 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 |
  160. | Support | Community, through GitHub | Onboarding and support | SLA and support plan agreed per contract; priority security response |
  161. | Hosted multi-tenant service with a dashboard | — | Planned ([roadmap](ROADMAP.md)) | — |
  162. | Price | Free | Request access | Contact sales |
  163. | Get started | [Quickstart](#quickstart-a-balanced-transfer) | [Request access](https://ledgerforge.io/cloud) | [Contact sales](https://ledgerforge.io/contact/us?interest=enterprise) |
  164. ## Documentation
  165. The [documentation index](docs/README.md) lists every guide. Start with:
  166. - [Concepts](docs/concepts.md): amounts, balances and transaction states
  167. - [Deployment](docs/deployment.md): secrets, TLS, limits and webhook verification
  168. - [Verification](docs/verification.md): accounting replay and external audit anchoring
  169. - [Agent safety](docs/agent-safety.md): spending policies and independent approval
  170. - [Security operations](docs/security.md): API keys, delegation and rotation
  171. - [MCP server](docs/mcp.md): connect AI agents to the ledger
  172. - [Architecture](ARCHITECTURE.md): package layout and trust boundaries
  173. Online documentation is at [ledgerforge.io/docs](https://ledgerforge.io/docs).
  174. The [roadmap](ROADMAP.md) describes what is planned and the
  175. [changelog](CHANGELOG.md) records what has shipped.
  176. ## Development
  177. ```sh
  178. make verify
  179. make test-integration
  180. make vuln
  181. make cover
  182. ```
  183. [CONTRIBUTING.md](CONTRIBUTING.md) covers prerequisites, isolated integration
  184. tests and pull request expectations.
  185. ## Community, support and license
  186. - **Bugs and proposals:** use the
  187. [issue forms](https://github.com/devaccuracy/ledgerforge/issues/new/choose).
  188. - **Questions:** start with the [documentation](docs/README.md), then open a
  189. [question](https://github.com/devaccuracy/ledgerforge/issues/new?template=question.yml)
  190. if it does not help. [SUPPORT.md](SUPPORT.md) covers community and
  191. commercial support.
  192. - **Contributing:** read [CONTRIBUTING.md](CONTRIBUTING.md) and follow the
  193. [Code of Conduct](CODE_OF_CONDUCT.md). [GOVERNANCE.md](GOVERNANCE.md) explains
  194. how decisions are made.
  195. - **Security:** report vulnerabilities privately to
  196. [security@ledgerforge.io](mailto:security@ledgerforge.io); see the
  197. [security policy](SECURITY.md).
  198. Licensed under [Apache 2.0](LICENSE.md). Required notices are in [NOTICE.md](NOTICE.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.