Skip to main content
Creates a new balance record in the ledger. A balance represents a financial account that tracks funds for a specific identity in a given currency.

​
Balance Types

Balances in Blnk can be configured with different capabilities:
  • Standard Balance: Basic balance tracking with credit/debit operations
  • Tracked Balance: Enables fund lineage tracking to maintain source-of-funds information
  • Allocation-Aware: Supports different allocation strategies (FIFO, LIFO, Proportional) for fund lineage

​
Request Body

​
ledger_id
string
required
The ID of the ledger this balance belongs to. Every balance must be associated with a ledger.
​
currency
string
required
The currency code for this balance (e.g., “USD”, “EUR”, “NGN”). All transactions on this balance must use the same currency.
​
identity_id
string
The ID of the identity (user, customer, merchant) associated with this balance. Required when track_fund_lineage is enabled.
​
precision
float
The precision multiplier for currency handling. Determines how many decimal places the balance supports.Examples:
  • 100 for cents (2 decimal places)
  • 1000 for 3 decimal places
  • 1 for whole units only
Default precision is applied if not specified. Must be an integer value (whole number).
​
track_fund_lineage
boolean
default:"false"
Enable fund lineage tracking for this balance. When enabled, Blnk tracks the source of all funds and maintains a detailed breakdown of how funds flow through the balance.Requires identity_id to be set.
​
allocation_strategy
string
default:"FIFO"
The allocation strategy to use when debiting funds from a balance with lineage tracking. Determines which funds are spent first.Options:
  • FIFO: First In, First Out - spend oldest funds first
  • LIFO: Last In, First Out - spend newest funds first
  • PROPORTIONAL: Allocate proportionally across all fund sources
Only applies when track_fund_lineage is enabled.
​
meta_data
object
Custom metadata to attach to the balance. Can store any additional information as key-value pairs.Example:
{
  "account_type": "savings",
  "customer_tier": "premium",
  "notes": "Primary account"
}

​
Response

​
balance_id
string
Unique identifier for the created balance.
​
ledger_id
string
The ledger ID this balance belongs to.
​
identity_id
string
The identity ID associated with this balance.
​
currency
string
The currency code for this balance.
​
balance
string
The current balance amount (credit_balance - debit_balance). Stored as a big integer string for precision.
​
credit_balance
string
Total credits applied to this balance. Stored as a big integer string.
​
debit_balance
string
Total debits applied to this balance. Stored as a big integer string.
​
inflight_balance
string
Total balance currently in inflight transactions (pending confirmation).
​
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. Incremented with each balance update.
​
track_fund_lineage
boolean
Whether fund lineage tracking is enabled for this balance.
​
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

{
  "ledger_id": "ldg_123abc",
  "currency": "USD",
  "identity_id": "usr_456def",
  "precision": 100,
  "meta_data": {
    "account_type": "checking"
  }
}

​
Currency Precision

Blnk uses arbitrary precision arithmetic to handle currency amounts without rounding errors. The precision field defines the multiplier:
  • Amount 1234 with precision 100 = 12.34 in display currency
  • Amount 5000000 with precision 100 = 50000.00 in display currency
  • Amount 999 with precision 1000 = 0.999 in display currency
All balance amounts in the response are returned as string representations of large integers to preserve precision.

​
Fund Lineage Tracking

When track_fund_lineage is enabled:
  1. Shadow Balances: Blnk creates shadow balances to track funds from each provider
  2. Provider Tracking: Each credit transaction can specify a provider via metadata
  3. Allocation Strategies: Debits are allocated based on the configured strategy
  4. Full Transparency: Query lineage to see exactly which funds came from where
See the Get Balance Lineage endpoint for retrieving lineage information.

Build docs developers (and LLMs) love

Get started for freeTalk to us