Ledger balances (or balances, for short) are used to represent store of value in your Blnk Ledger, i.e., accounts, wallets, card balance, etc. They also represent the source or destination of a transaction record. All ledger balances in the Blnk Ledger each have 6 main balance attributes:
  1. balance: This shows the current value held in the ledger balance.
  2. credit_balance: This is the total sum of all amounts received by a ledger balance.
  3. debit_balance: This is the total sum of all amounts sent by a ledger balance.
  4. inflight_balance: This shows the net amount held inflight for a balance.
  5. inflight_credit_balance: This is the total sum of all amount waiting to be received by a ledger balance.
  6. inflight_debit_balance: This is the total sum of all amount waiting to be deducted from a ledger balance.
Important to note: Balance amounts are immutable and can only be updated through transactions. You cannot manually set or alter a balance amount directly.

​
Creating a balance

To create a balance in Blnk, call the Create Balance endpoint: 
{
    "ledger_id": "ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
    "currency": "USD",
    "meta_data": {
        "first_name": "Alice",
        "last_name": "Hart",
        "account_number": "1234567890"
    }
}
Response
{
    "balance": 0,
    "version": 0,
    "inflight_balance": 0,
    "credit_balance": 0,
    "inflight_credit_balance": 0,
    "debit_balance": 0,
    "inflight_debit_balance": 0,
    "precision": 0,
    "ledger_id": "ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
    "identity_id": "",
    "balance_id": "bln_e39a239a-a6ca-4509-b0d9-29dcc5630f8a",
    "indicator": "",
    "currency": "USD",
    "created_at": "2024-07-05T08:13:18.882616461Z",
    "meta_data": {
        "customer_internal_id": "1234",
        "customer_name": "Jerry"
    }
}
All newly created balances in the Blnk Ledger start from 0. You cannot create a ledger balance with a predefined balance amount.

​
Queued balances

Available in version 0.8.3 and later.
You can track total transaction amounts in queue per balance via the queued_credit_balance and queued_debit_balance attributes. These attributes show the cumulative value of all queued transactions that will affect a balance once they’re processed. When you query a balance, you’ll see:
  1. queued_credit_balance: Total amount of incoming transactions waiting to be processed.
  2. queued_debit_balance: Total amount of outgoing transactions waiting to be processed.
This helps you estimate the potential impact of queued transactions on your balance before they’re processed.
Use queued balances to check if a balance has pending transactions. If either queued_credit_balance or queued_debit_balance is greater than 0, there are transactions waiting in the queue for that balance.
Queued balances are estimates and may change as transactions are processed or if queue processing fails. Always verify final balances after queue processing completes.
To view the queued balances of a ledger balance: 
curl -X GET 'http://YOUR_BLNK_INSTANCE_URL/balances/{balance_id}?with_queued=true' \
  -H 'Authorization: Bearer YOUR_API_KEY'

​
Calculating expected and available balances

Use these formulas to understand your balance position:
  1. Expected balance: What your balance will be after all queued credits are processed 
    expected_balance = current_balance + queued_credit_balance
  2. Available balance: How much you can safely spend or transfer (accounting for pending debits) 
    available_balance = current_balance - inflight_debit_balance - queued_debit_balance
Example: If your current balance is 100,youhave100, you have 50 in queued credits, and $20 in queued debits:
  • Expected balance: 100+100 + 50 = $150
  • Available balance: 100−100 - 0 - 20=20 = 80

​
Multi-currency balances

Blnk enables you to create and manage balances in multiple currencies within your ledger. When building multi-currency wallets with Blnk, keep the following in mind:
  1. Standardize precision across currencies: Most fiat currencies have a precision of 100. However, when managing currencies with different precision values, such as crypto and fiat, it’s crucial to use the highest precision value for all transactions in your ledger. This ensures consistency when calculating transactions and converting exchange rates between currencies.

​
Balance overdrafts

An overdraft occurs when a transaction reduces a ledger balance below zero, resulting in a negative balance. This means that the amount debited exceeds the available funds in the account. While traditionally seen as a deficit, in Blnk, a negative balance is simply another balance state and can be used flexibly, especially depending on the type of financial product. In Blnk, implementing overdrafts is straightforward. By setting the allow_overdraft attribute when initiating a transaction, you can allow a ledger balance to fall below 0. This feature is valuable as it provides insights and reflects the position of a balance, especially useful in certain product contexts, such as lending or line-of-credit services. See the following: Applying overdrafts

​
Why negative balances?

In Blnk, a negative balance is simply a balance state and doesn’t necessarily mean there’s a problem. For example, it can simply show borrowed funds, as expected in products like loans or credit, where it reflects the amount owed. It could also mean that a balance has more debits than credits — this is especially relevant for internal balances like @World. To learn more, see the following: Internal balances Moreover, a negative balance is often temporary and can revert to a positive balance under certain conditions, such as:
  1. Incoming Credits: When new funds are credited to the account, they reduce or eliminate the negative balance.
  2. Scheduled Repayments: For products like loans, regular repayments or scheduled deposits will move the balance back toward positive territory over time, ultimately making it positive if the full overdraft is repaid.

​
Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool. To ask questions or discuss issues, please contact us or join our Discord community.