ledger.read.v1.LedgerReadService
GetBalanceHistory
Retrieve balance history buckets for an account. Supports optional subaccount, range, asset, and account-code filters.
Request
curl --request POST \ \
--url 'https://api.testnet.polyester.com/ledger.read.v1.LedgerReadService/GetBalanceHistory' \
--header 'Content-Type: application/json' \
--header 'Connect-Protocol-Version: 1' \
--data '{
"accountCodes": [
"FUNDING"
],
"ledger": 1,
"range": "DAY_1",
"subaccountId": "6789012345678"
}'Responses
{
"bucket": "1m",
"endTsSec": 1735689600,
"points": 1,
"range": "DAY_1",
"series": [
{
"accountCode": "FUNDING",
"assetId": 100,
"balanceQ": [
"1"
]
}
],
"startTsSec": 1735689600
}ledger.read.v1.GetBalanceHistoryRequestledger.read.v1.GetBalanceHistoryResponseOptional public subaccount ID. When omitted, subaccount-scoped API keys use their bound subaccount; other callers use their authenticated root account.
History window to return. When unset/UNSPECIFIED, defaults to 1D.
Optional public asset filter. When unset/0, returns all assets.
Optional subset of account buckets to return. When empty, returns all account buckets.
Resolved history window.
Sampling interval between points, such as "5m" or "1h".
First point timestamp in seconds since epoch (UTC).
Last point timestamp in seconds since epoch (UTC).
Number of aligned points in each returned series.
public unified asset id
account bucket
Chart balance in asset units scaled by 1e7 (7 decimals). Values are downscaled from 18-decimal ledger balances for compact charting and align 1:1 with implicit timestamps.
| Key | HTTP status | Connect code | Error | When |
|---|---|---|---|---|
| api-key-action-deny | 403 | permission_denied | API Key Policy Denied | API key policy does not allow this read action. |
| api-key-policy-not-found | 403 | permission_denied | API Key Policy Not Found | API key policy was not found. |
| api-key-policy-required | 403 | permission_denied | API Key Policy Required | API key policy is required for ledger reads. |
| api-key-root-scope-only | 403 | permission_denied | API Key Root Scope Only | This API key is scoped to the root account and cannot read sub-accounts. |
| api-key-subaccount-mismatch | 403 | permission_denied | API Key Sub-account Mismatch | This API key is bound to a different sub-account. |
| api-key-unknown | 403 | permission_denied | API Key Unknown | The authenticated API key has no metadata entry in the API key store. |
| auth-authentication-required | 401 | unauthenticated | Authentication Required | Authentication is required. |
| auth-session-kind-not-allowed | 403 | permission_denied | Interactive Session Required | This read accepts only an interactive session; API keys are refused. |
| bad-request | 400 | invalid_argument | Bad Request | — |
| invalid-account-id | 400 | invalid_argument | Invalid Account ID | — |
| invalid-argument | 400 | invalid_argument | Bad Request | — |
| invalid-subaccount-id | 400 | invalid_argument | Invalid Sub-account ID | — |
| ip-not-allowed | 401 | unauthenticated | API Key IP Not Allowed | API key is not authorized from this IP address. |
| key-disabled | 401 | unauthenticated | API Key Disabled | API key is disabled. |
| key-expired | 401 | unauthenticated | API Key Expired | API key has expired. |
| missing-account-id | 400 | invalid_argument | Missing Account ID | — |
| missing-headers | 400 | invalid_argument | Missing API Key Headers | Missing required API key authentication headers. |
| missing-wallet | 400 | invalid_argument | Missing Wallet | — |
| not-found | 404 | not_found | Not Found | — |
| permission-denied | 403 | permission_denied | Permission Denied | — |
| role-action-deny | 403 | permission_denied | Role Denied | Your role does not allow this read action. |
| server-error | 500 | internal | Server Error | — |
| signature-invalid | 401 | unauthenticated | Invalid API Key Signature | API key signature is invalid. |
| subaccount-policy-deny | 403 | permission_denied | Sub-account Policy Denied | Sub-account policy does not allow this read action. |
| subaccount-read-forbidden | 403 | permission_denied | Sub-account Read Forbidden | You do not have permission to read this sub-account. |
| timestamp-skew | 400 | invalid_argument | API Key Timestamp Skew | API key timestamp is outside the allowed skew window. |
| unauthenticated | 401 | unauthenticated | Unauthenticated | Ledger reads require a valid bearer JWT or signed API-key request. |
| upstream-error | 502 | unavailable | Upstream Error | — |
| wallet-not-found | 404 | not_found | Wallet Not Found | — |
| wallet-resolution-unavailable | 502 | unavailable | Wallet Resolution Unavailable | — |