Balances

What are balances?

Balances represent individual accounts that hold funds in your ledger system. Each balance tracks the total amount of money, along with detailed credit and debit information. Balances are the fundamental building blocks of your financial system - they’re where money is stored and from which transactions flow. Every balance:

Belongs to exactly one ledger
Has a specific currency
Maintains separate credit and debit totals
Tracks inflight (pending) amounts
Uses high-precision arithmetic to prevent rounding errors

Balance structure

The Balance model in Blnk contains the following fields:

balance_id

string

Unique identifier for the balance (auto-generated)

balance

big.Int

Current balance in minor units (credit - debit)

credit_balance

big.Int

Total amount credited to this balance

debit_balance

big.Int

Total amount debited from this balance

inflight_balance

big.Int

Total amount in pending/inflight transactions

inflight_credit_balance

big.Int

Pending credits not yet committed

inflight_debit_balance

big.Int

Pending debits not yet committed

queued_debit_balance

big.Int

Scheduled debit amounts

queued_credit_balance

big.Int

Scheduled credit amounts

currency

string

required

Currency code (e.g., “USD”, “EUR”, “NGN”)

currency_multiplier

float64

Multiplier for currency conversion (defaults to 1.0)

ledger_id

string

required

ID of the ledger this balance belongs to

identity_id

string

Optional link to an identity record

indicator

string

Custom identifier for balance lookup

version

int64

Version number for optimistic locking

created_at

timestamp

When the balance was created

inflight_expires_at

timestamp

When inflight amounts expire

meta_data

object

Custom metadata for additional information

track_fund_lineage

boolean

Enable fund flow tracking for this balance

allocation_strategy

string

Strategy for allocating funds (e.g., “FIFO”, “LIFO”)

Example balance object

{
  "balance_id": "bal_abc123def456",
  "balance": "50000",
  "credit_balance": "100000",
  "debit_balance": "50000",
  "inflight_balance": "0",
  "inflight_credit_balance": "0",
  "inflight_debit_balance": "0",
  "currency": "USD",
  "currency_multiplier": 1.0,
  "ledger_id": "ldg_customer123",
  "identity_id": "id_user789",
  "created_at": "2024-03-04T10:30:00Z",
  "version": 15,
  "meta_data": {
    "account_type": "wallet",
    "user_tier": "premium"
  }
}

Understanding balance types

Credit balance

The credit_balance field tracks the total amount of money that has been credited (added) to this balance over time. Credits increase the balance.

Debit balance

The debit_balance field tracks the total amount of money that has been debited (removed) from this balance over time. Debits decrease the balance.

Current balance

The current balance is calculated as:

balance = credit_balance - debit_balance

This follows double-entry accounting principles where credits and debits are tracked separately.

Inflight balances

Inflight amounts represent pending transactions that have been initiated but not yet committed:

inflight_credit_balance: Credits that are held but not yet applied
inflight_debit_balance: Debits that are held but not yet applied
inflight_balance: Net inflight amount (credit - debit)

See Transactions for more on inflight transactions.

Precision and currency handling

Working with precision

Blnk uses big.Int for all balance amounts to ensure perfect precision and avoid floating-point rounding errors. All amounts are stored in the smallest unit of the currency (minor units):

USD: Cents (100 = $1.00)
EUR: Cents (100 = €1.00)
JPY: Yen (1 = ¥1, as yen has no minor unit)
BTC: Satoshis (100000000 = 1 BTC)

When creating transactions, you specify the precision multiplier:

{
  "amount": 10000,
  "precision": 100,
  "currency": "USD"
}

This represents $100.00 (10000 ÷ 100).

The precision field in transactions tells Blnk how to interpret amounts. For most currencies, use 100 (2 decimal places). For cryptocurrencies or high-precision requirements, you can use larger values.

Currency multiplier

The currency_multiplier field allows you to apply conversion rates or scaling factors to balance calculations. This is useful for:

Multi-currency operations
Internal conversion rates
Scaled accounting systems

Creating a balance

Create a balance by sending a POST request to /balances:

curl -X POST http://localhost:5001/balances \
  -H "Content-Type: application/json" \
  -d '{
    "ledger_id": "ldg_customer123",
    "currency": "USD",
    "meta_data": {
      "user_id": "user_789",
      "account_type": "wallet"
    }
  }'

Response

{
  "balance_id": "bal_abc123def456",
  "balance": "0",
  "credit_balance": "0",
  "debit_balance": "0",
  "inflight_balance": "0",
  "inflight_credit_balance": "0",
  "inflight_debit_balance": "0",
  "currency": "USD",
  "currency_multiplier": 1.0,
  "ledger_id": "ldg_customer123",
  "created_at": "2024-03-04T10:30:00Z",
  "version": 0,
  "meta_data": {
    "user_id": "user_789",
    "account_type": "wallet"
  }
}

Creating a balance with an identity

You can link a balance to an identity for customer association:

curl -X POST http://localhost:5001/balances \
  -H "Content-Type: application/json" \
  -d '{
    "ledger_id": "ldg_customer123",
    "currency": "USD",
    "identity_id": "id_user789"
  }'

Using custom indicators

The indicator field lets you use custom identifiers for balance lookup:

curl -X POST http://localhost:5001/balances \
  -H "Content-Type: application/json" \
  -d '{
    "ledger_id": "ldg_customer123",
    "currency": "USD",
    "indicator": "user_789_usd_wallet"
  }'

Later, retrieve the balance by indicator:

curl "http://localhost:5001/balances/indicator/user_789_usd_wallet/currency/USD"

Balance monitoring

Blnk provides Balance Monitors to track balance conditions and trigger webhooks when thresholds are met.

Creating a balance monitor

curl -X POST http://localhost:5001/balance-monitors \
  -H "Content-Type: application/json" \
  -d '{
    "balance_id": "bal_abc123def456",
    "description": "Low balance alert",
    "condition": {
      "field": "balance",
      "operator": "lt",
      "value": 1000,
      "precision": 100
    }
  }'

This monitor triggers a webhook when the balance falls below $10.00 (1000 ÷ 100).

Monitor conditions

You can monitor various balance fields:

balance: Current balance
credit_balance: Total credits
debit_balance: Total debits
inflight_balance: Pending amounts

Supported operators:

lt: Less than
gt: Greater than
lte: Less than or equal to
gte: Greater than or equal to
eq: Equal to

Example: High balance warning

curl -X POST http://localhost:5001/balance-monitors \
  -H "Content-Type: application/json" \
  -d '{
    "balance_id": "bal_abc123def456",
    "description": "Exceeds maximum wallet balance",
    "condition": {
      "field": "balance",
      "operator": "gt",
      "value": 1000000,
      "precision": 100
    }
  }'

Balance monitors are useful for compliance, risk management, and customer notifications. You can set up monitors for low balance alerts, high balance warnings, or any custom threshold.

Balance snapshots

Blnk can create point-in-time snapshots of balances for reporting and auditing:

curl -X POST "http://localhost:5001/balances/snapshots?batch_size=1000"

This creates snapshots of all balances in batches. You can use snapshots to:

Generate daily balance reports
Track balance trends over time
Perform historical balance lookups

Retrieving historical balance

Get a balance’s state at a specific time:

curl "http://localhost:5001/balances/bal_abc123def456/at-time?timestamp=2024-03-01T00:00:00Z"

Response

{
  "balance": {
    "balance": "45000",
    "debit_balance": "55000",
    "credit_balance": "100000",
    "currency": "USD",
    "balance_id": "bal_abc123def456"
  },
  "timestamp": "2024-03-01T00:00:00Z",
  "from_source": false
}

Managing balances

Retrieve a balance

curl "http://localhost:5001/balances/bal_abc123def456"

Include related records:

curl "http://localhost:5001/balances/bal_abc123def456?include=ledger&include=identity"

List balances

# Get balances with pagination
curl "http://localhost:5001/balances?limit=20&offset=0"

# Filter by ledger
curl "http://localhost:5001/balances?ledger_id_eq=ldg_customer123"

# Filter by currency
curl "http://localhost:5001/balances?currency_eq=USD"

Update balance identity

Link a balance to an identity:

curl -X PUT http://localhost:5001/balances/bal_abc123def456/identity \
  -H "Content-Type: application/json" \
  -d '{"identity_id": "id_user789"}'

Best practices

Use metadata for searchability

Store relevant information in the meta_data field to make balances easy to find and filter:

{
  "meta_data": {
    "user_id": "user_789",
    "account_type": "savings",
    "region": "us-east",
    "tier": "premium"
  }
}

Set up monitoring for critical balances

Create balance monitors for:

User wallets that shouldn’t drop below zero
Operational accounts that need minimum reserves
Settlement accounts that need maximum limits

Track fund lineage when needed

Enable track_fund_lineage for balances where you need to track the source and flow of funds. This is useful for:

Compliance and auditing
Chargeback handling
Dispute resolution

Note: This adds processing overhead, so only enable when necessary.

Use indicators for external ID mapping

If you have existing user or account IDs in your system, use the indicator field to map them:

{
  "indicator": "external_user_123_usd"
}

This makes it easy to look up balances using your existing identifiers.

Never manipulate balances directly

Always update balances through transactions. Direct balance manipulation breaks double-entry accounting principles and audit trails.

Next steps

Transactions

Learn how to record financial movements between balances

Identities

Link balances to customer identities

Balance Monitoring

Set up alerts and notifications for balance thresholds

Ledgers

Understand how ledgers organize balances

Getting Started

Core Concepts

Guides

Advanced

Deployment

What are balances?

Balance structure

Example balance object

Understanding balance types

Credit balance

Debit balance

Current balance

Inflight balances

Precision and currency handling

Working with precision

Currency multiplier

Creating a balance

Creating a balance with an identity

Using custom indicators

Balance monitoring

Creating a balance monitor

Monitor conditions

Example: High balance warning

Balance snapshots

Retrieving historical balance

Managing balances

Retrieve a balance

List balances

Update balance identity

Best practices

Next steps

Transactions

Identities

Balance Monitoring

Ledgers

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Guides

Advanced

Deployment

​What are balances?

​Balance structure

​Example balance object

​Understanding balance types

​Credit balance

​Debit balance

​Current balance

​Inflight balances

​Precision and currency handling

​Working with precision

​Currency multiplier

​Creating a balance

​Creating a balance with an identity

​Using custom indicators

​Balance monitoring

​Creating a balance monitor

​Monitor conditions

​Example: High balance warning

​Balance snapshots

​Retrieving historical balance

​Managing balances

​Retrieve a balance

​List balances

​Update balance identity

​Best practices

​Next steps

Transactions

Identities

Balance Monitoring

Ledgers

Build docs developers (and LLMs) love

What are balances?

Balance structure

Example balance object

Understanding balance types

Credit balance

Debit balance

Current balance

Inflight balances

Precision and currency handling

Working with precision

Currency multiplier

Creating a balance

Creating a balance with an identity

Using custom indicators

Balance monitoring

Creating a balance monitor

Monitor conditions

Example: High balance warning

Balance snapshots

Retrieving historical balance

Managing balances

Retrieve a balance

List balances

Update balance identity

Best practices

Next steps