---
title: "Ledger history"
method: GET
path: "/wallets/{wallet_token}/ledger"
tags: ["Ledger"]
---

# Ledger history

`GET /wallets/{wallet_token}/ledger`

## Request

- Base URL: `https://api.masspay.io/v1.0.0`
- URL: `https://api.masspay.io/v1.0.0/wallets/{wallet_token}/ledger`
- Auth: one of:
  - API key in header `Authorization`
  - API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/masspay/apis/masspay-api/docs/wallets/:wallet_token/ledger/get.ts> (a function with typed inputs; its response is checked against the schema)

This **GET** endpoint is used to retrieve a list of all ledger entries, including payouts, payins, loads, spendbacks, fees, credits, and reversals, for a wallet with the provided wallet token. <br> You can use this endpoint to obtain a comprehensive history of balance movements for the provided wallet, allowing you to track and reconcile its activity over time. <br> To use this endpoint, you need to provide the `wallet_token` as a parameter in the URL Path. <br> The response will contain a JSON array of ledger entry objects, each including entry details, along with pagination metadata. Results can be paginated either with `page` or with `last_token`, passing the token of the last ledger entry from a previous response; the two parameters cannot be combined in the same request.

## Query parameters

- `number_of_records` number
- `start_date` string, date
- `end_date` string, date
- `page` integer
- `last_token` string
- `type` 'payout' | 'payout_cancel' | 'payout_reversal' | 'payin' | 'payin_reversal' | 'payin_deposit_return' | 'topup' | 'topup_reversal' | 'service_fee' | 'wallet_credit' | 'wallet_debit' | 'spendback' | 'load' | 'load_reversal' | 'spendback_reversal'

## Headers

- `Idempotency-Key` string

## Response `200`

Succesful operation.

- LedgerHistoryResp
  - `ledger_entries` LedgerEntry[], required
    - `token` string, required: Prefixed ledger entry identifier.
    - `wallet_token` string, required: Prefixed wallet identifier. User wallets use the `usr_wlt_` prefix and client wallets use the `clnt_wlt_` prefix.
    - `user_token` string: Prefixed user identifier.
    - `metadata` object: Optional JSON object with attributes associated with the transaction
    - `amount` number, double, required: Signed amount of the entry in the wallet's currency, with up to two decimal places. Negative values decrease the wallet balance.
    - `currency_code` string, required: Currency code of the wallet in which the entry is denominated. Three-letter ISO 4217 codes for fiat currencies (e.g. `USD`) and up to five characters for cryptocurrencies (e.g. `USDC`, `MATIC`).
    - `timestamp` string, date-time, required: Time at which the entry was recorded, ISO 8601 with millisecond precision.
    - `notes` string, required: Free-form notes attached to the entry.
    - `type` 'payout' | 'payout_cancel' | 'payout_reversal' | 'payin' | 'payin_reversal' | 'payin_deposit_return' | 'topup' | 'topup_reversal' | 'service_fee' | 'wallet_credit' | 'wallet_debit' | 'spendback' | 'load' | 'load_reversal' | 'spendback_reversal', required: The kind of ledger movement.
    - `ref_token` string: Prefixed token of a source transaction object, such as a payout, payin, top-up, load, or spendback. The prefix identifies the resource type.
    - `ref_tokens` SourceTransactionToken[]: Tokens of the source transactions that produced this ledger entry, such as a payout, payin, top-up, load, or spendback. Null for entries with no associated source object.
  - `metadata` object, required
    - `current_page` integer
    - `total_results` integer
    - `results_per_page` integer
    - `total_pages` integer

## Other responses

- `400`: Bad request.
- `401`: Unauthorized.
- `403`: Forbidden.
- `404`: Not found.
- `405`: Method Not Allowed.
- `500`: Internal server error.
- `504`: Gateway Time-out.

## Changes

- **2026-11-03** `f9fa41b7c45c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/masspay/apis/masspay-api/changes/wallets/:wallet_token/ledger/get.md)

---

[API](https://skmtc.dev/masspay/apis/masspay-api.md) - [All operations](https://skmtc.dev/masspay/apis/masspay-api/llms.txt) - [OpenAPI document](https://skmtc.dev/masspay/apis/masspay-api/revisions/f9fa41b7c45c?raw)