Charts
Supply Snapshot
Scheduled issued supply, node-equivalent circulating supply, current block subsidy, and next halving.
Page Sections
GET
/charts/supply
Full URL: https://forcex.com/xtract/v1/litecoin/charts/supply
Credit cost: 2 credits.
curl -H "Authorization: Bearer fx_live_************" \
"https://forcex.com/xtract/v1/litecoin/charts/supply"Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
at | query | no | string | null | Optional historical reference: a bare block height (exact, e.g. `3134692`) or an ISO-8601 date/timestamp (resolves to the last block at or before that time). Omit for the latest snapshot. |
include_current | query | no | boolean, default `False` | Attach the additive `current` member: the in-progress current window and/or state snapshots with explicit as-of provenance (height, hash, time, stability). Defaults to false — the pre-existing response is byte-identical when omitted. Unsupported current calculations return an explicit `status=unavailable` object with a governed `reason_code`; nothing is fabricated. |
Request Body
No request body.
Example Response
Representative trimmed response. Use the OpenAPI schema for the exhaustive field contract.
{
"data": {
"issued_supply_atomic_units": 7734511250000000,
"circulating_supply_atomic_units": 7734304641450101,
"current_subsidy_atomic_units": 625000000,
"next_halving_height": 3360000,
"at_height": 3135217
},
"meta": {
"served_from": "indexed_store",
"methodology_version": "litecoin-supply-schedule.v2",
"credit_cost": 1
}
}Documented Responses
| Status | Description |
|---|---|
200 | Successful Response |
400 | Bad request. The `error.code` field identifies the specific cause: `bad_request` (general validation failure, including malformed dates, out-of-order ranges, and request-body validation), `range_too_large` (date range exceeds the per-grain cap), `ambiguous_time_range` (legacy `from`/`to` and new `start`/`end` supplied with differing values), or `invalid_include` (unsupported expansion in `?include=`). |
401 | Authentication required, or the supplied Bearer token is invalid or revoked. `error.code` = `auth_required`. |
402 | Payment-tier gate. `error.code` identifies which gate fired: `subscription_required` (no active subscription on the account), `subscription_inactive` (subscription exists but is not active), `include_all_requires_paid_tier` (Free-tier keys cannot request `?include=all`), `include_set_requires_paid_tier` (the requested include set exceeds the per-request cost cap for Free-tier keys), `historical_scan_requires_paid_tier` (legacy test keys cannot scan outside the recent window), or `deep_pagination_requires_paid_tier` (Free-tier keys cannot page beyond the depth cap). |
403 | Authenticated but the key lacks the required scope. `error.code` = `scope_insufficient`. |
422 | Defense-in-depth: the runtime maps standard request-shape validation errors to 400, so partners normally see 400 instead of 422. This status is declared so any edge-case validation path that bypasses the override is still typed. |
429 | Rate limit or credit budget exceeded. `error.code` identifies the window: `rate_limit_exceeded` (per-second or per-minute), `quota_exceeded_daily` (Free-tier per-day budget), or `quota_exceeded` (per-subscription-period). The body carries a `window` field (`second`, `minute`, `day`, or `month`) naming the failing limit. Responses include the standard `Retry-After` header. |
500 | Internal server error. `error.code` = `internal_error`. Reference `meta.request_id` when contacting support. |
503 | Service or downstream data store is temporarily unavailable, or the endpoint is not implemented in this API version. `error.code` identifies the cause: `data_unavailable` (chain tip not yet populated), `audit_unavailable` (request completed but audit could not be acknowledged — safe to retry), `plan_misconfigured` (operational issue on the API side; not a tier problem), or `endpoint_not_available` (the route is reserved and not yet served in this version). |
Integration Notes
- `issued_supply_atomic_units` is deterministic scheduled issuance from the Litecoin block-subsidy halving schedule (excludes fees) — the same "Scheduled" figure shown on the Xplorer supply panel.
- `circulating_supply_atomic_units` is the node-equivalent UTXO-set total from the active validation checkpoint — it matches the Litecoin node's own supply accounting and excludes the genesis coinbase and cumulative nulldata burns, so it is slightly below issued supply.
- Circulating supply is a latest-only figure: responses for a historical `at` omit `circulating_supply_atomic_units` rather than pairing a historical issued value with the current checkpoint.
- Supply-age and MWEB charts are validation cross-checks, not the source of these figures.
- `at` is optional: a bare block height (exact, e.g. `at=3134692`) or an ISO-8601 date/timestamp (resolves to the last block at or before that time). Invalid values return 400; a height beyond the tip or a time before genesis returns 404. Omit for the latest snapshot.
- All values are exact atomic-unit integers (litoshi). Use this for chart labels and supply panels.
- `include_current=true` re-expresses the governed supply values as a canonical `state_snapshot` pinned to the exact `at_height` block identity — never extrapolated.
- `next_halving_at_estimate` is a SCHEDULE estimate: `block_time(at_height) + (next_halving_height − at_height) × 150 s` — anchored at the represented block (historical `at` reports the estimate as known from that point), not a prediction from observed block times.
- `include_current` and `current_metrics` add no charge in this schedule — live current objects are included in the route price (a governed product decision; any later surcharge would be a separately versioned contract change).