Skip to main content
Retrieves the historical state of a balance at a specific point in time. This endpoint enables time-travel queries to see what a balance looked like in the past, useful for auditing, reconciliation, and historical reporting.

​
Path Parameters

​
id
string
required
The unique identifier of the balance to query.

​
Query Parameters

​
timestamp
string
The point in time to retrieve the balance state, in ISO 8601 format.If not provided, returns the current balance state.Format: YYYY-MM-DDTHH:MM:SSZ (e.g., 2024-01-15T15:04:05Z)Example: ?timestamp=2024-01-01T00:00:00Z
​
from_source
boolean
default:"false"
Calculate balance from all source transactions instead of using snapshots.Options:
  • false (default): Use balance snapshots for efficient retrieval
  • true: Calculate from all transactions since inception (slower but always accurate)
Example: ?from_source=true

​
Response

​
balance
object
The balance state at the specified time.
​
timestamp
string
The ISO 8601 timestamp for which the balance was retrieved.
​
from_source
boolean
Indicates whether the balance was calculated from source transactions or snapshots.

​
Examples

curl https://api.blnk.io/balances/bal_123abc/at \
  -H "Authorization: Bearer YOUR_API_KEY"
Response Example
{
  "balance": {
    "balance_id": "bal_123abc",
    "balance": "75000",
    "debit_balance": "25000",
    "credit_balance": "100000",
    "currency": "USD"
  },
  "timestamp": "2024-01-15T15:04:05Z",
  "from_source": false
}

​
How It Works

​
Snapshot-Based Retrieval (Default)

By default, Blnk uses balance snapshots for efficient historical queries:
  1. Daily Snapshots: Blnk creates periodic snapshots of balance states
  2. Nearest Snapshot: Finds the closest snapshot before the requested time
  3. Transaction Delta: Applies transactions between snapshot and target time
  4. Fast Results: Optimized for quick retrieval without processing all historical transactions

​
Source-Based Calculation

When from_source=true, Blnk calculates the balance from scratch:
  1. All Transactions: Retrieves all transactions affecting the balance
  2. Time Filter: Only includes transactions before the target timestamp
  3. Full Calculation: Sums all debits and credits from the beginning
  4. Guaranteed Accuracy: Always reflects the true state, useful for verification

​
Use Cases

​
Daily Reconciliation

Check end-of-day balances for reconciliation: 
curl "https://api.blnk.io/balances/bal_123/at?timestamp=2024-01-31T23:59:59Z"

​
Month-End Reporting

Generate month-end balance reports: 
curl "https://api.blnk.io/balances/bal_123/at?timestamp=2024-01-31T23:59:59Z"
curl "https://api.blnk.io/balances/bal_123/at?timestamp=2024-02-29T23:59:59Z"
curl "https://api.blnk.io/balances/bal_123/at?timestamp=2024-03-31T23:59:59Z"

​
Audit Trail

Verify historical balance states for compliance: 
curl "https://api.blnk.io/balances/bal_123/at?timestamp=2024-01-15T14:30:00Z&from_source=true"

​
Dispute Resolution

Retrieve balance state at the time of a disputed transaction: 
curl "https://api.blnk.io/balances/bal_123/at?timestamp=2024-02-10T09:15:30Z"

​
Time-Series Analysis

Generate balance trends over time: 
# Get balance at multiple points in time
for day in {01..31}; do
  curl "https://api.blnk.io/balances/bal_123/at?timestamp=2024-01-${day}T23:59:59Z"
done

​
Balance Snapshots

To optimize historical queries, Blnk provides a snapshot mechanism:

​
Creating Snapshots

Use the Create Balance Snapshots endpoint to generate snapshots in batches: 
POST /balances-snapshots?batch_size=1000

​
When to Create Snapshots

  • Daily: Run at end of day for all balances
  • On-Demand: Before critical reporting periods
  • Scheduled: Via cron jobs or scheduled tasks

​
Snapshot Benefits

  • Faster historical queries
  • Reduced database load
  • Efficient time-travel queries
  • Point-in-time recovery

​
Performance Considerations

Snapshot Method (Recommended):
  • Fast response times (milliseconds)
  • Efficient for frequent queries
  • Requires periodic snapshot creation
Source Method:
  • Slower for long balance histories
  • Guaranteed accuracy
  • Use for verification or when snapshots aren’t available
  • Good for recent timestamps or new balances

​
Error Responses

Common Errors:
  • 400 Bad Request: Invalid timestamp format or missing balance ID
  • 404 Not Found: Balance does not exist
  • 400 Bad Request: No balance data found for the specified time (balance didn’t exist yet)

Build docs developers (and LLMs) love

Get started for freeTalk to us