Retrieves the complete fund lineage for a balance that has lineage tracking enabled. Fund lineage provides a detailed breakdown of where funds came from (by provider) and how much has been spent from each source.
Path Parameters The unique identifier of the balance to retrieve lineage for. The balance must have track_fund_lineage enabled.
Response The ID of the balance being queried.
The total available funds across all providers (as big integer string).
The ID of the aggregate shadow balance that holds all provider funds.
Array of provider breakdowns showing fund sources. Show Provider Breakdown Object
The name/identifier of the fund provider.
Total amount received from this provider (as big integer string).
Amount still available from this provider (not yet spent).
Amount that has been debited from this provider’s funds.
The ID of the shadow balance tracking this provider’s funds.
Examples Get Lineage
Response Example
curl https://api.blnk.io/balances/bal_123abc/lineage \ -H "Authorization: Bearer YOUR_API_KEY"
Understanding Fund Lineage What is Fund Lineage? Fund lineage tracks the complete journey of money through your system:
Source Tracking : Know exactly where each dollar came fromProvider Breakdown : See how much came from each payment providerSpend Attribution : Track which provider’s funds were spent firstCompliance : Meet regulatory requirements for fund source tracking
How It Works ┌─────────────────────────────────────────────────────┐ │ Main Balance │ │ bal_123abc │ │ Total: $2,300.00 │ └─────────────────────────────────────────────────────┘ │ ┌───────────────┼───────────────┐ │ │ │ ┌────▼────┐ ┌────▼────┐ ┌────▼────┐ │ Stripe │ │ PayPal │ │ Bank │ │ Shadow │ │ Shadow │ │ Shadow │ │ │ │ │ │ │ │ $1,000 │ │ $800 │ │ $500 │ │ Avail: │ │ Avail: │ │ Avail: │ │ $750 │ │ $500 │ │ $500 │ │ Spent: │ │ Spent: │ │ Spent: │ │ $250 │ │ $300 │ │ $0 │ └─────────┘ └─────────┘ └─────────┘
Enabling Fund Lineage To use this endpoint, create balances with lineage tracking:
{ "ledger_id" : "ldg_123" , "currency" : "USD" , "identity_id" : "usr_456" , "precision" : 100 , "track_fund_lineage" : true , "allocation_strategy" : "FIFO" }
Use Cases Payment Provider Reconciliation Track exactly how much was received from each payment provider:
curl https://api.blnk.io/balances/bal_merchant_123/lineage
Use the response to:
Reconcile with provider settlement reports
Calculate provider-specific fees
Identify discrepancies by provider
Compliance and Auditing Demonstrate source of funds for regulatory compliance:
# Get lineage breakdown curl https://api.blnk.io/balances/bal_customer_456/lineage # Show auditors: # - Where funds originated # - How much came from each source # - Which funds were spent first
Multi-Source Merchant Accounts Merchants receiving payments from multiple channels:
{ "providers" : [ { "provider" : "online_store" , "available" : "50000" }, { "provider" : "marketplace" , "available" : "30000" }, { "provider" : "mobile_app" , "available" : "20000" } ] }
Escrow and Trust Accounts Track client funds in escrow:
{ "providers" : [ { "provider" : "client_a" , "available" : "100000" }, { "provider" : "client_b" , "available" : "150000" }, { "provider" : "client_c" , "available" : "75000" } ] }
Allocation Strategy Verification Verify that funds are being allocated according to strategy:
# Balance with FIFO strategy curl https://api.blnk.io/balances/bal_fifo/lineage # Verify oldest provider funds are spent first # by comparing 'spent' amounts across providers
Allocation Strategies The allocation_strategy determines which provider’s funds are spent first:
FIFO (First In, First Out) Spend oldest funds first:
{ "providers" : [ { "provider" : "jan_deposits" , "spent" : "50000" }, // Oldest, spent first { "provider" : "feb_deposits" , "spent" : "30000" }, // Next oldest { "provider" : "mar_deposits" , "spent" : "0" } // Newest, not spent yet ] }
LIFO (Last In, First Out) Spend newest funds first:
{ "providers" : [ { "provider" : "jan_deposits" , "spent" : "0" }, // Oldest, not spent yet { "provider" : "feb_deposits" , "spent" : "25000" }, // Middle { "provider" : "mar_deposits" , "spent" : "40000" } // Newest, spent first ] }
Proportional Spend proportionally across all sources:
{ "providers" : [ { "provider" : "source_a" , "amount" : "100000" , "spent" : "30000" }, // 30% { "provider" : "source_b" , "amount" : "200000" , "spent" : "60000" }, // 30% { "provider" : "source_c" , "amount" : "150000" , "spent" : "45000" } // 30% ] }
Providers are specified in transaction metadata:
{ "source" : "@world" , "destination" : "bal_customer_123" , "amount" : 100.00 , "currency" : "USD" , "description" : "Payment received" , "meta_data" : { "BLNK_LINEAGE_PROVIDER" : "stripe" } }
The provider name can be anything meaningful:
Payment gateway: stripe, paypal, square
Channel: web, mobile, api
Client: client_a, customer_123
Source: bank_transfer, card_payment
Shadow Balances Blnk creates shadow balances automatically:
Shadow Balance : One per provider (e.g., @stripe_john_doe_12345678_lineage)Aggregate Balance : One for all providers (e.g., @john_doe_12345678_lineage)Automatic Creation : Created on first transaction with providerInternal Use : Shadow balances are for internal tracking, not direct access
Interpreting Results Available vs. Spent available = amount - spent
amount : Total ever received from providerspent : Amount debited from this provider’s fundsavailable : Remaining balance from this provider
Total with Lineage total_with_lineage = sum of all provider 'available' amounts
This should match the main balance’s available funds (excluding inflight).
Error Responses Common Errors: Lineage Not Enabled (400)
{ "error" : "balance bal_123 does not have fund lineage tracking enabled" }
{ "error" : "failed to get balance: balance not found" }
{ "balance_id" : "bal_123" , "total_with_lineage" : "0" , "aggregate_balance_id" : "" , "providers" : [] }
