Ledger API Documentation

Looking for the Ledger Proto Definitions?

Ledger API Overview

The Ledger API helps you record immutable, double-entry transactions in a consistent, auditable way. It draws from centuries-old accounting practices to build a modern foundation for FinTech systems.

Double-Entry Bookkeeping

Double-entry bookkeeping ensures financial accuracy by requiring every transaction to affect two or more accounts. For every debit, a corresponding credit must exist.

Accounting Formula

Assets = Liabilities + Equity

This equation keeps your ledger balanced and traceable. It’s the foundation for automated validation.

Mental Model

Debits increase what you own or spend (e.g., cash, expenses).
Credits increase what you owe or earn (e.g., liabilities, revenue).

Assets and expenses typically have debit balances. Liabilities, equity, and revenue typically have credit balances.

Account Type	Debit Effect	Credit Effect
Asset	Increase	Decrease
Liability	Decrease	Increase
Equity	Decrease	Increase
Revenue	—	Increase
Expense	Increase	—

Example: When cash is received, Cash (Asset) increases — a debit — and Revenue increases — a credit. Both grow, but affect opposite sides of the equation.

Use Case: Prepaid Charge Card

A prepaid virtual card system might include the following ledger events:

Fund via ACH — debit: Bank, credit: User Account
Authorize a charge — debit: Merchant Settlement, credit: User Account
Capture the charge — no-op if already fully matched

Each step results in a journal entry that mirrors real-world movement of funds.

Ledger flow: funding, authorization, and settlement of a virtual card.

Authentication & gRPC Access

All requests require an API key passed in the metadata using x-api-key.

Proto Reference & Downloads

All Ledger services are defined using Protocol Buffers and accessed via gRPC. Download the proto files or browse service definitions in the Ledger API Proto Reference.

Includes ZIP download, service documentation, and schema explorer.

How to Call gRPC

Any gRPC-compatible client can be used as long as requests include a valid API key and conform to the service contracts.

Ledgers

A ledger is the primary container for all financial activity. It groups accounts and journal entries to form a complete, consistent view of your organization’s financial operations.

Each ledger is defined by a name and a base currency and enforces double-entry accounting within its scope.

Ledger Lifecycle

Create: Initialize with a name and currency.
Configure: Define its chart of accounts.
Operate: Post immutable journal entries.

You can create multiple ledgers to separate business units, currencies, or organizations.

Proto: ledger.proto

RPC: CreateLedger

Chart of Accounts

Every ledger defines a Chart of Accounts—a hierarchical tree that categorizes all balances and transactions.

Postable accounts: Leaf nodes that hold balances.
Group accounts: Organizational nodes that group postables.

Example Chart

Start with postables. Use groups to organize accounts for reporting or nesting.

├── Assets

│ ├── Bank

│ └── User Balance

├── Liabilities

│ └── Merchant Settlement

└── Equity

└── Retained Earnings

Define accounts using CreateAccount before posting journal entries.

Proto: account.proto

RPC: CreateAccount

Journal Entries

Journal entries record financial events by debiting and crediting one or more postable accounts. The system ensures each entry is balanced.

Entries are immutable. To change an entry, create a reversing entry. Each entry is cryptographically signed to preserve a tamper-proof audit trail.

Proto: journal.proto

RPC: CreateJournalEntry

Operational Guarantees

The Ledger API is designed for safe, consistent, and predictable operations in production environments. This section outlines how the system handles retries, concurrency, and throughput.

All write operations are atomic and strongly consistent. The API supports idempotent requests using metadata headers and applies rate limiting to ensure fair usage and protect system stability.

Idempotency

Use the x-idempotency-key metadata header to safely retry write operations likeCreateJournalEntry andReverseJournalEntry.
The value must be a unique, deterministic identifier such as a UUID.
If a request with the same key has already succeeded, the cached response will be returned immediately without executing the logic again.
To bypass caching (e.g. during testing), add the headerx-no-cache: true.
Only successful responses (Status.OK) are cached. Errors are not stored or replayed.

Concurrency

Journal entries are validated and applied transactionally. If the resulting state is unbalanced or invalid, the entire operation is rolled back.
Concurrent writes to the same account are serialized internally to ensure correctness of balances.
Operations targeting independent accounts or ledgers are processed concurrently.
The system guarantees strong consistency—all reads reflect the latest committed state.

Rate Limits

Default limit: 10 requests per second per organization.
Bursts up to 100 RPS are allowed with token bucket smoothing.
If a client exceeds the limit, the request is rejected withRESOURCE_EXHAUSTED.
Contact support to request a custom quota for high-throughput systems.

Advanced Topics

Multitenancy & Orgs

Org-Aware Access

Every ledger belongs to an organisation_id. Users may be assigned to multiple orgs. Access is enforced through the authentication context.