> ## Documentation Index
> Fetch the complete documentation index at: https://ifemafia.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /api/wallets/:walletId/ledgers — wallet ledger entries

> Retrieve paginated ledger entries for a wallet. Each entry records a topup, debit, or refund with the resulting balance after the change.

Retrieve the double-entry ledger for a wallet, paginated and sorted newest-first. Every
balance-changing event — fund top-ups, approved payment debits, and refunds — produces a ledger
entry with the resulting `balanceAfter` so you can reconstruct the wallet's balance at any point
in time. Use this endpoint for reconciliation, audit exports, or building a running-balance
display in your dashboard.

## Endpoint

```
GET /api/wallets/:walletId/ledgers
```

## Authentication

Requires a valid **Session JWT** in the `Authorization` header.

```
Authorization: Bearer <session_jwt>
```

***

## Path Parameters

<ParamField path="walletId" type="string" required>
  The UUID of the wallet whose ledger you want to retrieve.
</ParamField>

***

## Query Parameters

<ParamField query="page" type="integer" default="1">
  The page number to retrieve. Pages are 1-indexed.
</ParamField>

<ParamField query="pageSize" type="integer" default="10">
  The number of ledger entries to return per page.
</ParamField>

***

## Response `200 OK`

The response envelope contains `success: true`, a `data` array of ledger entries, and a
`pagination` object with totals.

<ResponseField name="success" type="boolean">
  Always `true` for a successful response.
</ResponseField>

<ResponseField name="data" type="object[]">
  Array of ledger entry objects for the requested page, sorted newest-first.

  <Expandable title="ledger entry fields">
    <ResponseField name="data[].id" type="string">
      Unique ledger entry UUID.
    </ResponseField>

    <ResponseField name="data[].walletId" type="string">
      The wallet this entry belongs to.
    </ResponseField>

    <ResponseField name="data[].type" type="string">
      The type of balance event. One of:

      * `"topup"` — funds were credited to the wallet (e.g. bank transfer received).
      * `"debit"` — funds were debited for an approved payment.
      * `"refund"` — a previous debit was reversed and funds returned to the wallet.
    </ResponseField>

    <ResponseField name="data[].amount" type="integer">
      The absolute value of the balance change, in **kobo**. Always positive regardless of
      direction — use `type` to determine whether the balance increased or decreased.
    </ResponseField>

    <ResponseField name="data[].balanceAfter" type="integer">
      The wallet balance in **kobo** immediately after this entry was applied. Use this field
      to render a running balance column.
    </ResponseField>

    <ResponseField name="data[].transactionId" type="string | null">
      The UUID of the associated transaction record, if this entry was produced by a payment
      authorisation or refund. `null` for `topup` entries.
    </ResponseField>

    <ResponseField name="data[].reference" type="string | null">
      A human-readable reference string, or `null` when no reference is available. For top-ups
      this is typically the inbound bank transfer reference; for debits and refunds it mirrors
      the transaction reference.
    </ResponseField>

    <ResponseField name="data[].createdAt" type="string">
      ISO 8601 timestamp of when this ledger entry was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Metadata about the paginated result set.

  <Expandable title="pagination fields">
    <ResponseField name="pagination.page" type="integer">
      The current page number.
    </ResponseField>

    <ResponseField name="pagination.pageSize" type="integer">
      The number of entries per page.
    </ResponseField>

    <ResponseField name="pagination.totalCount" type="integer">
      Total number of ledger entries across all pages.
    </ResponseField>

    <ResponseField name="pagination.totalPages" type="integer">
      Total number of pages at the current `pageSize`.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "led_f1e2d3c4-b5a6-4789-bcde-f01234567890",
      "walletId": "wlt_f7e6d5c4-b3a2-4190-8fed-cba987654321",
      "type": "refund",
      "amount": 345000,
      "balanceAfter": 1595000,
      "transactionId": "txn_d4e5f6a7-b8c9-4012-8def-012345678901",
      "reference": "AXS-20250715-0041-REFUND",
      "createdAt": "2025-07-15T13:27:05Z"
    },
    {
      "id": "led_a0b1c2d3-e4f5-4678-abcd-e09876543210",
      "walletId": "wlt_f7e6d5c4-b3a2-4190-8fed-cba987654321",
      "type": "debit",
      "amount": 345000,
      "balanceAfter": 1250000,
      "transactionId": "txn_d4e5f6a7-b8c9-4012-8def-012345678901",
      "reference": "AXS-20250715-0041",
      "createdAt": "2025-07-15T11:03:44Z"
    },
    {
      "id": "led_b2c3d4e5-f6a7-4890-cdef-123456789012",
      "walletId": "wlt_f7e6d5c4-b3a2-4190-8fed-cba987654321",
      "type": "topup",
      "amount": 2000000,
      "balanceAfter": 1595000,
      "transactionId": null,
      "reference": "TRF-2025071501-WEMA",
      "createdAt": "2025-07-15T09:55:30Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "totalCount": 12,
    "totalPages": 2
  }
}
```

***

## Error Responses

| Status | Code               | Description                                    |
| ------ | ------------------ | ---------------------------------------------- |
| `401`  | `UNAUTHORIZED`     | Missing or invalid Session JWT.                |
| `404`  | `WALLET_NOT_FOUND` | No wallet exists with the supplied `walletId`. |

```json theme={null}
{
  "error": {
    "code": "WALLET_NOT_FOUND",
    "message": "No wallet found with ID wlt_f7e6d5c4-b3a2-4190-8fed-cba987654321."
  }
}
```