Read your naira wallet and transaction history - BITLIVA Merchant API

Your naira wallet is the account that pays for crypto purchases and receives the proceeds of sales and approved gift cards. This guide shows how to read its balance and its transaction history.

Check your wallet balance

curl https://merchant.bitliva.com/api/v1/balance \
  -H "Authorization: Bearer $BITLIVA_API_KEY"

{
  "status": "success",
  "message": "Balance retrieved successfully.",
  "data": {
    "balance": "5000000.00",
    "currency": "NGN",
    "mode": "test"
  }
}

Amounts are returned as strings so that you never lose precision.

List transactions

GET /transactions returns your transactions. Filter and page through them with these query parameters:

Parameter	Description
`type`	One of `topup`, `withdrawal`, `crypto_buy`, `crypto_sell`, `crypto_deposit`, `giftcard_sale`.
`status`	One of `pending`, `successful`, `failed`.
`per_page`	Between 1 and 100. Default 20.
`page`	Page number.

Get a single transaction with GET /transactions/{id}.

The transaction object

{
  "id": "9d3c5a1e-5b7e-4c2a-9f43-0c6c1b7a2d10",
  "type": "crypto_sell",
  "status": "successful",
  "amount": "98010.00",
  "fee": "0.00",
  "currency": "NGN",
  "reference": "order-1042",
  "customer_id": "2f6d1c0a-8a3e-4d59-b8a1-71e0c4d5f9a3",
  "details": null,
  "crypto": {
    "currency": "btc",
    "amount": "0.001"
  },
  "created_at": "2026-10-18T10:15:00+01:00"
}

Field	Description
`id`	The transaction’s UUID.
`type`	What kind of transaction it is. See the table below.
`status`	`pending`, `successful` or `failed`.
`amount`	The naira amount, as a string.
`fee`	The fee charged, as a string.
`currency`	`NGN`.
`reference`	The reference you sent when you created it.
`customer_id`	The customer it belongs to.
`details`	Extra information. For gift card sales it holds `card`, `card_value_usd` and `rate`. Otherwise `null` in the examples.
`crypto`	The `currency` and `amount` of crypto involved. `null` for gift card sales.
`created_at`	ISO 8601 timestamp.

Transaction types

`type`	Description
`topup`	Naira added to your wallet.
`withdrawal`	Naira withdrawn from your wallet.
`crypto_buy`	A crypto purchase for a customer.
`crypto_sell`	A crypto sale for a customer.
`crypto_deposit`	Crypto received at a customer’s address.
`giftcard_sale`	A gift card sale.

A transaction that is still pending finishes later, and a webhook tells you the outcome.