Ledger balances

Historical Balances

How to retrieve accurate historical balance information.

GET/balances/{balance_id}/at

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 being retrieved.

Query

timestampstringrequiredquery

Specifies the exact date and time for which a historical balance is requested

GET http://YOUR_BLNK_INSTANCE_URL/balances/{balance_id}/at?timestamp=2025-02-24T08:55:26Z

Always format the date input as ‘YYYY-MM-DDTHH:MM:SS+00:00’ (e.g., 2024-04-22T15:28:03+00:00), where +00:00 specifies the timezone. It is UTC by default.

from_sourcebooleanquery

When set to true, it indicates that the balance should be reconstructed directly from its transactions, bypassing balance snapshots.

{
  "error": "invalid timestamp format. Please use ISO 8601 format (e.g., 2024-01-01T15:04:05Z)",
  "error_detail": {
    "code": "BAL_INVALID_TIMESTAMP",
    "message": "invalid timestamp format. Please use ISO 8601 format (e.g., 2024-01-01T15:04:05Z)"
  }
}

{
  "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"
  }
}