Skip to main content
Retrieves a balance using a custom indicator and currency. Indicators allow you to reference balances using domain-specific identifiers like phone numbers, email addresses, or account numbers instead of the system-generated balance ID.

​
Path Parameters

​
indicator
string
required
The custom indicator value to look up the balance. This can be any unique identifier relevant to your application.Examples:
  • Phone number: +1234567890
  • Email: [email protected]
  • Account number: ACC-12345
  • Custom ID: merchant_settlement_001
​
currency
string
required
The currency code for the balance. Required because an indicator might be associated with multiple balances in different currencies.Example: USD, EUR, NGN

​
Response

Returns a complete balance object matching the indicator and currency combination.
​
balance_id
string
Unique identifier for the balance.
​
ledger_id
string
The ledger ID this balance belongs to.
​
identity_id
string
The identity ID associated with this balance.
​
indicator
string
The indicator value used to retrieve this balance.
​
currency
string
The currency code for this balance.
​
balance
string
The current balance amount (credit_balance - debit_balance). Returned as a big integer string.
​
credit_balance
string
Total credits applied to this balance.
​
debit_balance
string
Total debits applied to this balance.
​
inflight_balance
string
Total balance currently in inflight transactions.
​
inflight_credit_balance
string
Credits currently in inflight status.
​
inflight_debit_balance
string
Debits currently in inflight status.
​
currency_multiplier
float
The precision multiplier for this balance.
​
version
integer
Version number for optimistic concurrency control.
​
track_fund_lineage
boolean
Whether fund lineage tracking is enabled.
​
allocation_strategy
string
The allocation strategy for fund lineage (FIFO, LIFO, or PROPORTIONAL).
​
created_at
string
ISO 8601 timestamp when the balance was created.
​
inflight_expires_at
string
ISO 8601 timestamp when current inflight transactions expire.
​
meta_data
object
Custom metadata attached to the balance.

​
Examples

curl https://api.blnk.io/balances/indicator/+1234567890/currency/USD \
  -H "Authorization: Bearer YOUR_API_KEY"
Response Example
{
  "balance_id": "bal_123abc",
  "ledger_id": "ldg_456def",
  "identity_id": "usr_789ghi",
  "indicator": "+1234567890",
  "currency": "USD",
  "balance": "50000",
  "credit_balance": "100000",
  "debit_balance": "50000",
  "inflight_balance": "0",
  "inflight_credit_balance": "0",
  "inflight_debit_balance": "0",
  "currency_multiplier": 100,
  "version": 42,
  "track_fund_lineage": false,
  "allocation_strategy": "FIFO",
  "created_at": "2024-01-15T10:30:00Z",
  "inflight_expires_at": "2024-01-15T11:00:00Z",
  "meta_data": {
    "phone_verified": true,
    "account_type": "mobile_money"
  }
}

​
Use Cases

​
Mobile Money Wallets

Use phone numbers as indicators for mobile money balances: 
GET /balances/indicator/+254712345678/currency/KES

​
Email-Based Accounts

Retrieve balances using email addresses: 
GET /balances/indicator/[email protected]/currency/USD

​
Multi-Currency Support

The same indicator can have balances in multiple currencies: 
GET /balances/indicator/user123/currency/USD
GET /balances/indicator/user123/currency/EUR
GET /balances/indicator/user123/currency/GBP

​
Internal Accounting

Use custom identifiers for internal ledger balances: 
GET /balances/indicator/@revenue/currency/USD
GET /balances/indicator/@fees_collected/currency/USD

​
Auto-Creation with Indicators

When using indicators in transactions, Blnk can automatically create balances if they don’t exist. This is particularly useful for:
  • Dynamic balance creation during transaction processing
  • Simplified onboarding flows
  • Internal system balances (prefixed with @)
Example Transaction: 
{
  "source": "@world",
  "destination": "+254712345678",
  "amount": 100.00,
  "currency": "KES",
  "description": "Initial deposit"
}
This transaction would automatically create a balance with indicator +254712345678 if it doesn’t exist.

​
Error Responses

​
error
string
Error message when the balance is not found or parameters are invalid.
Common Errors:
  • 404 Not Found: No balance exists with the specified indicator and currency combination
  • 400 Bad Request: Missing or invalid indicator or currency parameter

Build docs developers (and LLMs) love

Get started for freeTalk to us