schema.graphql

type Asset {
  code: String!
  issuer: String
}

type Pair {
  pairKey: String!
  network: String!
  assetA: Asset!
  assetB: Asset!
  latestPrice: Float
  lastUpdated: String
}

type AggregatedPrice {
  assetA: String!
  assetB: String!
  pairKey: String!
  price: Float!
  sdexPrice: Float!
  ammPrice: Float!
  bestRoute: String!
  volume24h: Float!
  sdexVolume24h: Float!
  ammVolume24h: Float!
  vwap1m: Float!
  vwap5m: Float!
  vwap1h: Float!
  vwap24h: Float!
  priceChange24h: Float!
  lastUpdated: String!
  sources: Int!
  confidence: String!
  lastTradeAgeSeconds: Int
}

type RouteInfo {
  route: String!
  sdexPrice: Float!
  ammPrice: Float!
  estimatedOutput: Float!
  slippagePct: Float!
  recommendation: String!
  network: String
}

type PriceBucket {
  bucket: String!
  window: String!
  vwap: Float!
  sdexVwap: Float
  ammVwap: Float
  volume: Float!
  tradeCount: Int!
  open: Float
  close: Float
  high: Float
  low: Float
}

type PriceUpdate {
  pair: String!
  price: Float!
  ts: String!

  """Which chain the price came from — testnet or mainnet."""
  network: String!
}

enum OracleSourceStatus {
  NOT_CONFIGURED
  AVAILABLE
  UNREACHABLE
  EMPTY
}

type OracleSource {
  name: String!
  price: Float
  timestamp: String
  deviationPct: Float

  """
  UNREACHABLE means the adapter failed; EMPTY means it is configured but
  returned no quote.
  """
  status: OracleSourceStatus!
  ageSeconds: Int
}

type OracleComparison {
  asset: String!
  network: String!
  lens: Float
  reflector: Float
  deviationPct: Float
  status: String!
  fetchedAt: String!
  oracles: [OracleSource!]!
}

"""Sort order for the `screener` query."""
enum ScreenerSortOrder {
  ASC
  DESC
}

"""
Filters for the `screener` query — the same filters REST GET /screener
accepts. Every field is optional; an omitted field does not filter.

`marketCap` is declared only so it can be rejected with an explanation,
mirroring the REST route: Lens has no circulating supply data to compute a
market cap from. Passing it fails the query with UNSUPPORTED_PARAMETER
rather than being silently ignored.
"""
input ScreenerFilters {
  volume: Float
  change24hMin: Float
  change24hMax: Float
  priceMin: Float
  priceMax: Float
  liquidity: Float
  marketCap: Float
}

"""
One row of screener results. `liquidityUnit` is the quote asset of
`pairKey`; liquidity is summed AMM reserve value denominated in it.
"""
type ScreenerRow {
  pairKey: String!
  volume: Float!
  price: Float!
  change24h: Float!
  liquidity: Float!
  liquidityUnit: String!
}

"""
One page of screener results, cursor-paginated exactly like REST
GET /screener: pass `nextCursor` back as `cursor` for the following page;
it is null on the last page. `hasMore` reports whether another page exists.
"""
type ScreenerPage {
  network: String!
  rows: [ScreenerRow!]!
  nextCursor: String
  hasMore: Boolean!
}

"""
One venue's figures in a `volumes` or `spreads` result. Both queries
return venues as a list of this type so a caller can select only the fields
it wants per venue.

Which fields are set depends on the query, and mirrors the matching REST
route field for field:

- `volumes`: `venue`, `volume` (the asset's traded volume on that venue,
  in the asset's own units, summed across every pair) and `aggregator`.
  The spread fields are null.
- `spreads`: one entry per (venue, pair): `venue`, `pairKey`, `bid`,
  `ask`, `mid`, `spreadBps`, `spreadPct`, `observations`,
  `lastSeen`. `volume` is null.
"""
type VenueQuote {
  venue: String!

  """
  Whether the venue is an aggregator re-reporting primary-market trades (volumes only).
  """
  aggregator: Boolean

  """Traded volume in the asset's own units over the window (volumes only)."""
  volume: Float

  """
  The pair this quote is for (spreads only): two pairs on one venue are different books.
  """
  pairKey: String

  """Lowest print in the window (spreads only)."""
  bid: Float

  """Highest print in the window (spreads only)."""
  ask: Float
  mid: Float

  """(ask - bid) / mid * 10000 (spreads only)."""
  spreadBps: Float

  """spreadBps / 100 (spreads only)."""
  spreadPct: Float
  observations: Int
  lastSeen: String
}

"""
Labelled net (primary markets only) and gross (including aggregators) volume.
"""
type VolumeTotals {
  net: Float!
  gross: Float!
}

type VolumeProvenance {
  venues: [String!]!
  sampleCount: Int!
  observedSampleCount: Int!
  latestTradeAt: String
  dataAgeSeconds: Int
}

"""
Cross-venue traded volume for an asset: the same figures as REST
GET /volumes/:asset, with the per-venue breakdown (`byVenue` on REST) as a
typed `venues` list.
"""
type VolumeReport {
  asset: String!
  network: String!
  window: String!
  startTime: String!
  endTime: String!
  totals: VolumeTotals!
  netVolume: Float!
  grossVolume: Float!

  """Alias for netVolume, as on REST."""
  totalVolume: Float!

  """Per-venue volume, ordered by venue name like REST's `venues`."""
  venues: [VenueQuote!]!
  tradeCount: Int!
  netTradeCount: Int!
  grossTradeCount: Int!
  medianTradeSize: Float
  topTradeVolumeShare: Float
  volumeConcentration: Float
  concentrationMeasure: String!

  """ok, no_trades or no_positive_volume."""
  status: String!
  provenance: VolumeProvenance!
}

"""
Per-(venue, pair) spreads for an asset: the same figures as REST
GET /spreads/:asset. `venues` is tightest first; `tightest` is null when no
venue quoted the asset in the window.
"""
type SpreadReport {
  asset: String!
  network: String!
  window: String!
  startTime: String!
  endTime: String!
  venues: [VenueQuote!]!
  tightest: VenueQuote
}

type Query {
  """
  Aggregated price for a pair. Three outcomes are kept distinct:
  
  - Malformed asset input (an asset that is not CODE or CODE:ISSUER) fails
    with a GraphQL error whose extensions.code is INVALID_INPUT.
  - A well-formed pair that is not tracked on the active network fails with
    a GraphQL error whose extensions.code is PAIR_NOT_FOUND.
  - A tracked pair with no trade data yet is not an error: it resolves to an
    AggregatedPrice with zeroed figures rather than null or an error.
  
  The result is only null if the resolver itself cannot produce a payload;
  clients should branch on extensions.code, not on null.
  """
  getPrice(assetA: String!, assetB: String!): AggregatedPrice
  getBestRoute(assetA: String!, assetB: String!, amount: Float!): RouteInfo

  """
  Returns historical price aggregate buckets for a pair over an optional [from, to] time range.
  
  The time range is inclusive at both ends: a bucket is included if bucket >= from and bucket <= to.
  Because both endpoints are inclusive, querying adjacent windows (e.g. [t0, t1] and [t1, t2]) will
  return the boundary bucket at t1 in both results.
  """
  getPriceHistory(assetA: String!, assetB: String!, window: String!, limit: Int, from: String, to: String): [PriceBucket]
  listPairs: [String]! @deprecated(reason: "Use 'pairs' instead")
  pairs: [Pair!]!

  """
  Compares the Lens price for an asset against every configured oracle.
  The network argument defaults to the active network.
  """
  oracle(asset: String!, network: String): OracleComparison

  """
  The pair screener: filter, sort and cursor-paginate tracked pairs. Shares
  its implementation, filters, sort fields and cursor pagination with REST
  GET /screener, and resolves against the active network.
  
  - `sortBy` accepts the REST route's fields: volume, change_24h, price,
    liquidity. Sorting on `market_cap` fails with the same explanation REST
    gives (UNSUPPORTED_PARAMETER is reserved for the `marketCap` filter):
    Lens has no circulating supply data to compute it from.
  - `limit` is clamped to [1, 100] like REST, never
    rejected.
  """
  screener(filters: ScreenerFilters, sortBy: String = "volume", order: ScreenerSortOrder = DESC, cursor: String, limit: Int = 20): ScreenerPage!

  """
  Cross-venue traded volume for an asset. Shares its implementation with
  REST GET /volumes/:asset: same windows (24h, 7d, 30d; default 24h), same
  figures. `network` (testnet or mainnet) defaults to the active network;
  any other value fails with INVALID_INPUT, as REST answers 400.
  """
  volumes(asset: String!, window: String, network: String): VolumeReport!

  """
  Per-(venue, pair) bid/ask spreads for an asset. Shares its implementation
  with REST GET /spreads/:asset: same windows (5m, 15m, 1h, 24h; default 5m),
  same figures. `network` (testnet or mainnet) defaults to the active
  network; any other value fails with INVALID_INPUT, as REST answers 400.
  """
  spreads(asset: String!, window: String, network: String): SpreadReport!
}

type Subscription {
  """
  Streams a PriceUpdate every time an ingester records a new price for the
  given pair.
  
  The network argument narrows the stream to one chain. It is optional, and
  omitting it delivers every enabled network — the right default only if you
  read the network field on each message, since a dual-network deployment
  otherwise interleaves two chains prices on one stream.
  """
  priceUpdated(pair: String!, network: String): PriceUpdate!
}