LedgerReadService

Get Balance History

Retrieve balance history buckets for an account. Supports optional subaccount, range, asset, and account-bucket filters.

Method

GET

Path

/v1/balances/history

Visibility

Authentication required

Authentication

Session token or API key

MFA Requirement

Not required

GET

/v1/balances/history

Request

Testnet

curl --request GET \ \
  --url 'https://api.testnet.polyester.com/v1/balances/history?accountCode=FUNDING&ledger=USDT&range=1d&subaccountId=45LUmqjT' \
  --header 'Accept: */*' \
  --header 'X-API-KEY-ID: YOUR_API_KEY_ID' \
  --header 'X-API-TIMESTAMP: YOUR_API_TIMESTAMP' \
  --header 'X-API-SIGNATURE: YOUR_API_SIGNATURE'

Responses

{
  "bucket": "1m",
  "endTsSec": 1735689600,
  "points": 1,
  "range": "1d",
  "series": [
    {
      "account": "FUNDING",
      "asset": "USDT",
      "balance": [
        "0.0000001"
      ]
    }
  ],
  "startTsSec": 1735689600
}

accountCode string

Optional account bucket filter (comma-separated codes or names: funding, trading).

ledger string

Optional public asset filter.

range enum must be defined value

History window (defaults to 1d).

subaccountId string /^[1-9A…m-z]+$/

Optional subaccount public id (base58).

bucket string

Sampling interval between points, such as "5m" or "1h".

Example 1m

endTsSec integer (int32)

Last point timestamp in seconds since epoch (UTC).

Example 1735689600

points integer (int32)

Number of aligned points in each returned series.

Example 1

range enum

Resolved history window.

1d 7d 30d 90d 180d 365d

Example 1d

3 fields

startTsSec integer (int32)

First point timestamp in seconds since epoch (UTC).

Example 1735689600

Possible errors: 5

Key	HTTP status	Connect code	Error	When
unauthenticated	401	unauthenticated	Unauthenticated	Authentication required.
permission-denied	403	permission_denied	Permission Denied	Permission denied.
invalid-argument	400	invalid_argument	Invalid Argument	Invalid argument.
not-found	404	not_found	Not Found	Not found.
unavailable	503	unavailable	Unavailable	Service unavailable.