# Transactions

List, filter, and retrieve ledger transactions with related data.

Transactions are the core ledger primitive. Amount is negative for outflows, positive for inflows.

### `GET /api/v1/transactions`

List ledger transactions for the token's organization. Results are ordered by date descending. Agents should keep limit≤50 unless exporting.

- operationId: `list_transactions`
- scope: `read`

**Parameters**

- `status` (enum, optional) — uncategorized, matched, receipt_missing, agent_suggested, reconciled
- `source` (enum, optional) — nordea, stripe, manual_csv
- `date` (date, optional) — Exact date (YYYY-MM-DD)
- `dateFrom` (date, optional) — Inclusive start date
- `dateTo` (date, optional) — Inclusive end date
- `category` (string, optional) — Exact category name, or __uncategorized__
- `description` (string, optional) — Case-insensitive substring on description
- `limit` (integer, optional) — Default 50 (agent-lean), max 500
- `offset` (integer, optional) — Default 0

**Response**

```json
{
  "data": [ { "id": "…", "date": "2026-08-28", "amount": -842, "currency": "EUR", … } ],
  "meta": { "totalCount": 42, "limit": 50, "offset": 0 }
}
```

### `GET /api/v1/transactions/{id}`

Full transaction with linked notes and receipts. Prefer this over list_notes for investigation.

- operationId: `get_transaction`
- scope: `read`

**Parameters**

- `id` (uuid, required) — Transaction ID

**Response**

```json
{
  "data": {
    "transaction": { … },
    "notes": [ { "id": "…", "content": "…", "createdAt": "…" } ],
    "receipts": [ { "id": "…", "fileName": "invoice.pdf", … } ]
  }
}
```

## Status values

| Status | Meaning |
| --- | --- |
| uncategorized | No category assigned |
| matched | Categorized and matched |
| receipt_missing | Needs a receipt |
| agent_suggested | Legacy ledger status (demo/UI). Pending agent work is in proposals |
| reconciled | Fully reconciled |

## Source values

| Source | Origin |
| --- | --- |
| nordea | Bank feed |
| stripe | Stripe payouts/charges |
| manual_csv | Manual import or entry |