List Wallet Ledger Entries

Returns wallet ledger entries for one billing account in a project. Use this endpoint to audit balance changes such as top-ups, debits, voucher grants, and reconciliation, with optional filtering by change type.

GET /v1/projects/:project_id/wallet-ledger-entries

Authentication

Authorization: Bearer <api-key>

Requires wallets read access.

Path Parameters

Field	Required	Description
`project_id`	Yes	Project that owns the account and wallet ledger.

Request Body

This endpoint has no request body.

Query Parameters

Field	Required	Description
`account_id`	Yes	Billing account ID in the same project.
`wallet_id`	No	Filter by wallet ID. The wallet must belong to `account_id`, and when `currency` is also sent it must match that wallet. A wallet filter returns only that wallet’s entries; voucher entries carry no `wallet_id` and are therefore excluded.
`currency`	No	Filter by currency, for example `USD`.
`direction`	No	Filter by change direction. `credit` covers inbound entries such as top-ups and voucher grants, `debit` covers outbound entries such as charges and voucher revokes. These two values are exhaustive; use `fund_type` to separate cash from voucher entries.
`fund_type`	No	Filter by fund source: `cash` or `voucher`.
`source_type`	No	Filter by business reason. Must be one of the supported source types: `initial_balance`, `manual_topup`, `payment`, `credit_grant`, `adjustment`, `manual_debit`, `order`, `service_fee`, `usage_debit`, `usage_interim_bill`, `voucher_grant`, `voucher_revoke`, `voucher_revoke_pending_usage`.
`start_time`	No	Inclusive lower bound for ledger `created_at`, as a Unix timestamp in seconds.
`end_time`	No	Inclusive upper bound for ledger `created_at`, as a Unix timestamp in seconds.
`sort_order`	No	Sort by `created_at` (and `id` as a stable tie-breaker) in `asc` or `desc` order. Defaults to `desc`.
`limit`	No	Page size. Defaults to `50`; maximum is `200`.
`offset`	No	Page offset. Defaults to `0`.

Example

curl 'http://127.0.0.1:8080/v1/projects/proj_gateway/wallet-ledger-entries?account_id=acct_org_001&wallet_id=wlt_xxx&start_time=1783000000&end_time=1785600000&sort_order=asc&limit=50&offset=0' \
  -H 'Authorization: Bearer <api-key>'

Response

{
  "ledger_entries": [
    {
      "id": "wle_xxx",
      "tenant_id": "t_001",
      "project_id": "proj_gateway",
      "account_id": "acct_org_001",
      "wallet_id": "wlt_xxx",
      "currency": "USD",
      "fund_type": "cash",
      "fund_id": "",
      "direction": "debit",
      "amount": "8.00",
      "balance_after": "12.00",
      "source_type": "order",
      "source_id": "order_001",
      "idempotency_key": "order_001",
      "usage_version": 8,
      "created_at": 1782720000
    }
  ],
  "total_count": 1,
  "limit": 50,
  "offset": 0
}

Notes

Entries are ordered by created_at and id, newest first by default. Use sort_order=asc for oldest first.
start_time and end_time use an inclusive range: [start_time, end_time]. Omitting either bound leaves that side unbounded; omitting both returns all entries.
Omit direction, fund_type, and source_type to return every change type.
An invalid direction, fund_type, or source_type, or a wallet_id that does not belong to account_id, returns 400. A rejected filter names the offending field and value in the error message, for example invalid wallet ledger filter value: source_type="initial_blance" is not a supported source type or invalid wallet ledger filter value: wallet_id="wal_xxx" does not belong to account_id, so an unsupported filter value is never reported as a missing parameter.
Creating a wallet with a non-zero balance writes one credit entry with source_type=initial_balance, source_id set to the new wallet ID, and balance_after equal to the opening balance. A wallet created with balance=0 has no entry until money actually moves.
Because the opening balance is recorded, the sum of a single wallet’s entries equals its current balance; the credit_limit only affects available_balance and never produces a ledger entry.

remark is the optional business reason and is omitted when empty. source_id identifies a related business record. Legacy top-up notes may remain in source_id; they are not automatically migrated.