Build against validated Litecoin data.

Getting Started

Quickstart

Create an API key in your account, then pass it as a bearer token. New keys are `fx_live_` keys; existing `fx_test_` keys still work but can no longer be created.

curl -H "Authorization: Bearer fx_live_************" \
  https://forcex.com/xtract/v1/litecoin/chain/home

Base URL

The current production API is path-based on `forcex.com`.

https://forcex.com/xtract/v1/litecoin

Endpoint tables below use short paths such as `/chain/home`. Prepend the base URL when making requests.

Authentication

Every Xtract operation requires a bearer API key with the `xtract` scope.

Authorization: Bearer fx_live_************

Response Format

Successful responses use a strict `data` plus `meta` envelope. Optional expansion payloads appear in `included` when an endpoint supports `?include=`.

{
  "data": {
    "chain": "litecoin",
    "tip_height": 3118767,
    "tip_time": "2026-06-03T17:22:51Z"
  },
  "meta": {
    "request_id": "req_...",
    "served_at": "2026-06-03T17:23:02Z",
    "served_from": "indexed_store",
    "validation": {
      "scope": "chain",
      "status": "validated",
      "validated_height": 3118767,
      "validated_at": "2026-06-03T17:22:58Z",
      "lag_blocks": 0
    },
    "dataset_version": "v2.6",
    "credit_cost": 1,
    "included_expansions": []
  }
}

Validation Metadata

Validation is first-class in Xtract. Chain endpoints report the validated chain height used to serve the response. Control-plane endpoints report validation as not applicable instead of over-certifying data they do not read.

For the current scalar validation surface, use `GET /chain/validation`.

Credits & Rate Limits

Requests consume credits. Simple point lookups usually cost 1 credit; richer `?include=` expansions and batch requests cost more. Responses include `meta.credit_cost` and rate-limit headers where applicable.

Sandbox keys are always Free-effective: 30,000 period credits, 30 credits/minute, and 5 credits/second.

RateLimit-Limit: 20;w=1, 200;w=60, 300000;w=2592000
RateLimit-Remaining: 183
RateLimit-Reset: 42
RateLimit-Cost: 1

Retry-After: 17
X-Request-Id: req_...

Pagination

Paginated chain listings use opaque cursors. Page 1 anchors the walk to a validated chain height, and later pages keep that anchor so a long listing remains consistent while new blocks arrive.

Chart Ranges

Chart endpoints use `start` and `end` query parameters with half-open range semantics: `[start, end)`. Weekly buckets are anchored to Monday 00:00 UTC.

GET /charts/network?metrics=tx_count,avg_fee_atomic_units&start=2026-05-01&end=2026-06-01&grain=day

The older `from` and `to` aliases are accepted for compatibility during the transition, but new integrations should use `start` and `end`.

Live Current Data

Chart endpoints accept include_current=true (REST default false; MCP tools default true) to attach an additive current member beside the untouched completed history. Two object kinds exist:

• time_window — an interval aggregate over the half-open UTC range [window_start, window_end). is_complete=false means the interval can still accumulate observations. Completion is proven by consensus time: a window is complete only when the chain's median-time-past has reached window_end — a wall clock or a single next-day block timestamp never finalizes anything.
• state_snapshot — a point-in-time state (lifetime totals, pool balance, spot price). Snapshots are never summed and carry no interval semantics.

Every chain-derived current object binds one coherent read: as_of_height, as_of_hash, and as_of_time, plus stability — provisional until every represented block is beyond the deployed reorg-safe depth, reorg_safe after. Completeness and stability are orthogonal: a completed close can still be provisional. Unsupported calculations return an explicit status=unavailable object with a governed reason_code — never a fabricated zero, a copied close, or a silently missing key.

A just-rolled-over UTC day is a valid empty window: additive totals are exactly 0, non-additive statistics are null, observation_count=0, and as_of_time may precede window_start (it names the last coherent block, not an in-window observation).

Addresses: active_addresses is an exact distinct count inside one window and must never be summed across periods; the lifetime concept is total_unique_addresses_seen, a state through the as-of block.

MWEB: pool balance is state; peg-in, peg-out, fees, and net flow are window metrics. Net flow is peg-in minus peg-out minus MWEB fees, and the identity is enforced server-side at one height.

Launch granularity matrix: day and rolling_24h serve every governed metric; week/month current windows serve additive totals only (non-additive and distinct requests return exact_aggregation_unavailable); current year windows return unsupported_granularity. Sources are classed honestly: live (per-block), near-live (classifier watermark with explicit lag), daily-complete, and snapshot-only — snapshot-only sources never fabricate an intraday value.

Available example (abridged):

"current": {
  "window": {
    "kind": "time_window", "status": "available", "granularity": "day",
    "window_start": "2026-08-07T00:00:00Z", "window_end": "2026-08-08T00:00:00Z",
    "is_complete": false, "observation_count": 380,
    "as_of_height": 3155900, "as_of_hash": "<64-hex>",
    "as_of_time": "2026-08-07T15:30:00Z", "stability": "provisional",
    "values": { "tx_count": 41000 }
  },
  "snapshots": [ { "kind": "state_snapshot", "scope": "lifetime",
                   "values": { "total_unique_addresses_seen": 12345678 } } ]
}

Unavailable example:

"current": { "window": { "kind": "time_window", "status": "unavailable",
  "is_complete": false, "reason_code": "exact_aggregation_unavailable",
  "last_complete_at": "2026-08-06T00:00:00Z" }, "snapshots": [] }

Chart CSV exports (format version 2): the Xamine chart CSV route accepts format_version=2 (v1 stays byte-compatible and remains the default) adding the canonical metadata columns kind, status, granularity, window_start, window_end, is_complete, scope, observation_count, as_of_height, as_of_hash, as_of_time, stability, confirmation_depth, source_watermark, reason_code; include_current=true (requires v2) appends the current window and snapshot rows after the completed rows. Completed-row is_complete is proven per row by the same median-time-past predicate.

Errors

Error responses keep the same `meta` block for request tracing.

{
  "error": {
    "code": "auth_required",
    "message": "Authentication required."
  },
  "meta": {
    "request_id": "req_...",
    "served_at": "2026-06-03T17:23:02Z",
    "served_from": "control_plane",
    "validation": {
      "scope": "account",
      "status": "not_applicable",
      "validated_height": null,
      "validated_at": null,
      "lag_blocks": null
    }
  }
}

Endpoint Reference

This catalog mirrors the current OpenAPI 0.2.0 operation set. Use the per-endpoint pages for request examples and integration notes, and the OpenAPI document for exhaustive schemas and generated-client inputs.

Chain

Mempool

Charts

Developer

OpenAPI

The generated OpenAPI 3.1 contract is the source for schemas, operation ids, headers, and generated clients.