Balance

Use this endpoint to retrieve your business wallet balances — the total available balance across all supported tokens, with a fiat equivalent breakdown.

Authentication: Secret key (Authorization: sk_...)

---

Endpoints

Method	Path	Auth	Description
GET	/v1/balance	API Key	Get total balance with breakdown

---

GET /v1/balance

Returns the total available balance across all your wallets, expressed in your chosen fiat currency, along with a per-token breakdown.

Query Parameters

Parameter	Type	Required	Description
fiatCurrency	string	No	Fiat currency to express the total balance in. Defaults to USD. See supported values.

Request

GET /v1/balance?fiatCurrency=NGN
Authorization: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Response

{
  "status": true,
  "message": "Balance retrieved successfully",
  "data": {
    "totalAvailableBalance": 75430.50,
    "usdEquivalent": 48.20,
    "breakDown": [
      {
        "currency": "USDT",
        "balance": 30.00,
        "status": "ACTIVE"
      },
      {
        "currency": "USDC",
        "balance": 18.20,
        "status": "ACTIVE"
      }
    ]
  }
}

Response Fields

Field	Type	Description
totalAvailableBalance	number	Sum of all wallet balances converted to the requested fiatCurrency
usdEquivalent	number	Sum of all wallet balances converted to USD
breakDown	array	Per-token wallet details
breakDown[].currency	string	Crypto token (e.g. USDT, USDC)
breakDown[].balance	number	Available balance for this token
breakDown[].status	string	Wallet status — ACTIVE or INACTIVE

---

Code Samples

Node.js

const axios = require('axios');

const { data } = await axios.get('https://api.ivorypay.io/api/v1/balance', {
  params: { fiatCurrency: 'NGN' },
  headers: { Authorization: 'sk_live_xxxxxxxxxxxxxxxxxxxxxxxx' },
});

const { totalAvailableBalance, usdEquivalent, breakDown } = data.data;

console.log(`Total balance: NGN ${totalAvailableBalance}`);
console.log(`USD equivalent: $${usdEquivalent}`);

breakDown.forEach((wallet) => {
  console.log(`${wallet.currency}: ${wallet.balance}`);
});

Python

import requests

response = requests.get(
    'https://api.ivorypay.io/api/v1/balance',
    params={'fiatCurrency': 'NGN'},
    headers={'Authorization': 'sk_live_xxxxxxxxxxxxxxxxxxxxxxxx'},
)

data = response.json()['data']
print(f"Total balance: NGN {data['totalAvailableBalance']}")
print(f"USD equivalent: ${data['usdEquivalent']}")

for wallet in data['breakDown']:
    print(f"{wallet['currency']}: {wallet['balance']}")

cURL

curl "https://api.ivorypay.io/api/v1/balance?fiatCurrency=NGN" \
  -H "Authorization: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

---

Supported Fiat Currencies

Value	Currency
USD	US Dollar (default)
NGN	Nigerian Naira
KES	Kenyan Shilling
GHS	Ghanaian Cedi
ZAR	South African Rand
XOF	West African CFA Franc

---

Notes

• Balances reflect settled funds only — pending transactions are not included

• A wallet with status: INACTIVE still shows a balance but cannot be used for payouts until reactivated

• Use your live secret key to query live balances, and your test secret key for test environment balances