pycustodian

The book of record for trading and wealth platforms.

pycustodian is the single, durable source of truth for positions, cost basis, cash, and P&L. It ingests fills, records them in an event-sourced double-entry journal, and serves positions, exposure, current weights, and NAV to the rest of a platform (risk, optimization, dashboards).

It is a service built around a pure, extractable domain core (hexagonal architecture): the accounting logic in pycustodian.domain is I/O-free and deterministic; persistence (SQL event store), transport (FastAPI), and live ingestion (Kafka) are adapters around it.

Why it exists

Decisioning, risk, and execution can all be stateless or transient. The book of record cannot: it must be the one authoritative, always-consistent copy of the truth, with transactional integrity and exactly-once fill ingestion. That makes it a service — but its accounting math stays a clean, testable library at the core.

Design rules

1. The domain core is pure. pycustodian.domain imports no infrastructure (enforced by an import-linter contract). It can be extracted into a standalone package the day a second consumer (e.g. a backtester) needs the math.
2. The journal is append-only. Positions, cash, P&L, and NAV are projections folded from the immutable transaction log. Corrections are reversing entries, never mutations — giving a full audit trail and point-in-time replay.
3. Money is Decimal, never float.

Status

Early foundation. The pure domain core (double-entry journal, FIFO/LIFO/HIFO/ AVERAGE cost basis, projections, valuation, performance) and its test suite are in place. Persistence, application use cases, the API, Kafka ingest, and family integrations follow.

Install

pip install pycustodian                 # core (pure domain + config + CLI)
pip install "pycustodian[db,api,kafka]" # + durable store, HTTP service, live ingest

License

MIT