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

# Read your naira wallet and transaction history

> Check your naira balance, list transactions with type and status filters, and understand every field on a Bitliva transaction object.

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

```bash theme={null}
curl https://merchant.bitliva.com/api/v1/balance \
  -H "Authorization: Bearer $BITLIVA_API_KEY"
```

```json theme={null}
{
  "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`](https://docs.bitliva.com/api-reference/transactions-list) 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}`](https://docs.bitliva.com/api-reference/transactions-get).

## The transaction object

```json theme={null}
{
  "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](https://docs.bitliva.com/guides/buy-and-sell-crypto.md) for a customer. |
| `crypto_sell` | A [crypto sale](https://docs.bitliva.com/guides/buy-and-sell-crypto.md) for a customer. |
| `crypto_deposit` | Crypto received at a customer's address. |
| `giftcard_sale` | A [gift card sale](https://docs.bitliva.com/guides/gift-cards.md). |

A transaction that is still `pending` finishes later, and a [webhook](https://docs.bitliva.com/guides/webhooks.md) tells you the outcome.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.