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 isGET, and CORS is open (access-control-allow-origin: *). Any other method answers405 {"error":"read-only"}. - Network: the first path segment is
sequence(XYO's test network, chain4b43a753…24bc) ormainnet(chain319e667c…7f26). Anything else answers404 {"error":"unknown network","networks":["sequence","mainnet"]}. - Responses: JSON. Most carry
meta: { net, source, generatedAt }.sourcenames 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-controlheader.
Endpoints
In the paths below, {net} is sequence or mainnet.
| Path | Parameters | Returns | Edge cache |
|---|---|---|---|
/{net}/head | head {n, hash, producer, epoch, txs}, pace, block-time statistics, active producers, the viewer's observed range, upstream status and live | 2 s | |
/{net}/blocks | limit 1–100 (default 30), before (a height) | blocks[], high, more | 2 s at the top; 300 s for settled pages |
/{net}/block/{n | hash} | a height, or a 64-hex block hash inside the observed window | block {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 hash | tx {hash, n, blockHash, from, signers, fees, nbf, exp, payloads[], transfers[]} and raw | Immutable, 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 hash | type: height, block, tx, address or unknown-hash (with the viewer's window); unrecognised answers 400 | none to 300 s |
/{net}/producers | window: 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 address | windows, observed share, streaks, hourly counts, recent blocks, coverage | 15 s |
/{net}/address/{address} | a 40-hex address; upto: a block number, for older history | balance (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 hash | 15 s (older pages 300 s) |
/{net}/health | network 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 call | 15 s | |
/{net}/race | window: 10m, 1h (default), 6h, 24h or 7d | standings, leader and lead changes over the window | 3–300 s |
/{net}/activity | window: 1h (default) or 24h | transactions by app and by schema, latest transactions | 15 s |
/{net}/stats | block-time distribution (mean, median, p10, p90, fastest, slowest, histogram) | 60 s (mainnet 600 s) | |
/{net}/height/{n} | a height | why a height was won: the winner, the observer's view, and Oxyon's own build attempts | 30 s |
/{net}/heights | the 30 most recent explained heights | 30 s | |
/{net}/journey/{n} | a height | a block journey document, oxyon.xl1.block-journey.v1 (below) | 30 s |
/{net}/intel | race intelligence, oxyon.xl1.race-intel.v1, over each observer's window | 60 s | |
/{net}/live | a WebSocket upgrade | on connect, a hello message (summary and the latest 30 blocks), then blocks messages as new blocks arrive; a plain GET answers 426 | |
/infra | Oxyon's producers' published telemetry and each observer's race summary and health | 60 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
| Status | When | Body |
|---|---|---|
| 400 | A malformed height, hash, address or window, a missing id, or an unrecognised search query | {"error": "…"}; search adds a hint |
| 404 | Unknown 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 |
| 405 | Any method other than GET (or OPTIONS) | {"error":"read-only"} |
| 409 | tx/ was given a block hash | {"error":"that is a block hash","n":…} |
| 426 | live without a WebSocket upgrade | |
| 500, 502 | An 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}.jsonand recompute its hash, signer and signed time (itsnetwork.xyo.timepayload). - Finality: this API doesn't establish XL1 finality.
hasNext, and the journey'shasSuccessor, 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
produceris 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
| Field | Current value | Deprecated compatibility field |
|---|---|---|
chainTruth.class, winnerCandidate.class | ON-CHAIN DATA — RELAYED, CHECKABLE: relayed XYO data that you can recompute with howToCheck | legacyClass: VERIFIED ON-CHAIN FACT (deprecated 2026-11-13; it overstated the check) |
chainTruth.hasSuccessor | the 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[].hashClass | MATCHES 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 route | Contract (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
errormessages, the order of keys, and fields outside the schemas. A removed, renamed or retyped promised field would bev2, served beside v1.
| Status | When | Body |
|---|---|---|
| 200 | answered | the route's schema, with meta.apiVersion and meta.schema |
| 400 | malformed input (for example a hash that is not 64 hexadecimal characters) | { error, meta: { apiVersion, schema } } |
| 404 | unknown network, something not found, or a path outside the seven v1 routes | { error, meta }; outside v1 also v1Routes |
| 502 | an upstream source failed (for example XYO's RPC for address) | { error, meta }; never a zero or empty answer in its place |
| 500 | an 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 indeprecated. - Deprecated fields stay until a removal is announced on this page. None is scheduled.
- Responses without a
schemaare 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.tickErroris the last error ever recorded. ComparetickErrorAtwithlastOkbefore treating it as current.- Caching:
cache-controlis the same whether the answer is fresh or served from Cloudflare's edge cache (cf-cache-status: HIT). Until 2026-11-14, edge HITs carriedmax-age=14400instead 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 withcache: 'no-store', or checkmeta.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.