Developers  /  XL1 Explorer API

XL1 Explorer API reference

Experimental, read-only, free to read, and with no keys and no service-level guarantee. This page documents behaviour observed and read from the code on 2026-11-14. It is not a commercial API.

Basics

  • Base URL: https://oxyon.io/api/xl1/. Every endpoint is GET, and CORS is open (access-control-allow-origin: *). Any other method answers 405 {"error":"read-only"}.
  • Network: the first path segment is sequence (XYO's test network, chain 4b43a753…24bc) or mainnet (chain 319e667c…7f26). Anything else answers 404 {"error":"unknown network","networks":["sequence","mainnet"]}.
  • Responses: JSON. Most carry meta: { net, source, generatedAt }. source names where the data comes from:
    • official: XYO block data, relayed by Oxyon's chain viewer. It is not re-hashed by this API, so recompute it yourself (see provenance).
    • observed: computed from the blocks the viewer has seen.
    • derived: joined with Oxyon's published observer and producer files.
  • Readers never trigger an upstream read. Blocks come from the viewer's own store, which polls XYO. Answers are cached at Cloudflare's edge for the time shown in each response's cache-control header.

Endpoints

In the paths below, {net} is sequence or mainnet.

PathParametersReturnsEdge cache
/{net}/headhead {n, hash, producer, epoch, txs}, pace, block-time statistics, active producers, the viewer's observed range, upstream status and live2 s
/{net}/blockslimit 1–100 (default 30), before (a height)blocks[], high, more2 s at the top; 300 s for settled pages
/{net}/block/{n | hash}a height, or a 64-hex block hash inside the observed windowblock {n, hash, prev, producer, epoch, txs, txHashes, signatures, …} and raw, XYO's [boundWitness, payloads]Immutable once the viewer holds the next block, otherwise 5 s (a caching rule, not finality)
/{net}/tx/{hash}a 64-hex transaction hashtx {hash, n, blockHash, from, signers, fees, nbf, exp, payloads[], transfers[]} and rawImmutable, or 10 s; a 404 is cached 30 s
/{net}/search?q=a height, a 40-hex address, or a 64-hex block or transaction hashtype: height, block, tx, address or unknown-hash (with the viewer's window); unrecognised answers 400none to 300 s
/{net}/producerswindow: 10m, 1h, 6h, 24h (default), 7d or all; or day: a UTC date, YYYY-MM-DD, for exactly that calendar day (takes precedence over window)rows[] per producer, total, exact, coverage; with day: window: "day", day, and complete (true once the day has ended and is fully observed; publish a day's figures only then)10–60 s; a complete day 1 h
/{net}/producer/{address}a 40-hex addresswindows, observed share, streaks, hourly counts, recent blocks, coverage15 s
/{net}/address/{address}a 40-hex address; upto: a block number, for older historybalance (atto-XL1) and transfer history from XYO's public RPC, each with the head and range XYO answered for. History holds only the newest transfers in the range (about 30), so page with upto set to history.oldest and de-duplicate by block and transfer hash15 s (older pages 300 s)
/{net}/healthnetwork health: overall, groups (network: the XL1 network as observed; oxyon: Oxyon's own observers and telemetry, each with its own overall), checks[] (key, label, group, state: ok / slow / stalled / unknown / info, value, detail, source), the fixed thresholds and notChecked. Producer telemetry rows are always info; their value is { status, ageMin, stale } (stale after thresholds.telemetry.staleMin minutes; an unreadable report time gives null, never fresh). Composed from the summary, 1 h producers and the observers' published files; contacts no producer or observer. XYO RPC reachability is not independently checked: this route makes no RPC call15 s
/{net}/racewindow: 10m, 1h (default), 6h, 24h or 7dstandings, leader and lead changes over the window3–300 s
/{net}/activitywindow: 1h (default) or 24htransactions by app and by schema, latest transactions15 s
/{net}/statsblock-time distribution (mean, median, p10, p90, fastest, slowest, histogram)60 s (mainnet 600 s)
/{net}/height/{n}a heightwhy a height was won: the winner, the observer's view, and Oxyon's own build attempts30 s
/{net}/heightsthe 30 most recent explained heights30 s
/{net}/journey/{n}a heighta block journey document, oxyon.xl1.block-journey.v1 (below)30 s
/{net}/intelrace intelligence, oxyon.xl1.race-intel.v1, over each observer's window60 s
/{net}/livea WebSocket upgradeon connect, a hello message (summary and the latest 30 blocks), then blocks messages as new blocks arrive; a plain GET answers 426
/infraOxyon's producers' published telemetry and each observer's race summary and health60 s

Examples

curl https://oxyon.io/api/xl1/sequence/head
{"meta":{"net":"sequence","source":"observed","generatedAt":1794620702000},
 "head":{"n":764841,"hash":"…","producer":"…","epoch":1794620691000,"txs":0},
 "observed":{"low":…,"high":764841,…},"upstream":{"lastOk":…,"tickError":…,"tickErrorAt":…},"live":true, …}

curl https://oxyon.io/api/xl1/sequence/block/764829
{"meta":{"net":"sequence","source":"official",…},"block":{"n":764829,"hash":"…","prev":"…","producer":"…",…},"raw":[{…},[…]]}

curl https://oxyon.io/api/xl1/sequence/producers?window=99y
400 {"error":"window must be 10m, 1h, 6h, 24h, 7d or all"}

Errors

StatusWhenBody
400A malformed height, hash, address or window, a missing id, or an unrecognised search query{"error": "…"}; search adds a hint
404Unknown network or path; a block hash outside the observed window; a transaction that can't be found{"error":"not found", …}. Sequence has no public transaction index, so only the viewer's window can be searched there
405Any method other than GET (or OPTIONS){"error":"read-only"}
409tx/ was given a block hash{"error":"that is a block hash","n":…}
426live without a WebSocket upgrade
500, 502An internal error, or an index that names the wrong block{"error":"internal","detail":…}

Data provenance and finality

  • Source: all chain data comes from XYO's public XL1 RPC and block CDN, through Oxyon's chain viewer. The API relays it and does not re-hash it. To check a block yourself, fetch https://blocks.{net}.xyo.space/block/number/{n}.json and recompute its hash, signer and signed time (its network.xyo.time payload).
  • Finality: this API doesn't establish XL1 finality. hasNext, and the journey's hasSuccessor, mean only that the viewer already holds a newer block. Protocol finality is what XYO's RPC reports as its finalized head (finalizationViewer_head), and XYO publishes no finality rule that Oxyon checks independently.
  • Producer and canonicity: a block's producer is its first signer (INFERRED). Which chain is canonical is as XYO's servers present it (INFERRED).
  • Observer data (height, heights, journey, intel, infra) comes from files Oxyon's observers publish to the public xl1-status-data repository. Each observer reports on its own clock, and both poll the same public RPC, so their agreement isn't independent corroboration.

Block journey classes and deprecated fields

FieldCurrent valueDeprecated compatibility field
chainTruth.class, winnerCandidate.classON-CHAIN DATA — RELAYED, CHECKABLE: relayed XYO data that you can recompute with howToChecklegacyClass: VERIFIED ON-CHAIN FACT (deprecated 2026-11-13; it overstated the check)
chainTruth.hasSuccessorthe viewer holds height + 1 (a caching condition)final: the same value under a misleading name (deprecated 2026-11-13); it is not protocol finality
candidates[].hashClassMATCHES RELAYED BLOCK HASH, RECOMPUTED BY OXYON OBSERVER, OBSERVER REPORTED, UNVERIFIED (no hash published)legacyHashClass: CANONICAL VERIFIED or INDEPENDENTLY RECOMPUTED, present only where the label changed (deprecated 2026-11-14)

Each journey document also carries deprecated: {…} notes, and attestation.signed: false: it is unsigned and anchored nowhere. Trust comes from recomputing the chain.

Stable API: v1

Seven routes have a stable form under /api/xl1/v1/. A v1 request is answered by the same handler, and from the same edge cache, as its unversioned path, so it costs nothing extra. The answer differs only by two added fields: meta.apiVersion (1) and meta.schema (for example oxyon.xl1.api.head.v1). Every other field is exactly as on the unversioned path. Any other route under /v1/ answers 404 with the list of v1 routes. The unversioned paths above are unchanged.

v1 routeContract (JSON Schema)
/api/xl1/v1/{net}/head/xl1/api/v1/head.schema.json
/api/xl1/v1/{net}/block/{n|hash}/xl1/api/v1/block.schema.json
/api/xl1/v1/{net}/tx/{hash}/xl1/api/v1/tx.schema.json
/api/xl1/v1/{net}/address/{address}/xl1/api/v1/address.schema.json
/api/xl1/v1/{net}/producers/xl1/api/v1/producers.schema.json
/api/xl1/v1/{net}/producer/{address}/xl1/api/v1/producer.schema.json
/api/xl1/v1/{net}/journey/{n}/xl1/api/v1/journey.schema.json

Each schema lists the fields v1 promises. Other fields may appear and may change. Within v1, promised fields are only ever added to, never removed, renamed or retyped; a breaking change would be a new version (v2) beside v1. Each schema is tested against a real captured answer. Limits are the same as the unversioned routes (see below): no keys, and edge caching per route.

v1 compatibility and errors

  • Promised: the fields in each route's schema, their types, the route paths, and the status codes below. Within v1 these are only added to. Anything not in a schema may change without notice; read it defensively.
  • Not promised: the wording of error messages, the order of keys, and fields outside the schemas. A removed, renamed or retyped promised field would be v2, served beside v1.
StatusWhenBody
200answeredthe route's schema, with meta.apiVersion and meta.schema
400malformed input (for example a hash that is not 64 hexadecimal characters){ error, meta: { apiVersion, schema } }
404unknown network, something not found, or a path outside the seven v1 routes{ error, meta }; outside v1 also v1Routes
502an upstream source failed (for example XYO's RPC for address){ error, meta }; never a zero or empty answer in its place
500an internal failure in the viewer{ error: "internal", detail }, without v1 meta (the same answer as the unversioned path). Treat any 5xx as retryable

Error answers are not cached as answers: each route's cache policy applies only to successful reads.

Versioning and compatibility

  • Documents that carry a schema (oxyon.xl1.block-journey.v1, oxyon.xl1.race-intel.v1) are changed additively. Fields may be added. A renamed or reclassified field keeps its old value in a deprecated field, named in deprecated.
  • Deprecated fields stay until a removal is announced on this page. None is scheduled.
  • Responses without a schema are the viewer's working shapes. Fields may be added; read them defensively.

Rate and availability limits (known)

  • There are no keys and no published rate limit. Cloudflare's normal protections apply. Please poll no faster than the cache time of the endpoint you use.
  • Sequence is watched continuously (live: true). Mainnet is advanced by a once-a-minute schedule (live: false), so its head can be about a minute behind.
  • The viewer keeps the most recent 10,000 blocks per network. A block hash older than that can't be looked up by hash. A Sequence transaction older than that can't be found either; on mainnet, the API falls back to XYO's published transaction index.
  • upstream.tickError is the last error ever recorded. Compare tickErrorAt with lastOk before treating it as current.
  • Caching: cache-control is the same whether the answer is fresh or served from Cloudflare's edge cache (cf-cache-status: HIT). Until 2026-11-14, edge HITs carried max-age=14400 instead of the short value (fixed: oxyon-io-site #56). Responses carry no ETag, and a conditional request returns a full 200. To read the freshest data, fetch with cache: 'no-store', or check meta.generatedAt.
  • There is no uptime guarantee. A 5xx means try again later, not a statement about the chain.

For evidence records, which are not part of this API, see the Evidence Explorer and VERIFY.md.