Get address balance history

GET/v1/addresses/{address}/balance-history

TSCScan API v1.0.0 · Addresses · also at /api/v1/mainnet/addresses/{address}/balance-history

Chain-dependent response; compact chain headers identify the serving snapshot.

Example

curl 'https://api.tensorcash.org/v1/addresses/tc1qmvalge7mnhct9qj5uua8rn0dmjcyh6fmvrr46j/balance-history'

Name	In	Type	Required	Description
`address`	path	`string`	Yes	Exact TensorCash address on the selected network; aliases are not accepted here.
`min_height`	query	`integer`	—	Optional minimum serving indexed height. Returns DATA_NOT_READY if no eligible source has reached it.

Status	Description	Body
`200`	Successful read from one Indexer snapshot	application/json `BalanceHistoryResponse`
`400`	Invalid argument or page conditions	application/problem+json `Problem`
`401`	Authentication required	application/problem+json `Problem`
`403`	Permission denied	application/problem+json `Problem`
`404`	Absent in a ready indexed range	application/problem+json `Problem`
`409`	Verified chain continuity invalidation	application/problem+json `Problem`
`422`	Bounded response would exceed byte budget	application/problem+json `Problem`
`429`	Quota exceeded; Retry-After supplied	application/problem+json `Problem`
`503`	Data or eligible source not ready	application/problem+json `Problem`
`504`	Bounded upstream query timed out	application/problem+json `Problem`

Field	Type	Required	Description
`data`	`BalanceHistory`	Yes	The requested resource or collection; its schema is specific to this endpoint.

Field	Type	Required	Description
`first_height`	`integer \| null`	Yes	First indexed or selected height represented by this resource.
`first_time`	`integer \| null`	—	Unix timestamp of the first confirmed address activity; null when none exists.
`last_activity_height`	`integer \| null`	Yes	Latest confirmed address activity height; null when none exists.
`last_activity_time`	`integer \| null`	—	Latest confirmed address activity timestamp in Unix seconds; null when none exists.
`tip_height`	`integer`	Yes	Canonical height at the serving snapshot's watermark.
`tip_time`	`integer`	Yes	Unix timestamp of the watermark block.
`bucket_size`	`integer`	Yes	Number of block heights in each balance-history candle interval.
`current_balance`	`Amount`	Yes	Current confirmed address balance in smallest units.
`ledger_balance`	`Amount`	Yes	Confirmed balance reconstructed from indexed address activity, in smallest units.
`candles`	`BalanceCandle[]`	Yes	Chronological exact balance candles; at most 160 nonempty intervals.

Exact smallest-unit decimal. Known zero is units '0'.

Field	Type	Required	Description
`units`	`string`	Yes	Exact decimal string in smallest units; signed where the schema permits. Divide by 10^precision only for display.
`precision`	`integer`	Yes	Decimal places for the smallest-unit amount. TSC uses 8; assets use their indexed precision.

Field	Type	Required	Description
`state`	`"unknown"`	Yes	Availability or confirmation state. Use the declared enum/constant; unknown or unavailable never means numeric zero.
`units`	`null`	Yes	Exact decimal string in smallest units; signed where the schema permits. Divide by 10^precision only for display.
`precision`	`integer \| null`	Yes	Decimal places for the smallest-unit amount. TSC uses 8; assets use their indexed precision.

Field	Type	Required	Description
`state`	`"unavailable"`	Yes	Availability or confirmation state. Use the declared enum/constant; unknown or unavailable never means numeric zero.
`units`	`null`	Yes	Exact decimal string in smallest units; signed where the schema permits. Divide by 10^precision only for display.
`precision`	`integer \| null`	Yes	Decimal places for the smallest-unit amount. TSC uses 8; assets use their indexed precision.

Field	Type	Required	Description
`start_height`	`integer`	Yes	First inclusive canonical height represented by the window or candle.
`end_height`	`integer`	Yes	Final inclusive canonical height represented by the window or candle.
`activity_height`	`integer`	Yes	Height of the last balance-changing activity within this candle.
`time`	`integer`	Yes	Unix timestamp in seconds; mempool items use Core arrival time and confirmed items use block time.
`transaction_count`	`integer`	Yes	Exact number of confirmed transactions/activities represented by this resource; pending activity is excluded unless explicitly stated.
`open`	`string`	Yes	Confirmed balance immediately before the interval's first activity, in smallest units.
`close`	`string`	Yes	Confirmed balance after the final activity in the interval, in smallest units.
`high`	`string`	Yes	Highest confirmed balance in the interval, including its opening balance.
`low`	`string`	Yes	Lowest confirmed balance in the interval, including its opening balance.

Field	Type	Required	Description
`type`	`string`	Yes	Problem type URI; about:blank is used for the current error family.
`title`	`string`	Yes	Short human-readable problem title, normally the stable error code.
`status`	`integer`	Yes	HTTP status code for this problem response.
`code`	`"INVALID_ARGUMENT" \| "UNAUTHORIZED" \| "FORBIDDEN" \| "RESOURCE_NOT_FOUND" \| "CHAIN_ANCHOR_INVALIDATED" \| "RATE_LIMITED" \| "DATA_NOT_READY" \| "SERVICE_UNAVAILABLE" \| "UPSTREAM_TIMEOUT" \| "RESPONSE_TOO_LARGE" \| "CORE_UNAVAILABLE" \| "CORE_METHOD_UNAVAILABLE" \| "CORE_DATA_NOT_READY" \| "CORE_CAPACITY" \| "TRANSACTION_CAPACITY" \| "TRANSACTION_STATE_CHANGED" \| "TRANSACTION_REJECTED" \| "BROADCAST_OUTCOME_UNKNOWN" \| "UNSUPPORTED_ASSET_POLICY"`	Yes	Stable machine-readable error code; use this instead of matching message text.
`request_id`	`string`	Yes	Identifier also supplied in X-Request-ID; include it when reporting an error.
`detail`	`string`	—	Human-readable explanation of the error.
`retry_after_seconds`	`integer`	—	Suggested wait in seconds before retrying; where present, agrees with Retry-After.