Charts

Supply Age Distribution

Transparent UTXO set distributed across 11 coin-age bands (HODL waves), as period-end snapshots.

Page Sections

GET

`/charts/supply-age-distribution`

Full URL: https://forcex.com/xtract/v1/litecoin/charts/supply-age-distribution

Credit cost: 6 credits.

curl -H "Authorization: Bearer fx_live_************" \
  "https://forcex.com/xtract/v1/litecoin/charts/supply-age-distribution?start=2026-06-01&end=2026-06-08&grain=day"

Parameters

Name	Location	Required	Type	Description
`start`	query	no	string \| null	ISO date (YYYY-MM-DD) or ISO-Z timestamp. Range is half-open `[start, end)` — `start` is inclusive.
`end`	query	no	string \| null	ISO date (YYYY-MM-DD) or ISO-Z timestamp. Range is half-open `[start, end)` — `end` is exclusive. Example: `start=2026-05-12&end=2026-05-15` covers May 12, 13, 14 (NOT 15).
`grain`	query	no	string matching `^(day\|week\|month)$`, default `day`	—
`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": {
    "grain": "day",
    "latest_available_date": "2026-06-23",
    "disclosure": "Transparent spendable UTXOs only — MWEB peg carriers, OP_RETURN outputs, and the genesis coinbase are excluded. This is a distribution of the transparent UTXO set by coin age, not total supply.",
    "snapshots": [
      {
        "bucket_start": "2026-06-23",
        "bucket_end": "2026-06-23",
        "total_output_count": 78214553,
        "total_value_atomic_units": 6543210000000000,
        "bands": [
          {
            "age_bucket": "<1d",
            "band_order": 0,
            "display_label": "less than 1 day",
            "output_count": 412233,
            "value_atomic_units": 91230000000000,
            "cumulative_output_count": 412233,
            "cumulative_value_atomic_units": 91230000000000,
            "share": 0.0139
          },
          {
            "age_bucket": "1y-2y",
            "band_order": 6,
            "display_label": "1 year to 2 years",
            "output_count": 8123445,
            "value_atomic_units": 1203400000000000,
            "cumulative_output_count": 51233440,
            "cumulative_value_atomic_units": 4321000000000000,
            "share": 0.1839
          },
          {
            "age_bucket": "7y+",
            "band_order": 10,
            "display_label": "more than 7 years",
            "output_count": 2233445,
            "value_atomic_units": 765400000000000,
            "cumulative_output_count": 78214553,
            "cumulative_value_atomic_units": 6543210000000000,
            "share": 0.117
          }
        ]
      }
    ]
  },
  "meta": {
    "served_from": "indexed_store",
    "credit_cost": 2,
    "methodology_version": "v1"
  }
}

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

Period-end snapshot semantics: week and month grains return the closing snapshot within the period, never a sum across days.
Every snapshot returns all 11 canonical age bands in young-to-old order: <1d, 1d-1w, 1w-1m, 1m-3m, 3m-6m, 6m-1y, 1y-2y, 2y-3y, 3y-5y, 5y-7y, 7y+.
Transparent spendable UTXOs only — MWEB peg carriers, OP_RETURN outputs, and the genesis coinbase are excluded. This is a distribution of the transparent UTXO set by coin age, not total supply.
Distinct from /charts/supply, which is a point-in-time supply scalar.
`include_current=true` returns an explicit `status=unavailable` current window with `last_complete_at` — snapshots are daily-complete; no intraday snapshot source exists.
`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).