Skip to main content
XIRA

XIRA API reference

XIRA turns messy market data into one clean, verifiable risk score per asset. This page explains what that means in plain terms, where to get the data, and how to check it for yourself.

An API is simply a set of web addresses that answer questions. Each address below is called an endpoint: you visit it, and it returns a JSON response your app (or you, in a browser) can read. The base URL for every endpoint is https://xira-gsb3.onrender.com.

The frontend is statically hosted; the API is a separate server with a 5-minute in-memory price cache. A cold Render instance may take 30–60s to wake.

Endpoints

Every endpoint serves one job: the board, one asset, its history, market stats, alerts, or health. The interactive OpenAPI docs at /docs of the same origin let you try each one in the browser.

GET/api/assets/allAllAssetsResponse

The main board. Returns a risk score for every tracked market plus a one-line market summary.

?fresh=true forces a recalculation instead of using the price cache

data_source is 'live', 'partial', or 'mock' depending on how many assets resolved from Yahoo Finance.

GET/api/attestations/{symbol}AttestationResponse

The full record for one asset: its score, confidence, the five factor scores, the explanation, and the on-chain transaction when one was published.

symbol is case-insensitive; must be a tracked symbol (NVDAx, TSLAx, ...)

Computes fresh (or serves from the 5-minute cache) and attempts an on-chain updateAttestation.

GET/api/attestations/{symbol}/historyAttestationHistory

A trail of past scores for one asset, newest first. Useful for spotting trends.

?limit=N, 1–50, default 10

Historical entries may omit evidence_hash and chain fields (they are retro-fit from the score log).

GET/api/assets/{symbol}AssetDetailResponse

A single asset's profile: which underlying ticker it tracks, its sector, the token address, and how the score moved since the last attestation.

symbol is case-insensitive

score_delta_24h compares the latest score with the previous one.

GET/api/assets/statsMarketStatsResponse

Market-level picture: the average score, how many assets sit in each risk band, and which markets score best and worst.

Served from the shared board cache.

GET/api/alertsAlertsResponse

Every market currently flagged as an anomaly, sorted from highest to lowest risk, with the reason for each flag.

Anomalies are factors scoring at critically low levels.

GET/api/assets/healthHealthResponse

Service health: version, chain, contract address, tracked asset count, and whether live data is enabled.

The landing page's oracle card mirrors this data.

GET/api/assets/history/stats{ status, database, stats }

SQLite store statistics (row counts per symbol).

Diagnostics.

GET/debug/data-sources{ use_live_data, cache_ttl, cached_tickers, cache_details, env_vars }

Per-ticker data source, cache age, and live-data flag.

Diagnostics; may be disabled in stricter deployments.

Example response

This is what one asset's record looks like. The important parts: risk_score (the 0–100 number), factors (why the number is what it is), and evidence_hash (the fingerprint that proves this record matches what was published onchain).

AttestationResponse

symbol · risk_score (0–100) · risk_level (LOW/MODERATE/ELEVATED/HIGH/CRITICAL) · confidence (37–100) · factors[5] · explanation · anomaly · anomaly_reason · evidence_hash (sha256 hex) · timestamp (unix) · model_version · data_source · data_freshness_ms · chain_tx? · chain_explorer? · chain_block? · chain_id?

FactorScore

name · label · score (0–100) · weight · description

AllAssetsResponse

generated_at · model_version · data_source · summary · assets[]

AttestationHistory

symbol · history[]

HealthResponse

status · version · chain · contract · tracked_assets · live_data

{
  "symbol": "NVDAx",
  "risk_score": 62,
  "risk_level": "HIGH",
  "confidence": 83,
  "factors": [
    { "name": "momentum", "label": "Momentum", "score": 58, "weight": 0.25,
      "description": "Neutral: +0.12% (24h), +1.80% (7d)." }
  ],
  "explanation": "NVDAx shows high risk (score 62/100). ...",
  "anomaly": false,
  "anomaly_reason": "",
  "evidence_hash": "0x4d8a…",
  "timestamp": 1786471527,
  "model_version": "v1.0.0",
  "data_source": "yahoo",
  "data_freshness_ms": 4120,
  "chain_tx": "0xabf3…",
  "chain_explorer": "https://www.okx.com/web3/explorer/xlayer-test/tx/0xabf3…",
  "chain_block": 9480231,
  "chain_id": 1952
}

On-chain contract

Every score is also published to a small program on the X Layer blockchain, so the number does not live only on one server. Anyone can read it there, and the stored fingerprint lets you confirm the API and the chain agree. The contract runs on X Layer Testnet (chain 1952) at 0x64288ccD936470f66D7035e824A9141C938C32AE.

Think of it as a public notice board: the oracle posts the latest score for each market, and anyone can check the post. Read functions are open to everyone; only the oracle can write.

updateAttestation(asset, score, confidence, evidenceHash, modelVersion, anomaly, anomalyReason)

owner / authorized updater

Requires score ≤ 100 and confidence ≤ 100; reverts otherwise.

batchUpdateAttestations(inputs[])

owner / authorized updater

Write several attestations in one transaction.

getLatestAttestation(asset)

anyone · view

Returns the full stored attestation including evidenceHash and timestamp.

getHistory(asset)

anyone · view

Returns the last 20 attestations for an asset, oldest first.

getScore(asset)

anyone · view

The single uint8 risk score: one call, one number.

getScoreBatch(assets[])

anyone · view

Many scores in one call; O(n) read, no per-call fee on testnet.

getAllTrackedAssetsWithScores()

anyone · view

All registered symbols, their asset addresses, scores, and timestamps in one call.

getAllTrackedSymbols()

anyone · view

Symbol names registered by the owner.

registerAsset / setAuthorizedUpdater / transferOwnership

owner only

Admin surface for asset registration and updater rotation.

Agents (MCP tools)

AI agents can use the same data through MCP (Model Context Protocol) tools. Instead of reading a dashboard, an agent asks one of these tools and receives the answer directly, with the attestation behind it. Each tool maps one-to-one onto an endpoint.

xira_get_asset_risk

GET /api/attestations/{symbol} : Full attestation for one symbol.

xira_get_all_assets

GET /api/assets/all : All tracked assets with scores, factors, and market summary.

xira_get_attestation_history

GET /api/attestations/{symbol}/history : Recent score trail for one symbol.

xira_get_alerts

GET /api/alerts : All currently flagged anomalies.

xira_get_market_stats

GET /api/assets/stats : Market-level risk statistics.

Quickstart

You do not need an API key. Copy any of these into a terminal:

# one market
curl https://xira-gsb3.onrender.com/api/attestations/NVDAx

# the whole board
curl https://xira-gsb3.onrender.com/api/assets/all

# a score trail
curl "https://xira-gsb3.onrender.com/api/attestations/BAx/history?limit=20"

# market stats and alerts
curl https://xira-gsb3.onrender.com/api/assets/stats
curl https://xira-gsb3.onrender.com/api/alerts

# health + contract
curl https://xira-gsb3.onrender.com/api/assets/health

Versioning and compatibility

Endpoints are additive; breaking changes will bump the model version and the docs page together. The contract ABI is fixed at the deployed address and is the compatibility boundary. A future verify() addition would be an additive function.