API + engineering reference
For engineers building against, extending, or operating the Valura Ledger.
If you want the "what" and "why" instead of the "how", read the Documentation.
What's here
| Section | For |
|---|---|
| Getting started | Local install, run, hit an endpoint |
| Engine | Double-entry core, posting rules, recost, reconciliation |
| Data model | CoAs + posting worked examples for both books |
| Endpoints | Every API endpoint with request/response shapes |
| Operations | Config, migrations, testing, troubleshooting, deployment |
| FAQ | Common technical Q&A |
Ground rules
- The ledger is the source of truth. Every ingested event becomes ONE
Transactionand TWO+ balancedJournalLines. Trial balance = 0 always. - The ledger never writes to a broker. Every external call is a GET (except auth-chain POSTs for token exchange). Broker writes belong somewhere else.
- One codebase, two books. Same FastAPI app, same schema, same migrations — different DB per legal entity. UAE code stays byte-identical on every India change.
- Idempotency everywhere.
(source, source_txn_id)is the unique key on every ingested transaction. Duplicate delivery is a no-op. - Pure functions where possible. Posting rules, matchers, aggregators are pure over shaped inputs. Testable without a DB.