Docs  /  Developers

Stable API v1

LiveReviewed 2026-11-15

A read-only JSON API for XL1 data that Oxyon has observed. Its answers are observed data, not verified evidence. The full reference is at oxyon.io/developers/xl1-api.

Routes

Every route is a GET under https://oxyon.io/api/xl1/v1/{net}, where {net} is mainnet or sequence. No keys are needed, and CORS is open (*).

RouteAnswer's schema
/headhead
/block/{n or hash}block
/tx/{hash}tx
/address/{address}address
/producersproducers
/producer/{address}producer
/journey/{n}journey
  • /address/{address} takes ?upto=<block> to page back (see paging).
  • /producers takes ?window= with one of 10m, 1h, 6h, 24h, 7d or all.

What v1 adds

A v1 answer is the same answer as the unversioned path (/api/xl1/{net}/…), plus two fields:

"meta": { "…": "…", "apiVersion": 1, "schema": "oxyon.xl1.api.address.v1" }

Compatibility

  • Promised: the fields in each route's schema, their types, the paths, and the status codes below. Within v1 these are only ever added to.
  • Not promised: error-message wording, key order, and fields outside the schemas.
  • A breaking change would be published as v2, served beside v1.
  • Checked regularly: every 6 hours an automated, read-only check calls each live v1 route and validates the answers against the published schemas. A failure is reported to Oxyon; nothing is changed automatically.

Errors

StatusWhenBody
200answeredthe route's schema
400malformed input{ error, meta: { apiVersion, schema } }
404unknown network, not found, or a route outside v1{ 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{ error: "internal", detail } without v1 meta; treat any 5xx as retryable

Errors aren't cached. Don't assume every error carries meta.apiVersion.

Paging an address's transfers

XYO's history returns the newest transfers in a block range, one page at a time. The page size is XYO's and varies, so don't assume a number.

  • To go further back, ask again with ?upto=<history.oldest>. upto is inclusive, so the boundary block can appear on both pages: de-duplicate.
  • De-duplicate rows by block + transfer hash. Use transfer as a row's identity, not tx.
  • tx can be null, and often is, because XYO's history doesn't always name the transaction. Link a row to its block when tx is null.
  • History rows carry no finality or confirmation field. Treat them as observed activity.
  • Amounts are integer strings of atto-XL1 (10⁻¹⁸ XL1). Never parse them as floating point.

Example

curl -s https://oxyon.io/api/xl1/v1/mainnet/head | jq '.meta, .head'