Charts

MWEB Chart

MWEB time-series metrics.

Page Sections

GET

`/charts/mweb`

Full URL: https://forcex.com/xtract/v1/litecoin/charts/mweb

Credit cost: 1 credit plus 1 credit per metric requested.

curl -H "Authorization: Bearer fx_test_************" \
  "https://forcex.com/xtract/v1/litecoin/charts/mweb?metrics=pegin_atomic_units,pegout_atomic_units,cumulative_balance_atomic_units&start=2026-05-01&end=2026-06-01&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`	—
`metrics`	query	no	string \| null	Comma-separated MWEB metric names. Valid values: `pegin_atomic_units` (total peg-in value — transparent → MWEB), `pegout_atomic_units` (total peg-out value — MWEB → transparent), `cumulative_balance_atomic_units` (running MWEB pool balance at bucket close), `mweb_tx_count` (count of MWEB transactions in the bucket; not a kernel count). When `?metrics=` is omitted all four are returned. Unknown names return 400 `bad_request`. Per-metric definitions are in the data dictionary at /xtract/docs.

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",
      "pegin_atomic_units": 250000000,
      "pegout_atomic_units": 100000000,
      "cumulative_balance_atomic_units": 18000000000
    }
  ],
  "meta": {
    "served_from": "indexed_store",
    "credit_cost": 4
  }
}

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` (sandbox keys cannot request `?include=all`), `include_set_requires_paid_tier` (the requested include set exceeds the per-request cost cap for sandbox keys), `historical_scan_requires_paid_tier` (sandbox keys cannot scan outside the recent window), or `deep_pagination_requires_paid_tier` (sandbox 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` (sandbox 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

When `metrics` is omitted, all MWEB metrics are returned.
Metric values use atomic units where value is represented.