Core Concepts

Beetles provides a purpose-built engine for financial accounting. This page explains the key concepts you need to understand.

Double-Entry Bookkeeping

Every transfer in Beetles has exactly two sides: a debit (source) and a credit (destination). The total debits always equal the total credits across the system — this is enforced at the engine level.

Transfer: $100
  Debit:  Account A  (balance decreases by $100)
  Credit: Account B  (balance increases by $100)

This means money can never be created or destroyed — only moved between accounts.

Ledgers

A Ledger is an isolated financial environment. Each ledger has its own set of accounts and transfers. Think of it as a separate chart of accounts.

Common use cases:

• One ledger per currency — USD Operations, EUR Treasury, BRL Payments
• One ledger per business unit — Payments, Payroll, Treasury
• One ledger per client — Multi-tenant marketplaces

Every ledger automatically includes a @world account — a special funding account with unlimited balance used to inject money into the system.

Accounts

An Account is a container for tracking balances. Each account has:

Account Codes

You can assign a numeric code to each account for categorization (e.g., 1001 for Revenue, 2001 for Expenses). This follows standard accounting conventions.

Transfers

A Transfer moves money between two accounts. Beetles supports three modes:

1. Direct Transfer

Money moves immediately. The simplest mode.

{
  "ledger_id": "...",
  "debit_account_id": "...",
  "credit_account_id": "...",
  "amount": 10000,
  "code": 1
}

2. Two-Phase Transfer (Auth & Capture)

Money is held (pending) and then either captured or voided:

{
  "ledger_id": "...",
  "debit_account_id": "...",
  "credit_account_id": "...",
  "amount": 10000,
  "code": 1,
  "pending": true,
  "timeout": 3600
}

Then resolve with:

• POST /transfers/{id}/confirm — capture the funds
• POST /transfers/{id}/void — release the hold

The timeout (in seconds) auto-voids the transfer if not resolved.

3. Settlement Transfer

For receivables — money is pending until a specific date:

{
  "amount": 10000,
  "settlement_date": "2025-03-15T12:00:00Z"
}

Beetles automatically posts the transfer on the settlement date using durable workflows.

Split & Batch

Beyond these three modes, a single POST /transfers endpoint also supports split transfers (one source to multiple destinations) and batch transfers (multiple entries with timestamps). See the Transfers guide for full details.

Exchanges

An Exchange moves money across two different ledgers — typically used for currency conversion. It creates two atomically linked transfers: one debiting the source account and one crediting the destination account.

POST /v1/exchanges
{
  "source_account_id": "brl_revenue_id",
  "destination_ledger_id": "usd_ledger_id",
  "amount": 542000,
  "exchange_rate": 5.42,
  "code": 1
}

The exchange:

1. Finds the Identity attached to the source account
2. Resolves (or auto-creates) a destination account for that Identity in the target ledger
3. Creates 2 linked transfers: source → @world (source ledger) + @world → destination (dest ledger)

Both transfers succeed or fail together — there is no partial state. See the Multi-Currency Exchange modeling guide for the full flow.

Identities

An Identity is a label that groups multiple accounts under the same entity within a ledger. It does not store personal data by default — Beetles has no concept of "people" or "companies" at the engine level.

You can optionally attach metadata (name, tax ID, etc.) if your application requires it, but it's entirely up to you.

{
  "ledger_id": "...",
  "metadata": {
    "label": "Acme Corp",
    "reference": "your-internal-id"
  }
}

Workspaces

A Workspace is a tenant boundary. All resources (ledgers, accounts, transfers) belong to a workspace. Each user can have multiple workspaces, and workspaces can have multiple members.

Every API request to workspace-scoped resources must include the Beetles-Workspace-Id header.

IDs

All resource IDs use UUIDv7 — they are time-ordered and sortable. Internal numeric IDs are derived from the UUID bytes and never exposed externally.