# Ledger

The ledger is the complete, ordered history of all financial movements on an account. Every debit and credit operation generates a ledger line.

## What is the Ledger?

Think of the ledger as your account statement. Each line records:

* What operation occurred (debit or credit)
* Which transaction and journal entry it belongs to
* The amount moved
* The account balance after the operation
* The account version at that point

## Ledger Line Fields

| Field                    | Type      | Description                                              |
| ------------------------ | --------- | -------------------------------------------------------- |
| `id`                     | UUID      | Unique identifier for this ledger line                   |
| `account_id`             | UUID      | The account this line belongs to                         |
| `account_category`       | String    | Category of the account at the time of the journal entry |
| `operation`              | String    | `DEBIT` or `CREDIT`                                      |
| `transaction_id`         | UUID      | The transaction that generated this line                 |
| `journal_entry_id`       | UUID      | The specific journal entry that generated this line      |
| `journal_entry_type`     | String    | The type label from the journal entry (e.g., `PIX_OUT`)  |
| `journal_entry_sequence` | Integer   | The journal entry's sequence within its transaction      |
| `asset`                  | String    | Currency code                                            |
| `amount`                 | Integer   | Amount of the operation                                  |
| `account_post_balance`   | Integer   | Account balance after this operation                     |
| `account_version`        | Integer   | Account version after this operation                     |
| `account_balance_policy` | String    | Balance policy applied on this side                      |
| `idempotency_key`        | String    | The idempotency key from the original request            |
| `created_at`             | Timestamp | When this line was created                               |

## How Ledger Lines are Created

For each journal entry in a transaction, two ledger lines are created:

1. A **debit** line on the debit account (balance decreases)
2. A **credit** line on the credit account (balance increases)

The debit line is always written before the credit line for each journal entry.

## Querying the Ledger

```bash
curl "http://<host>:8080/account/<account_id>/ledger?limit=50" \
  -H "X-Api-Key: ak_..." \
  -H "X-Api-Secret: sk_..."
```

### Query Parameters

| Parameter | Type    | Default | Description                                      |
| --------- | ------- | ------- | ------------------------------------------------ |
| `from`    | String  | —       | Start date (`YYYY-MM-DD`) or datetime (ISO 8601) |
| `to`      | String  | —       | End date (`YYYY-MM-DD`) or datetime (ISO 8601)   |
| `cursor`  | Integer | —       | `account_version` (exclusive) from previous page |
| `limit`   | Integer | 50      | Items per page (1–200)                           |

### Pagination

The ledger uses **cursor-based pagination** via `account_version`. On each response, use the last `account_version` returned as the `cursor` for the next page.

**First page:**

```bash
curl "http://<host>:8080/account/<id>/ledger?limit=50"
```

**Next page (assuming last version was 50):**

```bash
curl "http://<host>:8080/account/<id>/ledger?cursor=50&limit=50"
```

### Date Filtering

Filter ledger lines by date range:

```bash
# Lines from January 2026
curl "http://<host>:8080/account/<id>/ledger?from=2026-01-01&to=2026-01-31"

# Lines from a specific datetime
curl "http://<host>:8080/account/<id>/ledger?from=2026-01-15T10:00:00Z"
```

## Ledger Consistency

The ledger guarantees:

1. **Sequential versioning** — `account_version` increments by 1 with no gaps per account
2. **Correct balance evolution** — each `account_post_balance` is correctly derived from the previous balance plus/minus the amount
3. **Completeness** — every journal entry creates exactly two ledger lines (one debit, one credit)

## Ledger and Archiving

Over time, the ledger table grows as transactions accumulate. You can archive historical ledger data to reduce table size while preserving full history. See [Ledger Archive](/docs/concepts/ledger-archive.md) for details.

When ledger lines have been archived, the first available `account_version` in the live ledger may be greater than 1. Consult the [archive endpoint](/docs/api-reference/ledger-archive.md) for older data.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://entrytarget.gitbook.io/docs/concepts/ledger.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.