Charts
Network Chart
Network time-series metrics.
Page Sections
GET
/charts/network
Full URL: https://forcex.com/xtract/v1/litecoin/charts/network
Credit cost: 2 credits plus 2 credits per metric requested — the omitted-metrics default (`tx_count`) costs 4; two selected metrics cost 6 (the free-key cap); `metrics=all` is not a token and is rejected before any charge.
curl -H "Authorization: Bearer fx_live_************" \
"https://forcex.com/xtract/v1/litecoin/charts/network?metrics=tx_count,avg_fee_atomic_units&start=2026-05-01&end=2026-06-01&grain=day"Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
metrics | query | no | string | null | Comma-separated metric names to include in the response. **Valid values:** `tx_count` (count of confirmed transactions; default when `?metrics=` is omitted), `active_addresses` (distinct addresses with activity — **`grain=day` only** in v1; see note below), `new_addresses` (addresses first seen), `total_output_value_atomic_units`, `avg_hashrate_hashes_per_second` (H/s), `avg_fee_atomic_units`, `avg_block_size_bytes`. Unknown names return 400 `bad_request`. Per-metric units and definitions are in the data dictionary at /xtract/docs. **`active_addresses` × non-day grain returns 400 `bad_request`** because daily distinct counts cannot be honestly summed into weekly/monthly distincts; the rollup source is a planned follow-on. All other metrics aggregate correctly across `day`/`week`/`month` (sums for totals; daily-mean averages for rate/fee/size; appropriate snapshot semantics where applicable). |
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. |
current_metrics | query | no | string | null | Comma-separated CURRENT-window metric selection from the governed current registry (superset of ?metrics=). Only meaningful with include_current=true; omitted = the full registry. Unknown names return 400 with the valid list. No per-metric charge. |
Request Body
No request body.
Example Response
Representative trimmed response. Use the OpenAPI schema for the exhaustive field contract.
{
"data": [
{
"bucket_start": "2026-05-01T00:00:00Z",
"tx_count": 154321,
"avg_fee_atomic_units": 1280
}
],
"meta": {
"served_from": "indexed_store",
"methodology_version": "v1",
"credit_cost": 3
}
}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
- `start` and `end` use half-open range semantics: `[start, end)`.
- `active_addresses` is day-grain only in v1.
- `include_current=true` adds the additive `current` member — an in-progress `time_window` and/or `state_snapshot` objects with explicit provenance (`as_of_height`, `as_of_hash`, `as_of_time`, `stability`). `is_complete` follows the median-time-past predicate; a current partial is never a completed close. See the Live current data guide at /xtract/docs/#current-data.
- `current_metrics` selects from the governed current registry (a superset of `metrics`; no per-metric charge). The lifetime snapshot carries `cumulative_tx_count`, `cumulative_output_value_atomic_units`, and `total_unique_addresses_seen` — lifetime unique addresses are a state, distinct from window-scoped `active_addresses`.
- Launch granularity: `day` serves every governed metric; `week`/`month` current windows serve additive totals only (non-additive and distinct requests are explicitly `exact_aggregation_unavailable`); current `year` windows return `unsupported_granularity`.
- `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).