Trancent Docs

Journal Entries

Journal entries are the atomic unit of the ledger. Every entry contains two or more lines whose functionalAmount values must sum to zero — one debit for every credit.

All amounts are integers in the smallest currency unit (e.g. cents for USD). Floating-point values are never accepted.

Base URL: https://api.trancent.dev — all paths below are relative to this.

Record a journal entry

POST /v1/ledgers/:ledgerId/journal-entries

Request body

{
  "externalId": "charge_abc123",
  "originSystem": "billing",
  "originAccount": "cust_42",
  "eventType": "token-grant",
  "transactionDate": "2026-03-05T00:00:00Z",
  "entryType": "STANDARD",
  "postingStatus": "POSTED",
  "metadata": {},
  "lines": [
    {
      "glAccountCode": "assets.token-pool",
      "transactionAmount": "10000",
      "transactionCurrency": "USD",
      "functionalAmount": "10000",
      "functionalCurrency": "USD",
      "spotRate": 1.0
    },
    {
      "glAccountCode": "revenue.token-sales",
      "transactionAmount": "-10000",
      "transactionCurrency": "USD",
      "functionalAmount": "-10000",
      "functionalCurrency": "USD",
      "spotRate": 1.0
    }
  ]
}

Key fields

FieldTypeDescription
externalIdstringCaller-supplied idempotency key. Duplicate IDs return 409.
lines[].glAccountCodestringGeneral-ledger account code from the chart of accounts.
lines[].transactionAmountstring (bigint)Amount in original currency, integer cents.
lines[].functionalAmountstring (bigint)Amount in the ledger’s base (functional) currency. All lines must sum to zero.
lines[].spotRatenumberExchange rate applied when transactionCurrency ≠ functionalCurrency.

Response — 201 Created

{
  "journalId": "01HXR...",
  "persistedAt": "2026-03-05T12:34:56.789Z"
}

Validation rules

  • Sum-zero: The sum of all functionalAmount values must equal zero. Violations return 400.
  • No zero amounts: Every line must have a non-zero functionalAmount.
  • Idempotency: If externalId has already been used in this ledger, the request is rejected with 409.

List journal entries

GET /v1/ledgers/:ledgerId/journal-entries
ParameterTypeDefaultDescription
limitinteger50Page size (max 100)
offsetinteger0Pagination offset

Response — 200 OK

{
  "entries": [ … ],
  "total": 142,
  "hasMore": true
}

Get a single entry

GET /v1/ledgers/:ledgerId/journal-entries/:entryId

Returns the full journal entry including all lines.

Reverse an entry

POST /v1/ledgers/:ledgerId/journal-entries/:entryId/reversal

Creates a new journal entry that mirrors the original with inverted amounts. The original entry is not modified — reversals are append-only and become part of the permanent audit trail.

Constraints:

  • A REVERSAL entry cannot itself be reversed.
  • Entries in a closed period cannot be reversed.

Response — 201 Created

{
  "journalId": "01HXS...",
  "persistedAt": "2026-03-05T12:45:00.000Z"
}

Error responses

StatusCodeMeaning
400VALIDATION_ERRORBad input, sum-zero violation, or zero-amount line
401—Invalid API key or signature
404—Ledger not found or not owned by caller’s org
409DUPLICATE_ENTRYexternalId already used in this ledger

All errors follow the RFC 9457 problem detail format.