Get User Wallet Transactions

Retrieves transaction records for a user across their wallets. Unlike the Wallet History endpoint, which retrieves transactions for a specific wallet, this endpoint uses the user_ref to return transactions across the user's wallets, including different currencies and wallet types.

Endpoint

GET {{base_url}}/api/v1/transaction/wallet-query

Authentication

Requires your Merchant API Key.

Headers

Header	Required	Description
`X-merchant-ref`	Yes	Your unique merchant reference.

Example Request

curl --location -g '{{base_url}}/api/v1/transaction/wallet-query?user_ref={USER_REF}&date_from=2026-01-18&date_to=2026-09-20&page=1&no_records=10&sort=desc' \
--header 'X-merchant-ref: {{x-merchant-ref}}'

Query Parameters

Parameter	Required	Type	Description
`user_ref`	Yes	String	Reference of the user whose wallet transactions are being retrieved.
`date_from`	No	Date	Start date for the transaction history. Format: `YYYY-MM-DD`.
`date_to`	No	Date	End date for the transaction history. Format: `YYYY-MM-DD`.
`page`	No	Integer	Page number for paginated results.
`no_records`	No	Integer	Number of records to return per page.
`sort`	No	String	Sort order for the results. Accepted values: `asc` or `desc`.

Response

`200 OK`

{
  "status": "success",
  "message": "Retrieved successfully",
  "data": [
    {
      "amount": 0.04892368,
      "available_balance_after": 90.89004311,
      "available_balance_before": 90.84111943,
      "category": "TRANSFER",
      "currency": "NGN",
      "date": "2026-09-16T14:28:22.351627Z",
      "description": "WALLET_TRANSFER_CREDIT",
      "ledger_balance_after": 0,
      "ledger_balance_before": 0,
      "payment_reference": "sw_00000441_1_2_2_1-credit",
      "reference": "sw_00000441_1_2_2_1-credit",
      "status": "SUCCESSFUL",
      "type": "CREDIT",
      "wallet_id": "LBWCADFAE7405062AC4815B971F6DEB0F1EE0200DKT"
    },
    {
      "amount": 50,
      "available_balance_after": 467,
      "available_balance_before": 517,
      "category": "WALLET_TRANSFER",
      "currency": "NGN",
      "date": "2026-09-16T14:28:22.295491Z",
      "description": "WALLET_SWAP_DEBIT",
      "ledger_balance_after": 0,
      "ledger_balance_before": 0,
      "payment_reference": "sw_00000441_1_2_2_1-debit",
      "reference": "sw_00000441_1_2_2_1-debit",
      "status": "SUCCESSFUL",
      "type": "DEBIT",
      "wallet_id": "LBWNGN81C4801EE29D43F8A0B2231E367B74550063J"
    },
    {
      "amount": 0.5,
      "available_balance_after": 0,
      "available_balance_before": 0,
      "category": "COLLECTION",
      "currency": "USDT:POL",
      "date": "2026-09-08T08:05:03.986433Z",
      "description": "DYNAMIC_COLLECTION",
      "ledger_balance_after": 0,
      "ledger_balance_before": 0,
      "payment_reference": "6a733723-7724-4efc-8f57-3cd923b0e01c",
      "reference": "LIVE_0009_02_09_0162",
      "status": "PENDING",
      "type": "CREDIT",
      "wallet_id": "LBWUSDT:POL1649B6B5F7524B3C9DE3618DF461947200F2Y"
    }
  ]
}

Response Fields

Field	Type	Description
`amount`	Number	Amount involved in the transaction.
`available_balance_after`	Number	Available wallet balance after the transaction.
`available_balance_before`	Number	Available wallet balance before the transaction.
`category`	String	Transaction category, such as `TRANSFER`, `WALLET_TRANSFER`, `COLLECTION`, or `PAYOUT`.
`currency`	String	Currency of the transaction, such as `NGN`, `CAD`, or `USDT:POL`.
`date`	String	Date and time when the transaction was recorded.
`description`	String	Description or internal classification of the transaction.
`ledger_balance_after`	Number	Ledger balance after the transaction.
`ledger_balance_before`	Number	Ledger balance before the transaction.
`payment_reference`	String	Payment reference associated with the transaction.
`reference`	String	Unique transaction reference.
`status`	String	Transaction status, such as `SUCCESSFUL` or `PENDING`.
`type`	String	Indicates whether the transaction is a `CREDIT` or `DEBIT`.
`wallet_id`	String	ID of the wallet associated with the transaction.