Ledger balances

View balance lineage

See a balance’s provider breakdown (received, spent, available) when fund lineage is enabled.

GET/balances/{balance_id}/lineage

Authorization

If set, the API uses an API key for authentication. Include the following header in your requests: X-blnk-key: <api-key>.

Replace <api-key> with your secret API key. Ensure the key is kept secure and not exposed in public repositories or client-side code.

Path

balance_idstringrequiredpath

Specifies the unique ID of the balance whose lineage you want to retrieve.

Response

All amounts are returned as strings in minor units.

balance_idstringrequired

The ID of the balance being queried.

aggregate_balance_idstringrequired

The internal aggregate balance ID used to track combined provider funds.

total_with_lineagestringrequired

Total available funds tracked by lineage (in minor units, like precise_amount).

providersarrayrequired

Provider-by-provider breakdown of received and spent funds.

curl -X GET "http://localhost:5001/balances/{balance_id}/lineage" \
  -H "X-blnk-key: <api-key>"

{
  "balance_id": "bln_5ce86029-3c2e-4e2a-aae2-7fb931ca4c4f",
  "aggregate_balance_id": "bln_aggregate_shadow_balance_id",
  "total_with_lineage": "7500",
  "providers": [
    {
      "provider": "stripe",
      "amount": "10000",
      "available": "7500",
      "spent": "2500",
      "shadow_balance_id": "bln_shadow_balance_id"
    }
  ]
}

{
  "error": "Balance with ID 'bln_a3f8c2e1-9d4b-4f7a-b6e2-1c8d5f0a7b3e' not found",
  "error_detail": {
    "code": "BAL_NOT_FOUND",
    "message": "Balance with ID 'bln_a3f8c2e1-9d4b-4f7a-b6e2-1c8d5f0a7b3e' not found"
  }
}