Public API

All endpoints are read-only JSON over HTTPS, versioned under /api/v1. Responses are wrapped as { data, meta }; meta carries generatedAt, methodologyVersion, cache TTL and a disclaimer. Numbers that carry monetary precision are strings. Errors are { error: { code, message } }.

Rate limits

Default 120 requests per minute per IP (configurable). Every response includes x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset; exceeding the limit returns HTTP 429 with retry-after. Responses are cacheable for 10–60 seconds (cache-control). CORS is open for GET.

Endpoints

Endpoint	Description	Parameters	Example
GET /api/v1/assets	Ranked assets with USD reference price, route, confidence, freshness and volumes.	—	/api/v1/assets
GET /api/v1/assets/{symbol}	Asset detail: price, route, pairs, recent swaps, anomaly summary. {symbol} accepts a ticker (RXD) or canonical id (usdc-plg20).	—	/api/v1/assets/RXD
GET /api/v1/pairs	All enabled pairs with their latest pair-level reference price.	—	/api/v1/pairs
GET /api/v1/pairs/{base}/{quote}	Pair detail including full methodology details (rejections, weights, repricing support, thresholds), liquidity and recent swaps. Reversed directions are resolved to the canonical pair.	—	/api/v1/pairs/RXD/LTC
GET /api/v1/pairs/{base}/{quote}/trades	Completed swaps with eligibility and flags.	limit (1–500), start_time, end_time (unix seconds or ISO)	/api/v1/pairs/RXD/LTC/trades?limit=50
GET /api/v1/pairs/{base}/{quote}/orderbook	Latest order-book snapshot and liquidity metrics.	depth (1–500)	/api/v1/pairs/RXD/LTC/orderbook?depth=20
GET /api/v1/pairs/{base}/{quote}/candles	OHLCV candles.	interval (5m,1h,4h,1d,1w), kind (raw\|filtered), limit, start_time, end_time	/api/v1/pairs/RXD/LTC/candles?interval=1h&kind=raw
GET /api/v1/prices/{symbol}	Compact price object for an asset.	—	/api/v1/prices/RXD
GET /api/v1/prices/{symbol}/methodology	Full audit trail: route, thresholds, per-pair evaluation, external anchor comparison and version history.	—	/api/v1/prices/RXD/methodology
GET /api/v1/health	Service health (database, cache, worker freshness).	—	/api/v1/health
GET /api/v1/status/sources	Data-source and collector status with recent failures.	—	/api/v1/status/sources
GET /api/v1/network/activity	Network-wide pair activity from the upstream aggregator, covering every pair on the network and flagging which ones SwapScope tracks. Context and discovery only; never an input to a reference price.	untracked (true to list only pairs SwapScope does not track)	/api/v1/network/activity?untracked=true
GET /api/coingecko/pairs	CoinGecko-style pair list (ticker_id, base, target, pool_id).	—	/api/coingecko/pairs
GET /api/coingecko/tickers	CoinGecko ideal-API tickers. last_price is the SwapScope reference price; last_trade_price, price_status, confidence_score and price_age_sec are added so integrators can filter stale markets.	—	/api/coingecko/tickers
GET /api/coingecko/orderbook	CoinGecko orderbook format.	ticker_id (RXD_LTC), depth	/api/coingecko/orderbook?ticker_id=RXD_LTC&depth=50
GET /api/coingecko/historical_trades	CoinGecko historical trades. trade_id is the swap uuid.	ticker_id, type (buy\|sell), limit, start_time, end_time	/api/coingecko/historical_trades?ticker_id=RXD_LTC&limit=50

Example

curl -s https://your-host/api/v1/prices/RXD | jq
{
  "data": {
    "id": "rxd",
    "symbol": "RXD",
    "price": {
      "usd": "0.0000396",
      "status": "reference",
      "freshness": "live",
      "confidence": { "score": 79, "level": "high" },
      "route": "RXD → LTC → USD",
      "externalAnchor": { "usd": "0.00003805", "providers": ["coingecko","coinpaprika"], "divergencePct": "4.1", "note": "comparison only" }
    }
  },
  "meta": { "generatedAt": "...", "methodologyVersion": "1.0.0" }
}

Field definitions

status: reference | indicative | stale | unavailable. Only `reference` is a confirmed, fresh price.
freshness: live | recent | low_confidence | stale | unavailable, from the age of the newest reliable trade.
confidence.score / level: 0–100 and High/Medium/Low/Stale/Unavailable. Components are included on detail endpoints.
referencePrice: Quote units per 1 base unit (string, full precision).
referencePriceUsd / price.usd: USD value through the published route; null when no route or unavailable.
indicativePrice / indicativeSource: Best current estimate when no reference exists (orderbook | trades | previous).
lastTradePrice: Newest completed swap price. Never the reference.
rawVwap24h / filteredVwap24h: Volume-weighted averages over all / eligible swaps.
volume24h.rawUsd / reliableUsd / rejectedUsd: Raw, reliable and excluded USD volume.
priceAgeSec: Age of the newest reliable trade in seconds.
route / routeString: Selected conversion route, e.g. RXD → LTC → USD, with per-hop rate, quality and age.
externalAnchor: External aggregator price for DEX-priced assets, comparison only; `used: false`.
flags[].code: Machine-readable anomaly code with severity, penalty and explanation.
maker / taker.participant: Truncated keyed hash of the DEX pubkey. Not an identity.
methodologyVersion: Version of the pricing methodology that produced the value.

CoinGecko compatibility

The /api/coingecko/* endpoints follow the CoinGecko exchange-integration “ideal API” field names (tickers: ticker_id, base_currency, target_currency, pool_id, last_price, base_volume, target_volume, liquidity_in_usd, bid, ask, high, low; orderbook: bids/asks as [price, quantity]; historical_trades: trade_id, price, base_volume, target_volume, trade_timestamp, type). Extra SwapScope fields are additive. Integrators should treat markets with price_status ≠ reference as unpriced.