openapi.yaml

openapi: 3.0.0
info:
  title: Lens API
  description: >-
    Unified Stellar price API aggregating SDEX + AMM prices.

    Every route is served under the `/v1` version segment; the versioned path is
    the canonical one documented here. The same routes also answer at their
    unversioned paths as deprecated aliases so pre-`/v1` integrations keep
    working — those responses carry `Deprecation` and `Link` headers pointing at
    the successor. See `docs/api-versioning.md` for the retirement policy.

    Cache policy: every route sends a deliberate `Cache-Control` response
    header. Live prices (`/price/*`) are `public, max-age=30`; aggregates
    (`/price/*/history`, `/price/twap/*`, `/price/vwap/*`, `/prices/history`,
    `/compare/*`, `/spreads/*`) are `public, max-age=60`; slower-moving views
    (`/volumes/*`, `/screener`, `/basket`) are `public, max-age=120`;
    reference data that changes rarely (`/pairs`, `/pools`, `/benchmark/*`)
    is `public, max-age=300`; the discovery document is
    `public, max-age=3600`. `/candles` for a closed historical window (its
    `to` at least one full interval in the past) is *probably* immutable —
    backfill can rewrite history — so it is
    `public, max-age=3600, stale-while-revalidate=86400`; the still-forming
    window is `public, max-age=60`. Every `public` response also sends
    `Vary: x-network`, because the Stellar network can come from the
    `x-network` header (not part of the URL cache key). Routes behind the
    x402 payment gate use `private` instead of `public` when x402 is
    configured, so a shared cache never serves paid content for free.
    Per-caller responses (`/usage/me`), operator routes
    (`/admin/*`), mutations and error responses are `no-store` and must never
    sit in a shared cache.

    Data Quality Guarantees: see `docs/data-quality.md` for explicit SLAs
    and guarantees on freshness (e.g. 300s staleness bound), completeness,
    precision (PostgreSQL Decimal(36,18) and negotiated string serialization),
    and multi-venue coverage across SDEX, Stellar AMM, Soroswap, and Aquarius.
  version: 0.1.0
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:4000
    description: Local development server

paths:
  /v1/venues/registry:
    get:
      operationId: getVenueRegistry
      summary: List registered venues and their network liveness
      description: Returns each registered venue adapter for the selected network. Liveness is based on recent price writes where available; on-demand adapters without persisted price points report unknown.
      security: []
      parameters:
        - $ref: '#/components/parameters/NetworkQuery'
      responses:
        '200':
          description: Registered venues and their current liveness
          content:
            application/json:
              schema:
                type: object
                required: [network, venues]
                properties:
                  network:
                    type: string
                    enum: [testnet, mainnet]
                  venues:
                    type: array
                    items:
                      type: object
                      required: [id, kind, network, enabled, liveness, lastSeenAt]
                      properties:
                        id:
                          type: string
                        kind:
                          type: string
                          enum: [orderbook, amm, oracle]
                        network:
                          type: string
                          enum: [testnet, mainnet]
                        enabled:
                          type: boolean
                        liveness:
                          type: string
                          enum: [live, stale, disabled, unknown]
                        lastSeenAt:
                          type: string
                          format: date-time
                          nullable: true

  /v1/venues:
    get:
      operationId: getVenueVolumeShare
      summary: Venue Share of Volume
      description: >-
        Per-venue traded volume, market share (percentage of total), and
        period-over-period percentage change comparing the requested window
        against the immediately preceding window of identical duration.

        Market shares sum to 100% within floating-point tolerance. Stale or
        excluded venues are explicitly listed in `excludedVenues`.

        All queries are filtered by `network` via the `x-network` header —
        testnet and mainnet data are never merged into a single series.
      security: []
      parameters:
        - $ref: '#/components/parameters/NetworkQuery'
        - name: window
          in: query
          description: Time window for the aggregation
          required: false
          schema:
            type: string
            enum: [24h, 7d, 30d]
            default: '24h'
      responses:
        '200':
          description: Venue volume share and market share data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VenuesResponse'
        '400':
          description: Invalid window parameter
          content:
            application/json:
              schema:
                type: object
                required: [error]
                properties:
                  error:
                    type: string

  /v1/live:
    get:
      operationId: getLive
      summary: Liveness probe
      description: >-
        Reports whether this process is wedged and needs to be restarted. It
        checks no dependencies by design: a process that cannot reach Postgres
        is still healthy and should keep running, so failing liveness during a
        database outage would restart every instance at once. Use `/ready` to
        decide whether to send traffic.
      security: []
      responses:
        '200':
          description: Process is alive.
  /v1/tvl:
    get:
      operationId: getTvl
      summary: Total Value Locked across Stellar DeFi venues
      description: >-
        Aggregates Total Value Locked (TVL) in USD across Stellar Classic AMM,
        Soroswap, and Aquarius. Reports totals, breakdown by venue, breakdown
        by asset with valuation sources named, and marks pools with unpriceable
        assets as unpriced rather than zero. Querying `?history=true` returns
        historical hourly TVL samples.
      security: []
      parameters:
        - $ref: '#/components/parameters/NetworkQuery'
        - name: history
          in: query
          required: false
          description: Return historical time series of TVL when true
          schema:
            type: boolean
            default: false
        - name: window
          in: query
          required: false
          description: Historical lookback window in hours (default 24)
          schema:
            type: string
            default: 24
      responses:
        '200':
          description: Total Value Locked breakdown or historical series
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                type: object
                required: [ok, uptimeSeconds]
                properties:
                  ok:
                    type: boolean
                    example: true
                  uptimeSeconds:
                    type: integer
                    description: Seconds since the process started.
                    example: 3600

  /v1/ready:
    get:
      operationId: getReady
      summary: Readiness probe
      description: >-
        Reports whether this process should receive traffic yet. Unhealthy
        until the boot sequence finishes — the server starts listening before
        the ingesters and background workers are running — and while Postgres
        is unreachable or unmigrated, or Redis is unreachable when Redis is
        part of readiness (`READINESS_REDIS_CHECK`, default true).

        A probe timeout is reported as `down`, and answers are cached briefly,
        so this is cheap to poll every few seconds. `/live` stays healthy
        throughout: a starting instance should be held out of rotation, not
        killed.
      security: []
      responses:
        '200':
          description: Ready to receive traffic.
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadinessReport'
        '503':
          description: >-
            Not ready. `ok` is false and `checks` says which dependency (or the
            boot sequence) is responsible. `/live` remains healthy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadinessReport'
                properties:
                  network:
                    type: string
                    enum: [testnet, mainnet]
                  totalTvlUsd:
                    type: number
                  unpricedPoolsCount:
                    type: integer
                  pricedPoolsCount:
                    type: integer
                  venues:
                    type: object
                  byAsset:
                    type: object
                  pools:
                    type: array
                    items:
                      type: object
                  computedAt:
                    type: string
                    format: date-time
        '400':
          description: Invalid parameters

  /v1/status:
    get:
      operationId: getStatus
      summary: Get API status and indexer state
      security: []
      parameters:
        - $ref: '#/components/parameters/NetworkQuery'
      responses:
        '200':
          description: API status and health diagnostics
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  status:
                    type: string
                    enum: [healthy, degraded, unhealthy]
                  network:
                    type: string
                    enum: [testnet, mainnet]
                  health:
                    type: object
                    properties:
                      process:
                        type: string
                      data:
                        type: string
                  process:
                    type: object
                    properties:
                      uptimeSeconds:
                        type: number
                      memoryUsageMb:
                        type: number
                      status:
                        type: string
                  data:
                    type: object
                    properties:
                      lastIndexedLedger:
                        type: integer
                        nullable: true
                      lastProcessedAt:
                        type: string
                        format: date-time
                        nullable: true
                      ingestLagSeconds:
                        type: integer
                        nullable: true
                      isStale:
                        type: boolean
                  watchedPairs:
                    type: array
                    items:
                      type: string
                  lastIndexedLedger:
                    type: integer
                    nullable: true
                  lastProcessedAt:
                    type: string
                    format: date-time
                    nullable: true
                  ingestLagSeconds:
                    type: integer
                    nullable: true
                  adminConfigured:
                    type: boolean
                    description: >-
                      Whether this deployment has an ADMIN_TOKEN configured, so
                      an operator can tell a rejected token from a disabled
                      admin surface. Reports only that a token is set, never any
                      part of its value. Admin routes answer 503
                      admin_not_configured when this is false.
        '503':
          description: Service unhealthy or database unreachable
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  status:
                    type: string
                  error:
                    type: string
                    description: >-
                      A fixed phrase, never the database driver's message. This
                      route is public and unauthenticated, and a connection
                      failure carries the host, the user and sometimes the whole
                      connection string; the detail is logged server-side
                      instead.
                    example: Database unavailable
                  pagingCondition:
                    type: string
                    example: DATABASE_DOWN
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /v1/snapshot:
    get:
      operationId: getSnapshot
      summary: Whole-network snapshot (venues, TVL, 24h volume, top pairs, pegs, freshness)
      description: >-
        A single timestamped summary of one network: every venue's liveness,
        AMM pool reserves (TVL), 24h traded volume, the busiest pairs, stablecoin
        peg readings and how fresh the underlying data is. All figures are read
        in one consistent database statement, so `asOf` is a real instant and
        every age is measured from it. Missing data is reported as `null` with a
        reason (or an empty list), never invented — a cross-pair volume total is
        only returned when the pairs share one unit. Responses are cached briefly
        per network; `cache.ageSeconds` states the age of a served copy.
      security: []
      parameters:
        - $ref: '#/components/parameters/NetworkQuery'
      responses:
        '200':
          description: Network snapshot
          headers:
            Cache-Control:
              schema:
                type: string
              description: Freshness/brief-caching policy for the snapshot.
            X-Cache:
              schema:
                type: string
                enum: [HIT, MISS]
              description: Whether this response came from the short-lived cache.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SnapshotResponse'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          description: Snapshot aggregation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalErrorResponse'

  /v1/price/{assetA}/{assetB}:
    get:
      operationId: getPrice
      summary: Get aggregated price for a pair
      security:
        - x402: []
      parameters:
        - name: assetA
          in: path
          required: true
          schema:
            type: string
          example: XLM
        - name: assetB
          in: path
          required: true
          schema:
            type: string
          example: USDC
        - $ref: '#/components/parameters/NetworkQuery'
        - $ref: '#/components/parameters/DecimalFormatHeader'
      responses:
        '200':
          description: Aggregated price data
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregatedPrice'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          description: Pair not watched
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /v1/price/{assetA}/{assetB}/route:
    get:
      operationId: getBestRoute
      summary: Get best swap route for a pair and amount
      security:
        - x402: []
      parameters:
        - name: assetA
          in: path
          required: true
          schema:
            type: string
          example: XLM
        - name: assetB
          in: path
          required: true
          schema:
            type: string
          example: USDC
        - name: amount
          in: query
          required: false
          schema:
            type: number
            default: 1000
        - $ref: '#/components/parameters/NetworkQuery'
        - $ref: '#/components/parameters/DecimalFormatHeader'
      responses:
        '200':
          description: Best route information
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteInfo'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /v1/price/{asset}/fiat:
    get:
      operationId: getFiatPrice
      summary: Convert asset price to fiat currency with NGN support (#290)
      security: []
      parameters:
        - name: asset
          in: path
          required: true
          schema:
            type: string
            example: XLM
        - name: currency
          in: query
          required: false
          schema:
            type: string
            default: USD
        - $ref: '#/components/parameters/NetworkQuery'
      responses:
        '200':
          description: Price converted into target fiat currency
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Invalid parameters
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /v1/price/{assetA}/{assetB}/history:
    get:
      operationId: getPriceHistory
      summary: Get price history buckets
      description: >-
        Returns price aggregate buckets (1m, 5m, 1h, 24h). Prices are serialized up to 18
        decimal places and volumes up to 7 decimal places matching Stellar stroop precision.
      security: []
      parameters:
        - name: assetA
          in: path
          required: true
          schema:
            type: string
          example: XLM
        - name: assetB
          in: path
          required: true
          schema:
            type: string
          example: USDC
        - name: window
          in: query
          required: false
          schema:
            type: string
            enum: [1m, 5m, 1h, 24h]
            default: 1h
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
            maximum: 1000
        - $ref: '#/components/parameters/NetworkQuery'
        - $ref: '#/components/parameters/DecimalFormatHeader'
      responses:
        '200':
          description: Price history
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                type: object
                properties:
                  pairKey:
                    type: string
                  network:
                    type: string
                    enum: [testnet, mainnet]
                  window:
                    type: string
                  buckets:
                    type: array
                    items:
                      $ref: '#/components/schemas/PriceBucket'
        '400':
          description: Invalid parameters
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /v1/pools:
    get:
      operationId: getPools
      summary: Get AMM liquidity pool reserves and spot prices
      description: >-
        Latest snapshot per pool for one network. Paginated with the shared
        keyset convention: ordered by pool_id ascending, default limit 50,
        maximum 200.
      security:
        - x402: []
      parameters:
        - $ref: '#/components/parameters/NetworkQuery'
        - $ref: '#/components/parameters/CursorQuery'
        - name: limit
          in: query
          required: false
          description: Page size. Out-of-range values are clamped into [1, 200].
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
      responses:
        '200':
          description: List of pools
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                type: object
                required: [pools, nextCursor, hasMore]
                properties:
                  pools:
                    type: array
                    items:
                      type: object
                      properties:
                        pool_id:
                          type: string
                        asset_a:
                          type: string
                        asset_b:
                          type: string
                        reserve_a:
                          oneOf:
                            - type: number
                            - type: string
                        reserve_b:
                          oneOf:
                            - type: number
                            - type: string
                        spot_price:
                          oneOf:
                            - type: number
                            - type: string
                        fee_bp:
                          type: integer
                        timestamp:
                          type: string
                          format: date-time
                  nextCursor:
                    type: string
                    nullable: true
                  hasMore:
                    type: boolean
        '400':
          description: Invalid limit or cursor
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /v1/candles/{assetA}/{assetB}:
    get:
      operationId: getCandles
      summary: Get OHLCV candle data
      description: >-
        OHLCV candles for a pair. Buckets are aggregated with exact numeric
        arithmetic in the database, so a sum does not depend on the order rows
        were summed in; values are narrowed to JSON numbers at the edge.
        Paginated with the shared keyset convention: ordered by bucket start
        time ascending, default limit 500, maximum 5000.
      security:
        - x402: []
      parameters:
        - name: assetA
          in: path
          required: true
          schema:
            type: string
          example: XLM
        - name: assetB
          in: path
          required: true
          schema:
            type: string
          example: USDC
        - name: interval
          in: query
          required: false
          schema:
            type: string
            enum: [1m, 5m, 15m, 1h, 4h, 1d]
            default: 1h
        - name: from
          in: query
          required: false
          description: >-
            Start of the time window (inclusive). Together with `to` this defines
            a half-open interval [from, to): samples whose timestamp is exactly
            `from` are included, samples whose timestamp is exactly `to` are
            excluded. This means two adjacent windows [T0, T1) and [T1, T2)
            share no boundary — a sample landing exactly on T1 appears in
            exactly one of the two windows.
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          required: false
          description: >-
            End of the time window (exclusive). Together with `from` this
            defines a half-open interval [from, to): samples whose timestamp is
            exactly `to` are excluded, samples whose timestamp is exactly
            `from` are included. This means two adjacent windows [T0, T1) and
            [T1, T2) share no boundary — a sample landing exactly on T1 appears
            in exactly one of the two windows.
          schema:
            type: string
            format: date-time
        - $ref: '#/components/parameters/CursorQuery'
        - name: limit
          in: query
          required: false
          description: Page size. Out-of-range values are clamped into [1, 5000].
          schema:
            type: integer
            minimum: 1
            maximum: 5000
            default: 500
      responses:
        '200':
          description: Candle data
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                type: object
                required: [pairKey, interval, from, to, candles, nextCursor, hasMore]
                properties:
                  pairKey:
                    type: string
                  interval:
                    type: string
                  from:
                    type: string
                    format: date-time
                  to:
                    type: string
                    format: date-time
                  candles:
                    type: array
                    items:
                      type: object
                      properties:
                        time:
                          type: string
                          format: date-time
                        open:
                          type: number
                        high:
                          type: number
                        low:
                          type: number
                        close:
                          type: number
                        volume:
                          type: number
                  nextCursor:
                    type: string
                    nullable: true
                  hasMore:
                    type: boolean
        '400':
          description: Invalid parameters
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /v1/prices/history:
    get:
      operationId: getPriceSnapshots
      summary: Get historical 1-minute price snapshots
      description: >-
        Returns minute-resolution price snapshots for a pair over [from, to],
        optionally aggregated into 5m or 1h buckets, with exact numeric
        arithmetic in the database so a sum does not depend on row order.
        Snapshots are retained for
        ~30 days. Paginated with the shared keyset convention: ordered by
        bucket start time ascending, default limit 1000, maximum 10000 points.
        With format=csv the pagination envelope travels in the X-Next-Cursor
        and X-Has-More response headers; with format=json it is in the body.
        Gated by x402 (matches the /price prefix).
      security:
        - x402: []
      parameters:
        - name: pair
          in: query
          required: true
          schema:
            type: string
          example: XLM/USDC
        - name: interval
          in: query
          required: false
          schema:
            type: string
            enum: [1m, 5m, 1h]
            default: 1m
        - name: from
          in: query
          required: false
          description: >-
            Start of the time window (inclusive). Together with `to` this defines
            a half-open interval [from, to): samples whose timestamp is exactly
            `from` are included, samples whose timestamp is exactly `to` are
            excluded. This means two adjacent windows [T0, T1) and [T1, T2)
            share no boundary — a sample landing exactly on T1 appears in
            exactly one of the two windows.
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          required: false
          description: >-
            End of the time window (exclusive). Together with `from` this
            defines a half-open interval [from, to): samples whose timestamp is
            exactly `to` are excluded, samples whose timestamp is exactly
            `from` are included. This means two adjacent windows [T0, T1) and
            [T1, T2) share no boundary — a sample landing exactly on T1 appears
            in exactly one of the two windows.
          schema:
            type: string
            format: date-time
        - name: format
          in: query
          required: false
          description: >-
            Response encoding. `csv` returns a text/csv body holding a
            `ts,price,volume` table (RFC 4180 quoting, LF line endings, one
            trailing newline); `json` is the default.
          schema:
            type: string
            enum: [json, csv]
            default: json
        - $ref: '#/components/parameters/CursorQuery'
        - name: limit
          in: query
          required: false
          description: >-
            Page size (number of buckets). Out-of-range values are clamped
            into [1, 10000].
          schema:
            type: integer
            minimum: 1
            maximum: 10000
            default: 1000
        - $ref: '#/components/parameters/NetworkQuery'
      responses:
        '200':
          description: >-
            Historical price snapshots. When more buckets exist beyond this
            page, the response carries X-Next-Cursor (pass it back as
            ?cursor=) and X-Has-More: true.
          headers:
            X-Next-Cursor:
              description: Opaque cursor for the next page; absent on the last page.
              schema:
                type: string
            X-Has-More:
              description: "'true' when another page exists, 'false' otherwise."
              schema:
                type: string
                enum: ['true', 'false']
          content:
            text/csv:
              schema:
                type: string
                example: "ts,price,volume\n2025-01-01T00:00:00.000Z,1.25,500\n"
            application/json:
              schema:
                type: object
                required: [pair, network, interval, from, to, count, points, nextCursor, hasMore]
                properties:
                  pair:
                    type: string
                  network:
                    type: string
                    enum: [testnet, mainnet]
                  interval:
                    type: string
                  from:
                    type: string
                    format: date-time
                  to:
                    type: string
                    format: date-time
                  count:
                    type: integer
                    description: Number of points in this page (not the total across pages).
                  points:
                    type: array
                    items:
                      type: object
                      properties:
                        ts:
                          type: string
                          format: date-time
                        price:
                          type: number
                        volume:
                          type: number
                  nextCursor:
                    type: string
                    nullable: true
                  hasMore:
                    type: boolean
        '400':
          description: Invalid parameters
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /v1/pairs:
    get:
      operationId: listPairs
      summary: List all active trading pairs
      description: >-
        Active trading pairs with their latest price metadata. Paginated with
        the shared keyset convention: ordered by pairKey ascending, default
        limit 50, maximum 200.
      security: []
      parameters:
        - $ref: '#/components/parameters/NetworkQuery'
        - $ref: '#/components/parameters/CursorQuery'
        - name: limit
          in: query
          required: false
          description: Page size. Out-of-range values are clamped into [1, 200].
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
      responses:
        '200':
          description: List of pairs
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                type: object
                required: [pairs, nextCursor, hasMore]
                properties:
                  pairs:
                    type: array
                    items:
                      type: object
                      properties:
                        pairKey:
                          type: string
                        assetA:
                          $ref: '#/components/schemas/Asset'
                        assetB:
                          $ref: '#/components/schemas/Asset'
                        latestPrice:
                          type: number
                          nullable: true
                        lastUpdated:
                          type: string
                          format: date-time
                          nullable: true
                  nextCursor:
                    type: string
                    nullable: true
                  hasMore:
                    type: boolean
        '400':
          description: Invalid limit or cursor
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      operationId: addPair
      summary: Add a new trading pair (Admin only)
      security:
        - adminAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                assetA:
                  type: string
                  example: XLM
                assetB:
                  type: string
                  example: USDC:GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5
      responses:
        '201':
          description: Pair added
        '400':
          description: Invalid input
        '401':
          description: Unauthorized
        '409':
          description: Pair already exists
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /v1/price/{assetA}/{assetB}/depth:
    get:
      operationId: getDepth
      summary: Get order-book depth and execution slippage for a pair
      description: >-
        Simulates an order of `amount` units of assetA and returns the price
        ladder plus the execution price and slippage versus the spot price.
      security:
        - x402: []
      parameters:
        - name: assetA
          in: path
          required: true
          schema:
            type: string
          example: XLM
        - name: assetB
          in: path
          required: true
          schema:
            type: string
          example: USDC
        - name: amount
          in: query
          required: false
          schema:
            type: number
            default: 1000
        - $ref: '#/components/parameters/NetworkQuery'
        - $ref: '#/components/parameters/DecimalFormatHeader'
      responses:
        '200':
          description: Depth ladder
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepthResponse'
        '400':
          description: Invalid amount
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          description: Pair not watched
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /v1/book/{assetA}/{assetB}:
    get:
      operationId: getBook
      summary: Get the aggregated SDEX and AMM price ladder for a pair
      description: >-
        Returns asks and bids as cumulative assetA size at each price. Live
        SDEX levels are reported as observed; AMM levels are synthetic,
        fee-adjusted reserve steps. `depth` is a fractional price distance
        around spot (default 0.1), and `step` is the fraction of each AMM
        reserve used per synthetic level (default 0.01). Per-venue sample
        counts, observation times, ages and availability are included.
      parameters:
        - name: assetA
          in: path
          required: true
          schema:
            type: string
          description: Base asset; use XLM for native Stellar or CODE:ISSUER for a token.
          example: XLM
        - name: assetB
          in: path
          required: true
          schema:
            type: string
          description: Quote asset; token issuers must be supplied in full.
          example: USDC:GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5
        - name: depth
          in: query
          required: false
          description: Maximum fractional distance from spot; valid range 0 to 0.5.
          schema:
            type: number
            minimum: 0
            maximum: 0.5
            default: 0.1
        - name: step
          in: query
          required: false
          description: AMM input-reserve fraction per synthetic rung; valid range 0.001 to 0.1.
          schema:
            type: number
            minimum: 0.001
            maximum: 0.1
            default: 0.01
        - $ref: '#/components/parameters/NetworkQuery'
        - $ref: '#/components/parameters/DecimalFormatHeader'
      responses:
        '200':
          description: Book levels with per-venue provenance; unavailable venues are identified in the response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookResponse'
        '400':
          description: Invalid asset, depth, or step parameter
        '503':
          description: No source could be read; response provenance identifies failed venues.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookResponse'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /v1/impact/{assetA}/{assetB}:
    get:
      operationId: getImpact
      summary: Get an adaptive slippage impact curve for a pair
      description: >-
        Returns slippage at standard trade sizes, an additional liquidity-sized
        point, and the size at which configured slippage thresholds are crossed.
        A thin pair returns `insufficient_liquidity` instead of a fabricated
        100% slippage result.
      security:
        - x402: []
      parameters:
        - name: assetA
          in: path
          required: true
          schema:
            type: string
          example: XLM
        - name: assetB
          in: path
          required: true
          schema:
            type: string
          example: USDC
        - name: thresholds
          in: query
          required: false
          description: Comma-separated positive slippage percentages. Defaults to 1,5,10.
          schema:
            type: string
            default: 1,5,10
        - name: liquidityFraction
          in: query
          required: false
          description: Usable fraction of the A-side reserve, between 0 and 1.
          schema:
            type: number
            default: 0.5
        - $ref: '#/components/parameters/NetworkQuery'
      responses:
        '200':
          description: Adaptive impact curve
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImpactResponse'
        '400':
          description: Invalid threshold or liquidity settings
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          description: Pair or AMM liquidity not found
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /v1/price/twap/{assetA}/{assetB}:
    get:
      operationId: getTwap
      summary: Get a manipulation-resistant time-weighted average price
      security:
        - x402: []
      parameters:
        - name: assetA
          in: path
          required: true
          schema:
            type: string
          example: XLM
        - name: assetB
          in: path
          required: true
          schema:
            type: string
          example: USDC
        - name: window
          in: query
          required: false
          description: Lookback window in minutes.
          schema:
            type: integer
            minimum: 1
            maximum: 1440
            default: 60
        - name: sampleInterval
          in: query
          required: false
          description: Sampling grid width in seconds.
          schema:
            type: integer
            minimum: 1
            maximum: 3600
            default: 60
        - name: method
          in: query
          required: false
          schema:
            type: string
            enum: [iqr, modified_zscore]
            default: iqr
        - $ref: '#/components/parameters/NetworkQuery'
        - $ref: '#/components/parameters/DecimalFormatHeader'
      responses:
        '200':
          description: TWAP result
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TwapResponse'
        '400':
          description: Invalid parameters
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          description: TWAP computation failed

  /v1/price/vwap/{assetA}/{assetB}:
    get:
      operationId: getVwap
      summary: Get a volume-weighted average price
      security:
        - x402: []
      parameters:
        - name: assetA
          in: path
          required: true
          schema:
            type: string
          example: XLM
        - name: assetB
          in: path
          required: true
          schema:
            type: string
          example: USDC
        - name: window
          in: query
          required: false
          description: Lookback window in minutes.
          schema:
            type: integer
            minimum: 1
            maximum: 1440
            default: 60
        - name: source
          in: query
          required: false
          description: Restrict to a single venue (omitted pools every venue).
          schema:
            type: string
            enum: [SDEX, AMM]
        - name: method
          in: query
          required: false
          schema:
            type: string
            enum: [iqr, modified_zscore]
            default: iqr
        - $ref: '#/components/parameters/DecimalFormatHeader'
        - $ref: '#/components/parameters/NetworkQuery'
      responses:
        '200':
          description: VWAP result
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VwapResponse'
        '400':
          description: Invalid parameters
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          description: VWAP computation failed

  /v1/volumes/{asset}:
    get:
      operationId: getVolumes
      summary: Get cross-venue traded volume for an asset
      description: >-
        Sums traded volume for `asset` across every pair and venue it appears
        in, measured in the asset's own units, with a per-venue breakdown and
        trade-size statistics. `volumeConcentration` is the Herfindahl-Hirschman
        Index (HHI), calculated as the sum of squared per-trade volume shares
        across the selected venues and window; it ranges from 0 to 1, with 1
        meaning all volume came from one trade. A missing statistic is `null`
        when there are no trades or no positive volume. Provenance reports the
        venues, positive-volume trade count, observed sample count, most recent
        trade timestamp and its age at `endTime`.
        Venues are classified as primary markets or aggregators in the registry.
        `totals.net` / `netVolume` sum primary markets only, while
        `totals.gross` / `grossVolume` include aggregator venues (e.g. Aquarius)
        that re-report trades settled elsewhere. `totalVolume` and `tradeCount`
        report the net figures; the trade-size statistics and provenance
        cover every venue (gross).
      security: []
      parameters:
        - name: asset
          in: path
          required: true
          schema:
            type: string
          example: XLM
        - name: window
          in: query
          required: false
          schema:
            type: string
            enum: [24h, 7d, 30d]
            default: 24h
        - $ref: '#/components/parameters/NetworkQuery'
      responses:
        '200':
          description: Aggregated volume
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolumeResponse'
        '400':
          description: Invalid window
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          description: Volume aggregation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalErrorResponse'

  /v1/spreads/{asset}:
    get:
      operationId: getSpreads
      summary: Get the tightest per-venue bid/ask spread for an asset
      description: >-
        Reports, for every (venue, pair) that quoted `asset` inside the window,
        the observed low, high and spread in basis points, tightest first.
        The spread is the dispersion of recent prints, not a resting order
        book's top-of-book gap.
      security: []
      parameters:
        - name: asset
          in: path
          required: true
          schema:
            type: string
          example: XLM
        - name: window
          in: query
          required: false
          schema:
            type: string
            enum: [5m, 15m, 1h, 24h]
            default: 5m
        - $ref: '#/components/parameters/NetworkQuery'
      responses:
        '200':
          description: Per-venue spreads
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpreadResponse'
        '400':
          description: Invalid window or network
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          description: Spread aggregation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalErrorResponse'

  /v1/rates/{asset}:
    get:
      operationId: getLendingRates
      summary: Get supply and borrow rates for an asset across lending venues
      description: >-
        Answers what `asset` earns when supplied and costs to borrow at every
        lending venue Lens ingests, one entry per venue sorted best-first
        (highest supply rate first). Each entry names the venue, the source it
        was read from and the specific pool/market it came from, so a rate is
        always attributable and venues are never silently averaged.

        An asset with no lending market returns an empty `venues` list with a
        200, not a 404.
      security: []
      parameters:
        - name: asset
          in: path
          required: true
          schema:
            type: string
          example: USDC
        - $ref: '#/components/parameters/NetworkQuery'
      responses:
        '200':
          description: Per-venue lending rates, best-first (empty when no market)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RatesResponse'
        '400':
          description: Invalid network
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          description: Rate lookup failed

  /v1/dispersion/{assetA}/{assetB}:
    get:
      operationId: getPairDispersion
      summary: Get venue price dispersion and outlier attribution for a pair
      description: >-
        Returns cross-venue price dispersion history and outlier attribution
        for a pair over time, including median, max absolute percentage deviation,
        spread in basis points, and outlying venue.
      security: []
      parameters:
        - name: assetA
          in: path
          required: true
          schema:
            type: string
          description: Base asset code or CODE:ISSUER
          example: XLM
        - name: assetB
          in: path
          required: true
          schema:
            type: string
          description: Quote asset code or CODE:ISSUER
          example: USDC
        - $ref: '#/components/parameters/NetworkQuery'
        - name: from
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Start timestamp (ISO-8601)
        - name: to
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: End timestamp (ISO-8601)
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 500
          description: Max number of history records to return
      responses:
        '200':
          description: Dispersion history and latest outlier attribution
          content:
            application/json:
              schema:
                type: object
                properties:
                  pairKey:
                    type: string
                  network:
                    type: string
                  latest:
                    type: object
                    nullable: true
                  count:
                    type: integer
                  history:
                    type: array
                    items:
                      type: object
        '400':
          description: Invalid request parameters
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          description: Dispersion query failed

  /v1/dispersion:
    get:
      operationId: listDispersion
      summary: List cross-venue dispersion across watched pairs
      description: >-
        Queries recent cross-venue dispersion reconciliation records across all pairs
        or filtered by a specific pair.
      security: []
      parameters:
        - name: pair
          in: query
          required: false
          schema:
            type: string
          description: Optional pair key filter (e.g. XLM/USDC)
        - $ref: '#/components/parameters/NetworkQuery'
        - name: from
          in: query
          required: false
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          required: false
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: List of dispersion reconciliation records
          content:
            application/json:
              schema:
                type: object
                properties:
                  network:
                    type: string
                  pair:
                    type: string
                    nullable: true
                  count:
                    type: integer
                  history:
                    type: array
                    items:
                      type: object
        '400':
          description: Invalid request parameters
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          description: Dispersion query failed

  /v1/compare/{asset}:

    get:
      operationId: compareAsset
      summary: Compare Lens prices with every configured external oracle
      description: >-
        Returns 200 even when both Lens and all configured oracles have no data
        for the asset. The `status` field distinguishes "no_data" from "aligned",
        "minor_deviation", "major_deviation" and "partial" (one source only).
        The response includes both the legacy `reflector` field for backward
        compatibility and an `oracles` array listing every configured source.
      security: []
      parameters:
        - name: asset
          in: path
          required: true
          schema:
            type: string
          example: XLM
        - $ref: '#/components/parameters/NetworkQuery'
      responses:
        '200':
          description: Price comparison (includes status:"no_data" when both sources are null)
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompareResponse'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /v1/screener:
    get:
      operationId: screenPairs
      summary: Screen pairs by volume, change, liquidity and price
      security: []
      parameters:
        - name: volume
          in: query
          required: false
          schema:
            type: number
        - name: change_24h_min
          in: query
          required: false
          schema:
            type: number
        - name: change_24h_max
          in: query
          required: false
          schema:
            type: number
        - name: price_min
          in: query
          required: false
          schema:
            type: number
        - name: price_max
          in: query
          required: false
          schema:
            type: number
        - name: liquidity
          in: query
          required: false
          description: >-
            Filter for pairs with total AMM pool liquidity greater than or equal to this value.
            Liquidity is defined as the sum across all active AMM pools for the pair of
            (reserve_a * spot_price + reserve_b), valued in the quote asset (asset_b) at the
            latest snapshot spot price.
          schema:
            type: number
        - name: sortBy
          in: query
          required: false
          schema:
            type: string
            enum: [volume, change_24h, price, liquidity]
            default: volume
        - name: order
          in: query
          required: false
          schema:
            type: string
            enum: [asc, desc]
            default: desc
        - $ref: '#/components/parameters/CursorQuery'
        - name: limit
          in: query
          required: false
          description: Page size. Out-of-range values are clamped into [1, 100].
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - $ref: '#/components/parameters/NetworkQuery'
      responses:
        '200':
          description: Screened pairs
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScreenerResponse'
        '400':
          description: Invalid filter, sort or cursor
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          description: Internal server error

  /v1/movers:
    get:
      operationId: getMovers
      summary: Get biggest gainers, biggest losers, and volume movers
      description: >-
        Returns the top gainers, losers, and volume movers for the specified lookback window,
        annotated with venue provenance, sample counts, and single-venue move labelling.
      security: []
      parameters:
        - name: window
          in: query
          required: false
          schema:
            type: string
            enum: [1h, 24h, 7d]
            default: 24h
        - $ref: '#/components/parameters/NetworkQuery'
      responses:
        '200':
          description: Market movers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MoversResponse'
        '400':
          description: Invalid window or network
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          description: Internal server error

  /v1/benchmark/{asset}:
    get:
      operationId: getBenchmark
      summary: Get peg-deviation statistics for an asset against a target
      security: []
      parameters:
        - name: asset
          in: path
          required: true
          schema:
            type: string
          example: USDC
        - name: target
          in: query
          required: false
          schema:
            type: string
            default: USD
      responses:
        '200':
          description: Benchmark statistics
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenchmarkResponse'
        '404':
          description: Pair not watched
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          description: Benchmark computation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalErrorResponse'

  /v1/basket:
    get:
      operationId: getBasket
      summary: Compute the weighted price of a basket of assets
      description: >-
        Returns 200 even when one or more assets have no price data. The
        response body will contain an `error` field listing the missing assets
        and `reason: "missing_price_data"` rather than computing a partial
        basket price. A 404 would imply the assets themselves are invalid.
      security: []
      parameters:
        - name: asset
          in: query
          required: true
          description: Asset code; repeat for each basket member (at least two).
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          example: [XLM, USDC]
        - name: weight
          in: query
          required: true
          description: Relative weight for each `asset`, in the same order.
          schema:
            type: array
            items:
              type: number
          style: form
          explode: true
          example: [0.6, 0.4]
      responses:
        '200':
          description: Basket price or error with reason when price data is missing
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasketResponse'
        '400':
          description: Missing assets or mismatched/invalid weights
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /v1/correlation:
    get:
      operationId: getCorrelation
      summary: Compute price correlation matrix across a basket of assets over a window
      security: []
      parameters:
        - name: assets
          in: query
          required: true
          description: Comma-separated or repeated asset codes (at least two)
          schema:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
          example: XLM,USDC
        - name: window
          in: query
          required: false
          description: Lookback window (5m, 15m, 1h, 24h, 7d, 30d). Defaults to 24h.
          schema:
            type: string
            enum: [5m, 15m, 1h, 24h, 7d, 30d]
            default: 24h
        - $ref: '#/components/parameters/NetworkQuery'
      responses:
        '200':
          description: Correlation matrix and pair provenance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CorrelationResponse'
        '400':
          description: Missing or invalid parameters
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          description: Correlation computation failed

  /v1/discovery/resources:
    get:
      operationId: listDiscoveryResources
      summary: Browse the x402 Bazaar catalog of discoverable resources
      security: []
      parameters:
        - name: type
          in: query
          required: false
          schema:
            type: string
            enum: [http, mcp]
        - name: payTo
          in: query
          required: false
          schema:
            type: string
        - name: network
          in: query
          required: false
          description: >-
            Catalog filter matching the resource's payment network. Accepts
            either the Lens network name (`mainnet`/`testnet`) or the CAIP-2 id
            (`stellar:pubnet`/`stellar:testnet`).
          schema:
            type: string
        - name: extensions
          in: query
          required: false
          description: Filter to resources declaring this extension (e.g. `bazaar`).
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Paginated catalog page
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoveryResponse'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /v1/discovery/search:
    get:
      operationId: searchDiscoveryResources
      summary: Natural language search with ranking and quality evaluation for discoverable resources
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
            example: USDC
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
        - name: cursor
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Search results with relevance ranking and metadata quality
          content:
            application/json:
              schema:
                type: object
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /v1/webhooks:
    post:
      operationId: createWebhook
      summary: Subscribe to a price-threshold webhook
      description: >-
        Registers an HTTPS endpoint to be called when the pair's price crosses
        `threshold` in the given `direction`. The response contains the signing
        secret exactly once.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url, assetA, assetB, threshold, direction]
              properties:
                url:
                  type: string
                  format: uri
                  description: HTTPS endpoint to deliver events to.
                assetA:
                  type: string
                  example: XLM
                assetB:
                  type: string
                  example: USDC
                threshold:
                  type: number
                direction:
                  type: string
                  enum: [above, below]
      responses:
        '201':
          description: Webhook created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookCreatedResponse'
        '400':
          description: Invalid webhook definition
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /v1/webhooks/{id}:
    delete:
      operationId: deleteWebhook
      summary: Delete a webhook subscription
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Webhook deleted (idempotent — a missing id also returns 204)
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /v1/usage/me:
    get:
      operationId: getMyUsage
      summary: Get usage and quota for the calling API key
      security:
        - apiKeyAuth: []
      responses:
        '200':
          description: Usage summary for the authenticated key
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '401':
          description: Missing or invalid API key
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /v1/usage:
    get:
      operationId: getCallerUsage
      summary: Get usage and quota for the calling API key (alias for /usage/me)
      security:
        - apiKeyAuth: []
      responses:
        '200':
          description: Usage summary for the authenticated key
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '401':
          description: Missing or invalid API key
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /v1/supported:
    get:
      operationId: getSupported
      summary: List the payment kinds and extensions this facilitator supports
      security: []
      responses:
        '200':
          description: Supported payment kinds and extensions
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupportedResponse'

  /v1/verify:
    post:
      operationId: verifyPayment
      summary: Verify an x402 payment payload
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyRequest'
      responses:
        '200':
          description: Verification result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResponse'
        '400':
          description: Malformed request or invalid payment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResponse'
        '500':
          description: Internal verification error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResponse'

  /v1/settle:
    post:
      operationId: settlePayment
      summary: Settle an x402 payment (idempotent)
      description: >-
        Submits the payment transaction and records the attempt keyed on its
        transaction hash. Retrying the same payload replays the stored answer
        instead of paying twice.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SettleRequest'
      responses:
        '200':
          description: Settlement result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettleResponse'
        '400':
          description: Malformed payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettleResponse'

  /v1/graphql:
    get:
      operationId: graphqlGet
      summary: Execute a GraphQL query over HTTP GET
      security: []
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
        - name: variables
          in: query
          required: false
          description: JSON-encoded variables object.
          schema:
            type: string
        - name: operationName
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: GraphQL result
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphQlResponse'
    post:
      operationId: graphqlPost
      summary: Execute a GraphQL query, mutation or subscription handshake
      security:
        - x402: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [query]
              properties:
                query:
                  type: string
                variables:
                  type: object
                operationName:
                  type: string
      responses:
        '200':
          description: GraphQL result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphQlResponse'
        '402':
          $ref: '#/components/responses/PaymentRequired'

  /v1/rates:
    get:
      operationId: getLendingRates
      summary: Query latest lending and borrow rates across pools
      description: Returns the latest supply and borrow rates, utilisation, and reserves for lending markets.
      security: []
      parameters:
        - name: asset
          in: query
          required: false
          description: Filter by asset symbol (e.g. USDC, XLM)
          schema:
            type: string
        - name: poolId
          in: query
          required: false
          description: Filter by pool contract ID
          schema:
            type: string
        - name: network
          in: query
          required: false
          description: Stellar network to query (testnet or mainnet)
          schema:
            type: string
            enum: [testnet, mainnet]
        - name: limit
          in: query
          required: false
          description: Maximum number of rate records to return
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: Latest lending rates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LendingRatesResponse'
        '400':
          description: Invalid parameters
        '429':
          $ref: '#/components/responses/TooManyRequests'

components:
  securitySchemes:
    x402:
      type: apiKey
      name: X-PAYMENT
      in: header
      description: Base64 encoded JSON payment proof for x402 micropayments.
    adminAuth:
      type: apiKey
      name: X-Admin-Key
      in: header
    apiKeyAuth:
      type: http
      scheme: bearer
      description: >-
        Client API key issued through the admin API, sent as
        `Authorization: Bearer <key>`.

  parameters:
    DecimalFormatHeader:
      name: X-Decimal-Format
      in: header
      required: false
      description: >-
        Formatting for decimal quantities (prices, volumes, reserves).
        Set to `string` to serialize high-precision `Decimal(36,18)`
        quantities as exact strings, preventing IEEE-754 floating-point
        precision loss. Defaults to `number`. Can also be negotiated via
        `Accept: application/json; decimals=strings` or query parameter `?decimals=strings`.
      schema:
        type: string
        enum: [number, string]
        default: number

    NetworkQuery:
      name: network
      in: query
      required: false
      description: >-
        Stellar network to answer for — `testnet` or `mainnet`. Defaults to
        this instance's configured `STELLAR_NETWORK`. An unrecognised value is
        rejected with 400. DB-backed reads are currently served from whichever
        network this instance indexes, even when another is requested.
      schema:
        type: string
        enum: [testnet, mainnet]
        default: testnet
    CursorQuery:
      name: cursor
      in: query
      required: false
      description: >-
        Opaque cursor returned as `nextCursor` by the previous page. Every list
        route uses the same keyset-cursor convention: pass it unchanged to
        fetch the next page; rows inserted while paging never shift a page
        boundary. An invalid cursor is rejected with 400.
      schema:
        type: string

  responses:
    PaymentRequired:
      description: Payment Required
      content:
        application/json:
          schema:
            type: object
            properties:
              x402Version:
                type: integer
              accepts:
                type: array
                items:
                  type: object
                  properties:
                    scheme:
                      type: string
                    price:
                      type: string
                    network:
                      type: string
                    payTo:
                      type: string
              error:
                type: string
              description:
                type: string
    TooManyRequests:
      description: Rate limit exceeded
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: Remaining requests in current window
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
              error:
                type: string
              message:
                type: string
              retryAfter:
                type: string
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalErrorResponse'
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            type: object
            required: [error]
            properties:
              error:
                type: string

  headers:
    CacheControl:
      description: >-
        Per-route cache policy (see "Cache policy" in the API description).
        Every route sends a deliberate `Cache-Control`: live prices
        `public, max-age=30`; aggregates `public, max-age=60`; `/pairs` and
        `/pools` `public, max-age=300`; closed candle windows
        `public, max-age=86400`; per-caller, operator and error responses
        `no-store`.
      schema:
        type: string
        example: 'public, max-age=300'

  schemas:
    LendingRateEntry:
      type: object
      required: [id, venue, source, network, poolId, asset, supplyApy, borrowApy, timestamp]
      properties:
        id:
          type: string
        venue:
          type: string
          example: blend
        source:
          type: string
          example: blend
        network:
          type: string
          example: mainnet
        poolId:
          type: string
        poolName:
          type: string
          nullable: true
        asset:
          type: string
          example: USDC
        assetAddress:
          type: string
          nullable: true
        supplyApy:
          type: number
        borrowApy:
          type: number
        supplyApr:
          type: number
          nullable: true
        borrowApr:
          type: number
          nullable: true
        utilization:
          type: number
          nullable: true
          description: Borrowed / supplied as a fraction. Null for venues that publish rates only.
        totalSupply:
          type: number
          nullable: true
        totalBorrowed:
          type: number
          nullable: true
        reserves:
          type: number
          nullable: true
        ledger:
          type: integer
        timestamp:
          type: string
          format: date-time

    LendingRatesResponse:
      type: object
      required: [network, rates]
      properties:
        network:
          type: string
        rates:
          type: array
          items:
            $ref: '#/components/schemas/LendingRateEntry'

    InternalErrorResponse:
      type: object
      required: [code, message, correlationId]
      properties:
        code:
          type: string
          enum: [internal_error]
          example: internal_error
        message:
          type: string
          example: An internal server error occurred.
        correlationId:
          type: string
          example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d

    DependencyCheck:
      type: object
      description: >-
        Result of one dependency probe. `reason` is a fixed phrase, never the
        raw error: connection errors carry the host and port and this is a
        public endpoint.
      required: [status, latencyMs, reason]
      properties:
        status:
          type: string
          enum: [up, down, skipped]
        latencyMs:
          type: integer
          description: Round-trip time of the probe.
        reason:
          type: string
          nullable: true
          example: unreachable or not migrated

    VenuesResponse:
      type: object
      required: [network, window, excludedVenues, venues, totalVolume, marketShares, periodOverPeriodPctChange]
      additionalProperties: false
      properties:
        network:
          type: string
          enum: [testnet, mainnet]
        window:
          type: string
          enum: [24h, 7d, 30d]
        excludedVenues:
          type: array
          items:
            type: string
        venues:
          type: array
          items:
            type: object
            required: [venue, baseVolume, counterVolume, samples, pairs, marketShare, periodOverPeriodPctChange, lastUpdated, ageSeconds]
            additionalProperties: false
            properties:
              venue:
                type: string
              baseVolume:
                type: number
              counterVolume:
                type: number
              samples:
                type: integer
              pairs:
                type: integer
              marketShare:
                type: number
              periodOverPeriodPctChange:
                type: number
              lastUpdated:
                type: [string, 'null']
              ageSeconds:
                type: [integer, 'null']
        totalVolume:
          type: object
          required: [value, unit, reason]
          additionalProperties: false
          properties:
            value:
              type: [number, 'null']
            unit:
              type: [object, 'null']
            reason:
              type: [string, 'null']
        marketShares:
          type: object
          additionalProperties: false
          properties:
            total:
              type: number
            variance:
              type: number
        periodOverPeriodPctChange:
          type: number

    ReadinessReport:
      type: object
      description: >-
        Readiness of one instance. Identical on 200 and 503; `ok` and the HTTP
        status together say whether traffic should be routed here.
      required: [ok, booted, checks, checkedAt]
      properties:
        ok:
          type: boolean
          description: True only when boot finished and every checked dependency is up.
        booted:
          type: boolean
          description: False while the boot sequence is still running.
        checks:
          type: object
          required: [postgres, redis]
          properties:
            postgres:
              $ref: '#/components/schemas/DependencyCheck'
            redis:
              $ref: '#/components/schemas/DependencyCheck'
        checkedAt:
          type: string
          format: date-time
          description: When the underlying probes ran (answers may be briefly cached).

    Asset:
      type: object
      properties:
        code:
          type: string
        issuer:
          type: string
          nullable: true

    SnapshotAsset:
      type: object
      description: >-
        A Stellar asset. The issuer is kept because a code such as USDC names a
        different asset per issuer; `issuer` is null only for the native asset.
      properties:
        code:
          type: string
        issuer:
          type: string
          nullable: true

    SnapshotVenue:
      type: object
      properties:
        name:
          type: string
        source:
          type: string
        type:
          type: string
          enum: [orderbook, amm, unknown]
        enabled:
          type: boolean
          nullable: true
        status:
          type: string
          enum: [reporting, stale, silent, disabled]
        samples:
          type: integer
        samples24h:
          type: integer
        pairs24h:
          type: integer
        lastUpdated:
          type: string
          format: date-time
          nullable: true
        ageSeconds:
          type: integer
          nullable: true

    SnapshotPool:
      type: object
      properties:
        poolId:
          type: string
        pairKey:
          type: string
          nullable: true
        assetA:
          $ref: '#/components/schemas/SnapshotAsset'
        assetB:
          $ref: '#/components/schemas/SnapshotAsset'
        reserveA:
          type: number
          nullable: true
        reserveB:
          type: number
          nullable: true
        spotPrice:
          type: number
          nullable: true
        feeBp:
          type: integer
          nullable: true
        lastUpdated:
          type: string
          format: date-time
          nullable: true
        ageSeconds:
          type: integer
          nullable: true

    SnapshotVolume:
      type: object
      properties:
        value:
          type: number
          nullable: true
        unit:
          allOf:
            - $ref: '#/components/schemas/SnapshotAsset'
          nullable: true
        reason:
          type: string
          nullable: true

    SnapshotTopPair:
      type: object
      properties:
        pairKey:
          type: string
        configured:
          type: boolean
          description: >-
            Whether the pair is in this network's watched-pair config. When
            false the asset order (and therefore the price direction) is taken
            from the alphabetically-sorted pair key.
        assetA:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/SnapshotAsset'
        assetB:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/SnapshotAsset'
        price:
          type: number
          nullable: true
          description: Stored as assetB-per-assetA in the config's order.
        baseVolume24h:
          type: number
        counterVolume24h:
          type: number
        samples24h:
          type: integer
        venues:
          type: array
          items:
            type: string
        lastUpdated:
          type: string
          format: date-time
          nullable: true
        ageSeconds:
          type: integer
          nullable: true

    SnapshotPeg:
      type: object
      properties:
        asset:
          $ref: '#/components/schemas/SnapshotAsset'
        target:
          type: string
        pairKey:
          type: string
        quote:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/SnapshotAsset'
        price:
          type: number
          nullable: true
          description: The pegged asset's price in its quote asset.
        deviationBp:
          type: number
          nullable: true
        status:
          type: string
          enum: [on_peg, off_peg, no_reference, no_data]
        reason:
          type: string
          nullable: true
        samples24h:
          type: integer
        lastUpdated:
          type: string
          format: date-time
          nullable: true

    SnapshotResponse:
      type: object
      properties:
        network:
          type: string
          enum: [testnet, mainnet]
        asOf:
          type: string
          format: date-time
          description: The single instant (from one database statement) every window and age is measured from.
        generatedAt:
          type: string
          format: date-time
        window:
          type: string
          enum: ['24h']
        cache:
          type: object
          properties:
            ttlSeconds:
              type: integer
            maxAgeSeconds:
              type: integer
            hit:
              type: boolean
            storedAt:
              type: string
              format: date-time
            ageSeconds:
              type: integer
              nullable: true
        venues:
          type: array
          items:
            $ref: '#/components/schemas/SnapshotVenue'
        tvl:
          type: object
          properties:
            note:
              type: string
            poolCount:
              type: integer
            sampleCount:
              type: integer
            lastUpdated:
              type: string
              format: date-time
              nullable: true
            ageSeconds:
              type: integer
              nullable: true
            stale:
              type: boolean
            byAsset:
              type: array
              items:
                type: object
                properties:
                  asset:
                    $ref: '#/components/schemas/SnapshotAsset'
                  amount:
                    type: number
                  pools:
                    type: integer
            pools:
              type: array
              items:
                $ref: '#/components/schemas/SnapshotPool'
        volume24h:
          type: object
          properties:
            window:
              type: string
              enum: ['24h']
            sampleCount:
              type: integer
            byVenue:
              type: array
              items:
                type: object
                properties:
                  venue:
                    type: string
                  baseVolume:
                    type: number
                  counterVolume:
                    type: number
                  samples:
                    type: integer
                  pairs:
                    type: integer
                  lastUpdated:
                    type: string
                    format: date-time
                    nullable: true
                  ageSeconds:
                    type: integer
                    nullable: true
            total:
              $ref: '#/components/schemas/SnapshotVolume'
        topPairs:
          type: array
          items:
            $ref: '#/components/schemas/SnapshotTopPair'
        pegs:
          type: array
          items:
            $ref: '#/components/schemas/SnapshotPeg'
        freshness:
          type: object
          properties:
            asOf:
              type: string
              format: date-time
            windowStart:
              type: string
              format: date-time
            windowEnd:
              type: string
              format: date-time
            lastUpdated:
              type: string
              format: date-time
              nullable: true
            ageSeconds:
              type: integer
              nullable: true
            staleAfterSeconds:
              type: integer
            stale:
              type: boolean
            venuesReporting:
              type: integer
            venuesExpected:
              type: integer
            venuesSilent:
              type: integer

    AggregatedPrice:
      type: object
      properties:
        assetA:
          type: string
        assetB:
          type: string
        pairKey:
          type: string
        price:
          oneOf:
            - type: number
            - type: string
        sdexPrice:
          oneOf:
            - type: number
            - type: string
        ammPrice:
          oneOf:
            - type: number
            - type: string
        bestRoute:
          type: string
          enum: [SDEX, AMM, SPLIT, UNKNOWN]
        volume24h:
          oneOf:
            - type: number
            - type: string
        sdexVolume24h:
          oneOf:
            - type: number
            - type: string
        ammVolume24h:
          oneOf:
            - type: number
            - type: string
        vwap1m:
          oneOf:
            - type: number
            - type: string
        vwap5m:
          oneOf:
            - type: number
            - type: string
        vwap1h:
          oneOf:
            - type: number
            - type: string
        vwap24h:
          oneOf:
            - type: number
            - type: string
        priceChange24h:
          oneOf:
            - type: number
            - type: string
        lastUpdated:
          type: string
          format: date-time
        sources:
          type: integer
        confidence:
          type: string
          enum: [high, medium, low, unknown]
        lastTradeAgeSeconds:
          type: integer
          nullable: true

    RouteHop:
      type: object
      required: [assetIn, assetOut, venue, inputAmount, outputAmount, price, spotPrice, slippagePct]
      properties:
        assetIn:
          $ref: '#/components/schemas/Asset'
        assetOut:
          $ref: '#/components/schemas/Asset'
        venue:
          type: string
          enum: [SDEX, AMM]
        poolId:
          type: string
        inputAmount:
          type: number
        outputAmount:
          type: number
        price:
          type: number
        spotPrice:
          type: number
        slippagePct:
          type: number

    RouteOption:
      type: object
      required: [hops, hopCount, estimatedOutput, effectivePrice, slippagePct]
      properties:
        hops:
          type: array
          items:
            $ref: '#/components/schemas/RouteHop'
        hopCount:
          type: integer
        estimatedOutput:
          type: number
        effectivePrice:
          type: number
        slippagePct:
          type: number

    RouteComparison:
      type: object
      required: [direct, multiHop]
      properties:
        direct:
          type: object
          required: [route, sdexPrice, ammPrice, estimatedOutput, slippagePct]
          properties:
            route:
              type: string
              enum: [SDEX, AMM, SPLIT, UNKNOWN]
            sdexPrice:
              type: number
            ammPrice:
              type: number
            estimatedOutput:
              type: number
            slippagePct:
              type: number
        multiHop:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/RouteOption'

    RouteProvenance:
      type: object
      required: [sampledAt, network, venuesQueried, sampleCount, freshnessSeconds]
      properties:
        sampledAt:
          type: string
          format: date-time
        network:
          type: string
        venuesQueried:
          type: array
          items:
            type: string
        sampleCount:
          type: integer
        freshnessSeconds:
          type: number
          nullable: true

    RouteInfo:
      type: object
      required: [route, sdexPrice, ammPrice, estimatedOutput, slippagePct, recommendation]
      properties:
        route:
          type: string
          enum: [SDEX, AMM, SPLIT, MULTI_HOP, UNKNOWN]
        sdexPrice:
          oneOf:
            - type: number
            - type: string
        ammPrice:
          oneOf:
            - type: number
            - type: string
        estimatedOutput:
          oneOf:
            - type: number
            - type: string
        slippagePct:
          oneOf:
            - type: number
            - type: string
        recommendation:
          type: string
        network:
          type: string
          enum: [testnet, mainnet]
        hops:
          type: array
          items:
            $ref: '#/components/schemas/RouteHop'
        comparison:
          $ref: '#/components/schemas/RouteComparison'
        provenance:
          $ref: '#/components/schemas/RouteProvenance'

    PriceBucket:
      type: object
      properties:
        bucket:
          type: string
          format: date-time
        window:
          type: string
        vwap:
          oneOf:
            - type: number
            - type: string
        sdexVwap:
          oneOf:
            - type: number
            - type: string
          nullable: true
        ammVwap:
          oneOf:
            - type: number
            - type: string
          nullable: true
        volume:
          oneOf:
            - type: number
            - type: string
        tradeCount:
          type: integer
        open:
          oneOf:
            - type: number
            - type: string
          nullable: true
        close:
          oneOf:
            - type: number
            - type: string
          nullable: true
        high:
          oneOf:
            - type: number
            - type: string
          nullable: true
        low:
          oneOf:
            - type: number
            - type: string
          nullable: true

    PriceLevel:
      type: object
      required: [price, size]
      additionalProperties: false
      properties:
        price:
          oneOf:
            - type: number
            - type: string
        size:
          oneOf:
            - type: number
            - type: string

    DepthResponse:
      type: object
      required: [assetA, assetB, pairKey, spotPrice, executionPrice, slippagePct, asks, bids, source]
      additionalProperties: false
      properties:
        assetA:
          type: string
        assetB:
          type: string
        pairKey:
          type: string
        spotPrice:
          oneOf:
            - type: number
            - type: string
        executionPrice:
          oneOf:
            - type: number
            - type: string
        slippagePct:
          oneOf:
            - type: number
            - type: string
        asks:
          type: array
          items:
            $ref: '#/components/schemas/PriceLevel'
        bids:
          type: array
          items:
            $ref: '#/components/schemas/PriceLevel'
        source:
          type: string
          enum: [AMM, SDEX, BOTH]

    BookLevel:
      type: object
      required: [price, size, cumulativeSize, venues, synthetic, sampleCount]
      additionalProperties: false
      properties:
        price:
          oneOf:
            - type: number
            - type: string
          description: Quote-asset units per base-asset unit.
        size:
          oneOf:
            - type: number
            - type: string
          description: Base-asset size at this level.
        cumulativeSize:
          oneOf:
            - type: number
            - type: string
          description: Base-asset size from the best price through this level, independently for asks and bids.
        venues:
          type: array
          items:
            type: string
          description: SDEX for order-book levels or AMM:{poolId} for each contributing pool.
        synthetic:
          type: boolean
          description: True for reserve-derived AMM steps; false for observed SDEX book levels.
        sampleCount:
          type: integer
          description: Number of source levels combined at this price.

    BookSource:
      type: object
      required: [venue, status, sampleCount, observedAt, dataAgeSeconds, truncated]
      additionalProperties: false
      properties:
        venue:
          type: string
        status:
          type: string
          enum: [available, no_liquidity, unavailable]
        sampleCount:
          type: integer
          description: SDEX book levels returned, or latest AMM pool snapshots used.
        observedAt:
          type: string
          format: date-time
          nullable: true
        dataAgeSeconds:
          type: number
          nullable: true
        truncated:
          type: boolean
          description: True when the SDEX response reached the 200-level per-side request limit.

    BookResponse:
      type: object
      required: [assetA, assetB, pairKey, network, spotPrice, spotSource, depth, step, status, asks, bids, provenance]
      additionalProperties: false
      properties:
        assetA:
          type: string
        assetB:
          type: string
        pairKey:
          type: string
        network:
          type: string
          enum: [testnet, mainnet]
        spotPrice:
          type: number
          nullable: true
        spotSource:
          type: string
          nullable: true
          enum: [SDEX_MID, SDEX_ASK, SDEX_BID, AMM_RESERVES, null]
        depth:
          type: number
        step:
          type: number
        status:
          type: string
          enum: [ok, partial, no_liquidity, no_levels_in_range, unavailable]
        asks:
          type: array
          items:
            $ref: '#/components/schemas/BookLevel'
        bids:
          type: array
          items:
            $ref: '#/components/schemas/BookLevel'
        provenance:
          type: object
          required: [sampledAt, sampleCount, venues]
          additionalProperties: false
          properties:
            sampledAt:
              type: string
              format: date-time
            sampleCount:
              type: integer
            venues:
              type: array
              items:
                $ref: '#/components/schemas/BookSource'

    ImpactResponse:
      type: object
      required: [assetA, assetB, pairKey, status, spotPrice, availableLiquidity, smallestSize, ladder, thresholds, source]
      additionalProperties: false
      properties:
        assetA:
          type: string
        assetB:
          type: string
        pairKey:
          type: string
        status:
          type: string
          enum: [ok, insufficient_liquidity]
        spotPrice:
          type: number
        availableLiquidity:
          type: number
        smallestSize:
          type: number
        ladder:
          type: array
          items:
            type: object
            required: [size, output, executionPrice, slippagePct]
            additionalProperties: false
            properties:
              size:
                type: number
              output:
                type: number
              executionPrice:
                type: number
              slippagePct:
                type: number
        thresholds:
          type: array
          items:
            type: object
            required: [thresholdPct, crossed, size]
            additionalProperties: false
            properties:
              thresholdPct:
                type: number
              crossed:
                type: boolean
              size:
                type: number
                nullable: true
        source:
          type: string
          enum: [AMM]

    TwapResponse:
      type: object
      required: [assetA, assetB, pairKey, network, twap, windowMinutes, sampleIntervalSeconds, startTime, endTime, sampleCount, outlierRejected, filterMethod]
      additionalProperties: false
      properties:
        assetA:
          type: string
        assetB:
          type: string
        pairKey:
          type: string
        network:
          type: string
          enum: [testnet, mainnet]
        twap:
          oneOf:
            - type: number
            - type: string
        windowMinutes:
          type: integer
        sampleIntervalSeconds:
          type: integer
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        sampleCount:
          type: integer
        outlierRejected:
          type: integer
        filterMethod:
          type: string
          enum: [iqr, modified_zscore]

    VwapResponse:
      type: object
      required: [assetA, assetB, pairKey, network, vwap, windowMinutes, source, startTime, endTime, sampleCount, volumeTotal, outlierRejected, filterMethod]
      additionalProperties: false
      properties:
        assetA:
          type: string
        assetB:
          type: string
        pairKey:
          type: string
        network:
          type: string
          enum: [testnet, mainnet]
        vwap:
          oneOf:
            - type: number
            - type: string
        windowMinutes:
          type: integer
        source:
          type: string
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        sampleCount:
          type: integer
        volumeTotal:
          oneOf:
            - type: number
            - type: string
        outlierRejected:
          type: integer
        filterMethod:
          type: string
          enum: [iqr, modified_zscore]

    VolumeTotals:
      type: object
      required: [net, gross]
      additionalProperties: false
      properties:
        net:
          type: number
          description: Volume summed across primary markets only (excluding aggregator double-counts)
        gross:
          type: number
          description: Gross volume summed across all venues including aggregators

    VolumeResponse:
      type: object
      required:
        - asset
        - network
        - window
        - startTime
        - endTime
        - totalVolume
        - netVolume
        - grossVolume
        - totals
        - byVenue
        - venues
        - tradeCount
        - netTradeCount
        - grossTradeCount
        - medianTradeSize
        - topTradeVolumeShare
        - volumeConcentration
        - concentrationMeasure
        - status
        - provenance
      additionalProperties: false
      properties:
        asset:
          type: string
        network:
          type: string
          enum: [testnet, mainnet]
        window:
          type: string
          enum: [24h, 7d, 30d]
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        totals:
          $ref: '#/components/schemas/VolumeTotals'
        netVolume:
          type: number
          description: Volume summed across primary markets only (excluding aggregator double-counts)
        grossVolume:
          type: number
          description: Gross volume summed across all venues including aggregators
        totalVolume:
          type: number
          description: Primary volume total (alias for netVolume for backward compatibility)
        byVenue:
          type: object
          additionalProperties:
            type: number
        venues:
          type: array
          items:
            type: string
        tradeCount:
          type: integer
          description: Number of positive-volume samples from primary markets (equals netTradeCount).
        netTradeCount:
          type: integer
          description: Number of positive-volume samples from primary markets.
        grossTradeCount:
          type: integer
          description: Number of positive-volume samples across all venues, including aggregators.
        medianTradeSize:
          type: number
          nullable: true
          description: Median per-sample volume measured in the requested asset's units.
        topTradeVolumeShare:
          type: number
          nullable: true
          description: Largest single sample's share of total volume, from 0 to 1.
        volumeConcentration:
          type: number
          nullable: true
          description: HHI, the sum of squared per-sample volume shares; 1 is fully concentrated in one sample.
        concentrationMeasure:
          type: string
          enum: [hhi]
        status:
          type: string
          enum: [ok, no_trades, no_positive_volume]
        provenance:
          type: object
          required: [venues, sampleCount, observedSampleCount, latestTradeAt, dataAgeSeconds]
          additionalProperties: false
          properties:
            venues:
              type: array
              items:
                type: string
            sampleCount:
              type: integer
              description: Positive-volume samples used to calculate trade-size statistics.
            observedSampleCount:
              type: integer
              description: All matching price point samples observed in the window, including zero-volume samples.
            latestTradeAt:
              type: string
              format: date-time
              nullable: true
            dataAgeSeconds:
              type: integer
              nullable: true

    SpreadVenue:
      type: object
      required: [venue, pairKey, bid, ask, mid, spreadBps, observations, lastSeen]
      additionalProperties: false
      properties:
        venue:
          type: string
        pairKey:
          type: string
        bid:
          type: number
        ask:
          type: number
        mid:
          type: number
        spreadBps:
          type: number
        observations:
          type: integer
        lastSeen:
          type: string
          format: date-time

    SpreadResponse:
      type: object
      required: [asset, network, window, startTime, endTime, venues, tightest]
      additionalProperties: false
      properties:
        asset:
          type: string
        network:
          type: string
          enum: [testnet, mainnet]
        window:
          type: string
          enum: [5m, 15m, 1h, 24h]
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        venues:
          type: array
          items:
            $ref: '#/components/schemas/SpreadVenue'
        tightest:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/SpreadVenue'

    RateVenue:
      type: object
      required: [venue, source, pool, poolName, supplyRate, borrowRate, ledger, updatedAt]
      additionalProperties: false
      properties:
        venue:
          type: string
          description: Lending venue the rate was read from (e.g. "blend").
        source:
          type: string
          description: Distinct source tag stored on the row.
        pool:
          type: string
          description: Pool / market contract id the rate came from, never elided.
        poolName:
          type: string
          nullable: true
          description: Human-readable pool name, when the venue publishes one.
        supplyRate:
          type: number
          description: APY earned by supplying the asset, as a fraction (0.05 == 5%).
        borrowRate:
          type: number
          description: APY charged to borrow the asset, as a fraction (0.07 == 7%).
        ledger:
          type: integer
        updatedAt:
          type: string
          format: date-time

    RatesResponse:
      type: object
      required: [asset, network, venues, best, count, computedAt]
      additionalProperties: false
      properties:
        asset:
          type: string
        network:
          type: string
          enum: [testnet, mainnet]
        venues:
          type: array
          description: >-
            One entry per venue, sorted best-first (highest supply rate). Empty
            when no venue lists the asset.
          items:
            $ref: '#/components/schemas/RateVenue'
        best:
          nullable: true
          description: The highest-supply venue, or null when nothing lends the asset.
          allOf:
            - $ref: '#/components/schemas/RateVenue'
        count:
          type: integer
        computedAt:
          type: string
          format: date-time

    CompareResponse:
      type: object
      required: [asset, network, lens, reflector, deviationPct, status, fetchedAt, oracles]
      additionalProperties: false
      properties:
        asset:
          type: string
        network:
          type: string
          enum: [testnet, mainnet]
        lens:
          type: number
          nullable: true
        reflector:
          type: number
          nullable: true
        deviationPct:
          type: number
          nullable: true
        status:
          type: string
          enum: [aligned, minor_deviation, major_deviation, partial]
        fetchedAt:
          type: string
          format: date-time
        oracles:
          type: array
          description: One result per configured adapter; unavailable sources remain present with a status.
          items:
            type: object
            required: [name, price, timestamp, deviationPct, status, ageSeconds]
            additionalProperties: false
            properties:
              name:
                type: string
              price:
                type: number
                nullable: true
              timestamp:
                type: string
                format: date-time
                nullable: true
              deviationPct:
                type: number
                nullable: true
              status:
                type: string
                description: unreachable means the adapter failed; empty means it is configured but returned no quote.
                enum: [available, unreachable, empty, not_configured]
              ageSeconds:
                type: integer
                nullable: true

    ScreenerRow:
      type: object
      additionalProperties: true
      properties:
        pair_key:
          type: string
        volume:
          type: number
        price:
          type: number
        change_24h:
          type: number
        liquidity:
          type: number
          description: >-
            Total liquidity across all active AMM pools for this pair on the network,
            computed as sum(reserve_a * spot_price + reserve_b), valued in the quote
            asset (asset_b) at each pool's latest snapshot spot price.
        liquidity_unit:
          type: string
          description: >-
            The asset symbol/identifier that liquidity is denominated in, corresponding
            to the counter/quote asset (asset_b) of the pair (the asset after the slash in pair_key).

    ScreenerResponse:
      type: object
      required: [data, nextCursor, hasMore, total]
      additionalProperties: false
      properties:
        network:
          type: string
          enum: [testnet, mainnet]
          description: The network answered for.
        data:
          type: array
          items:
            $ref: '#/components/schemas/ScreenerRow'
        nextCursor:
          type: string
          nullable: true
        hasMore:
          type: boolean
        total:
          type: integer
          nullable: true

    MoverItem:
      type: object
      required: [pairKey, assetA, assetB, priceChangePct, startPrice, endPrice, currentVolume, previousVolume, volumeChangePct, venues, isSingleVenue, sampleCount, lastUpdated]
      additionalProperties: false
      properties:
        pairKey:
          type: string
        assetA:
          type: string
        assetB:
          type: string
        priceChangePct:
          type: number
          nullable: true
        startPrice:
          type: number
          nullable: true
        endPrice:
          type: number
          nullable: true
        currentVolume:
          type: number
        previousVolume:
          type: number
        volumeChangePct:
          type: number
          nullable: true
        venues:
          type: array
          items:
            type: string
        isSingleVenue:
          type: boolean
        sampleCount:
          type: integer
        lastUpdated:
          type: string
          format: date-time
          nullable: true

    MoversResponse:
      type: object
      required: [network, window, startTime, endTime, gainers, losers, volumeMovers]
      additionalProperties: false
      properties:
        network:
          type: string
          enum: [testnet, mainnet]
        window:
          type: string
          enum: [1h, 24h, 7d]
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        gainers:
          type: array
          items:
            $ref: '#/components/schemas/MoverItem'
        losers:
          type: array
          items:
            $ref: '#/components/schemas/MoverItem'
        volumeMovers:
          type: array
          items:
            $ref: '#/components/schemas/MoverItem'

    BenchmarkResponse:
      type: object
      required: [asset, target, pairKey, currentPrice, currentDeviationBp, rolling24h]
      additionalProperties: false
      properties:
        asset:
          type: string
        target:
          type: string
        pairKey:
          type: string
        currentPrice:
          type: number
          nullable: true
        currentDeviationBp:
          type: number
          nullable: true
        rolling24h:
          type: object
          required: [maxDeviationBp, minDeviationBp, maxAbsoluteDeviationBp, averageDeviationBp, sampleCount]
          additionalProperties: false
          properties:
            maxDeviationBp:
              type: number
              nullable: true
            minDeviationBp:
              type: number
              nullable: true
            maxAbsoluteDeviationBp:
              type: number
              nullable: true
            averageDeviationBp:
              type: number
              nullable: true
            sampleCount:
              type: integer

    BasketResponse:
      type: object
      required: [basketPrice, components, weightSum, computedAt]
      additionalProperties: false
      properties:
        basketPrice:
          type: number
        components:
          type: array
          items:
            type: object
            required: [asset, price, weight, contribution]
            additionalProperties: false
            properties:
              asset:
                type: string
              price:
                type: number
              weight:
                type: number
              contribution:
                type: number
        weightSum:
          type: number
        computedAt:
          type: string
          format: date-time

    CorrelationResponse:
      type: object
      required: [network, window, startTime, endTime, assets, matrix, sampleCounts, pairs]
      additionalProperties: false
      properties:
        network:
          type: string
          enum: [testnet, mainnet]
        window:
          type: string
          enum: [5m, 15m, 1h, 24h, 7d, 30d]
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        assets:
          type: array
          items:
            type: string
        matrix:
          type: object
          description: Symmetric correlation matrix keyed by asset pair
          additionalProperties:
            type: object
            additionalProperties:
              type: number
              nullable: true
        sampleCounts:
          type: object
          description: Overlapping sample count per pair
          additionalProperties:
            type: object
            additionalProperties:
              type: integer
        pairs:
          type: array
          items:
            $ref: '#/components/schemas/CorrelationCell'

    CorrelationCell:
      type: object
      required: [assetA, assetB, coefficient, status, sampleCount, provenance]
      additionalProperties: false
      properties:
        assetA:
          type: string
        assetB:
          type: string
        coefficient:
          type: number
          nullable: true
          description: Pearson correlation coefficient between -1 and 1, or null if insufficient
        status:
          type: string
          enum: [computed, insufficient]
        sampleCount:
          type: integer
        provenance:
          type: object
          required: [sampleCount, venues, oldestSample, newestSample]
          additionalProperties: false
          properties:
            sampleCount:
              type: integer
            venues:
              type: array
              items:
                type: string
            oldestSample:
              type: string
              format: date-time
              nullable: true
            newestSample:
              type: string
              format: date-time
              nullable: true

    DiscoveryResource:
      type: object
      properties:
        resource:
          type: object
          additionalProperties: true
          properties:
            url:
              type: string
            description:
              type: string
            mimeType:
              type: string
            serviceName:
              type: string
            tags:
              type: array
              items:
                type: string
            iconUrl:
              type: string
        accepts:
          type: array
          items:
            type: object
            properties:
              scheme:
                type: string
              price:
                type: string
              network:
                type: string
              payTo:
                type: string
        extensions:
          type: object
          additionalProperties: true

    DiscoveryResponse:
      type: object
      required: [resources, limit, offset, total]
      additionalProperties: false
      properties:
        resources:
          type: array
          items:
            $ref: '#/components/schemas/DiscoveryResource'
        limit:
          type: integer
        offset:
          type: integer
        total:
          type: integer

    WebhookCreatedResponse:
      type: object
      required: [id, secret]
      additionalProperties: false
      properties:
        id:
          type: string
        secret:
          type: string

    UsageResponse:
      type: object
      required: [keyId, dailyCalls, dailyCents, monthlyCalls, monthlyCents, dailyQuotaCents, monthlyQuotaCents, dailyRemainingCents, monthlyRemainingCents, overagePolicy, quotaExceeded]
      additionalProperties: false
      properties:
        keyId:
          type: string
        dailyCalls:
          type: integer
        dailyCents:
          type: integer
        monthlyCalls:
          type: integer
        monthlyCents:
          type: integer
        dailyQuotaCents:
          type: integer
        monthlyQuotaCents:
          type: integer
        dailyRemainingCents:
          type: integer
        monthlyRemainingCents:
          type: integer
        overagePolicy:
          type: string
          enum: [block, charge_402, allow_overage]
        quotaExceeded:
          type: boolean
        dailyResetsAt:
          type: string
        monthlyResetsAt:
          type: string
        resets:
          type: object
          properties:
            daily:
              type: string
            monthly:
              type: string
        resetsInSeconds:
          type: object
          properties:
            daily:
              type: integer
            monthly:
              type: integer

    VerifyRequest:
      type: object
      required: [paymentPayload, paymentRequirements]
      properties:
        x402Version:
          type: integer
        paymentPayload:
          type: object
        paymentRequirements:
          type: object

    VerifyResponse:
      type: object
      required: [isValid]
      additionalProperties: true
      properties:
        isValid:
          type: boolean
        invalidReason:
          type: string
          nullable: true
        invalidMessage:
          type: string
          nullable: true
        payer:
          type: string
          nullable: true

    SettleRequest:
      type: object
      required: [paymentPayload, paymentRequirements]
      properties:
        x402Version:
          type: integer
        paymentPayload:
          type: object
        paymentRequirements:
          type: object

    SettleResponse:
      type: object
      required: [success, transaction, network]
      additionalProperties: true
      properties:
        success:
          type: boolean
        errorReason:
          type: string
          nullable: true
        errorMessage:
          type: string
          nullable: true
        transaction:
          type: string
        network:
          type: string

    SupportedResponse:
      type: object
      additionalProperties: true
      properties:
        kinds:
          type: array
          items:
            type: object
            properties:
              scheme:
                type: string
              network:
                type: string
        extensions:
          type: array
          items:
            type: string

    GraphQlResponse:
      type: object
      additionalProperties: true
      properties:
        data:
          type: object
          nullable: true
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string