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

# Wallet

> Check your Dancity wallet balances via the merchant API

## Overview

Every Dancity merchant account has one or more wallets (e.g., **main**, **bonus**). Your API key is tied to a specific account, so calling the wallet endpoint always returns balances for that account.

Use wallet balances to:

* Display a live balance before processing a purchase
* Check which wallet type (`wallettype`) to pass in a buy request
* Detect low-balance conditions and alert your team

## Authentication

Wallet reads use your **merchant API key** only — no `channel: API` header is required for this endpoint.

```http theme={null}
Authorization: Bearer dcy_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

## Get wallets balance

```
GET /api/v1/wallet
```

Returns all wallets linked to the API key's account, including their types and current balances.

### Example

```bash cURL theme={null}
curl -sS "https://api.dancity.app/api/v1/wallet" \
  -H "Authorization: Bearer $DANCITY_API_KEY"
```

```javascript Node.js theme={null}
const res = await fetch("https://api.dancity.app/api/v1/wallet", {
  headers: {
    Authorization: `Bearer ${process.env.DANCITY_API_KEY}`,
  },
});
const { data } = await res.json();
console.log(data); // array of wallet objects
```

```python Python theme={null}
import requests, os

res = requests.get(
    "https://api.dancity.app/api/v1/wallet",
    headers={"Authorization": f"Bearer {os.environ['DANCITY_API_KEY']}"},
)
print(res.json()["data"])
```

### Sample response

```json theme={null}
{
  "success": true,
  "message": "Wallets retrieved",
  "data": [
    {
      "wallettype": "main",
      "balance": 15000.00,
      "currency": "NGN"
    },
    {
      "wallettype": "bonus",
      "balance": 250.00,
      "currency": "NGN"
    }
  ]
}
```

## Using wallet types in purchases

Most buy endpoints accept an optional `wallettype` field. Omit it to debit your **main** wallet, or pass a value from `GET /api/v1/wallet` (e.g. `"main"`, `"bonus"`).

```json theme={null}
{
  "plan": "PLAN_ID",
  "phone": "08012345678"
}
```

> [!WARNING]
>
> If your balance is insufficient for the purchase amount, the API returns a `400` error with a message indicating low balance. Always check balances before bulk purchase flows.

## Next steps

* [Buy airtime or data](https://docs.dancity.app/guides/airtime-data.md)
* [Buy cable TV subscription](https://docs.dancity.app/guides/cable-tv.md)
* [Vend electricity](https://docs.dancity.app/guides/electricity.md)


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