openapi.yaml

openapi: 3.0.3

info:
  title: StellarRoute API
  version: 0.1.0
  description: |
    REST API for DEX aggregation on the Stellar Network.

    StellarRoute aggregates liquidity from Stellar's SDEX (Stellar Distributed
    Exchange) and Soroban AMM pools to find the best available price for any
    token pair.

    ## Asset identifiers

    Assets are encoded in path segments using one of three formats:

    | Format | Example | Meaning |
    |--------|---------|---------|
    | `native` | `native` | XLM (Stellar's native asset) |
    | `CODE` | `USDC` | Issued asset — code only (omits issuer) |
    | `CODE:ISSUER` | `USDC:GA5ZSEJ...` | Issued asset — fully qualified |

    ## Error handling

    All errors return a JSON body with `error` (machine-readable code) and
    `message` (human-readable description).  See the `ErrorResponse` schema
    and the **Error codes** section below for the full list.

    ## Rate limiting

    Endpoints are rate-limited per IP address.  When the limit is exceeded the
    API returns **429 Too Many Requests** with `X-RateLimit-*` headers.

    ## Request correlation

    Clients may optionally send `X-Request-ID` with any request. The API will
    reuse that value, or generate a UUID when the header is omitted, and echo
    the final request ID back in the `X-Request-ID` response header.

    ## Versioning and deprecation

    `/api/v1/*` is in deprecation mode. Responses from v1 routes include
    `Deprecation`, `Sunset`, and `Link` headers. Breaking removals require a
    notice period and migration guidance.
  contact:
    name: StellarRoute
    url: https://github.com/stellarroute/stellarroute
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:3000
    description: Local development server
  - url: https://api.stellarroute.io
    description: Production server (future)

tags:
  - name: health
    description: Service health and readiness probes
  - name: assets
    description: Asset metadata — decimals, issuer labels, and trustline hints
  - name: activity
    description: Indexed on-chain contract swap activity
  - name: trading
    description: Market data — trading pairs, orderbooks, and price quotes

paths:
  /health:
    get:
      operationId: health_check
      summary: Service health check
      description: |
        Probes PostgreSQL and Redis (when configured) and returns a per-component
        status map.

        Returns **200 OK** when all required dependencies are healthy.
        Returns **503 Service Unavailable** when any required dependency is down.
      tags:
        - health
      responses:
        "200":
          description: All dependencies healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
              example:
                status: healthy
                timestamp: "2026-02-23T12:00:00Z"
                version: "0.1.0"
                components:
                  database: healthy
                  redis: healthy
                  horizon: healthy
                  soroban_rpc: healthy
        "503":
          description: One or more dependencies unhealthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
              example:
                status: unhealthy
                timestamp: "2026-02-23T12:00:00Z"
                version: "0.1.0"
                components:
                  database: degraded
                  redis: healthy
                  horizon: degraded
                  soroban_rpc: healthy

  /health/deps:
    get:
      operationId: dependency_health
      summary: Dependency readiness check
      description: |
        Returns per-dependency readiness status for infrastructure and external
        providers (PostgreSQL, Redis, Horizon, Soroban RPC).

        Returns **200 OK** when dependencies are healthy.
        Returns **503 Service Unavailable** when one or more are degraded.
      tags:
        - health
      responses:
        "200":
          description: Dependencies healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DependenciesHealthResponse"
              example:
                status: ok
                timestamp: "2026-02-23T12:00:00Z"
                components:
                  database: healthy
                  redis: healthy
                  horizon: healthy
                  soroban_rpc: healthy
        "503":
          description: One or more dependencies degraded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DependenciesHealthResponse"
              example:
                status: degraded
                timestamp: "2026-02-23T12:00:00Z"
                components:
                  database: healthy
                  redis: healthy
                  horizon: degraded
                  soroban_rpc: degraded

  /api/v1/assets:
    get:
      operationId: list_assets_metadata
      summary: Bulk asset metadata
      description: |
        Returns metadata for multiple assets identified by their codes.
      tags:
        - assets
      parameters:
        - name: codes
          in: query
          description: Comma-separated list of asset codes (e.g. `XLM,USDC`)
          required: true
          schema:
            type: string
            example: XLM,USDC
      responses:
        "200":
          description: List of asset metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssetMetadataBulkResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/assets/{code}:
    get:
      operationId: get_asset_metadata
      summary: Get asset metadata
      description: |
        Returns decimals, issuer labels, and domain information for a single asset.
      tags:
        - assets
      parameters:
        - name: code
          in: path
          description: Asset code (e.g. `XLM`, `USDC`)
          required: true
          schema:
            type: string
            example: USDC
        - name: issuer
          in: query
          description: Optional issuer address for disambiguating common codes.
          required: false
          schema:
            type: string
            example: GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN
      responses:
        "200":
          description: Asset metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssetMetadataResponse"
        "404":
          description: Asset not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/activity/swaps:
    get:
      operationId: list_swap_activity
      summary: Recent indexed contract swaps
      description: |
        Returns a paginated list of indexed on-chain swap activity from the
        `contract_swap_activity` table. Results are ordered by ledger
        descending (most recent first).

        Use `before_ledger` for cursor-based pagination and `limit` to
        control page size (default 50, max 100).
      tags:
        - activity
      parameters:
        - name: limit
          in: query
          description: Maximum number of swaps to return, capped at 100.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: before_ledger
          in: query
          description: Return swaps with ledger sequence strictly less than this value.
          required: false
          schema:
            type: integer
            format: int64
            example: 500000
      responses:
        "200":
          description: Recent indexed contract swaps
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SwapActivityResponse"
              example:
                swaps:
                  - event_id: "evt_abc123"
                    contract_id: "CBKMVLHBS2SNEQIS3EMU3Q4A2OGG5OQ5Z23Q7ITX5DOFGZQD5OZ6PQZ4"
                    ledger: 499999
                    ledger_closed_at: "2026-08-20T14:30:00Z"
                    paging_token: "499999-0"
                    sender: "GBV4FDE6VRZHQ2YG5NKB7RJE36GDEW3Y3L6YQ4Q5UZ6VJZGJLKZ46AAA"
                    amount_in: "10.0000000"
                    amount_out: "1.0500000"
                    fee_amount: "0.0000100"
                    route:
                      from_asset: native
                      to_asset: "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
                      source: sdex
                    source_asset: native
                    destination_asset: "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/RateLimited"

  /api/v1/pairs:
    get:
      operationId: list_pairs
      summary: List trading pairs
      description: |
        Returns active trading pairs that currently have offers in the SDEX
        orderbook.

        Stable sort order:
        1. `offer_count DESC`
        2. `last_updated DESC`
        3. Canonical asset fields ascending as deterministic tie-breakers

        Pagination:
        - Default page size: `25`
        - Max page size: `100`
        - `cursor` (preferred) or `offset` (fallback)
      tags:
        - trading
      parameters:
        - $ref: "#/components/parameters/PageLimit"
        - $ref: "#/components/parameters/PageCursor"
        - $ref: "#/components/parameters/PageOffset"
      responses:
        "200":
          description: List of active trading pairs
          headers:
            Deprecation:
              $ref: "#/components/headers/DeprecationHeader"
            Sunset:
              $ref: "#/components/headers/SunsetHeader"
            Link:
              $ref: "#/components/headers/DeprecationLinkHeader"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PairsResponse"
              example:
                pairs:
                  - base: XLM
                    counter: USDC
                    base_asset: native
                    counter_asset: "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
                    offer_count: 42
                    last_updated: "2026-02-23T11:59:00Z"
                  - base: USDC
                    counter: BTC
                    base_asset: "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
                    counter_asset: "BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF"
                    offer_count: 17
                    last_updated: "2026-02-23T11:58:30Z"
                total: 2
                limit: 25
                next_cursor: "25"
                prev_cursor: null
        "400":
          description: Invalid pagination parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                v: 1
                timestamp: 1740312000000
                request_id: req_01hyxk6bzv4n9p8m8j1f4c0a2r
                data:
                  error: validation_error
                  message: Invalid cursor; expected a numeric offset
        "404":
          description: Trading pairs not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                v: 1
                timestamp: 1740312000000
                request_id: req_01hyxk6bzv4n9p8m8j1f4c0a2r
                data:
                  error: not_found
                  message: No trading pairs found
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                v: 1
                timestamp: 1740312000000
                request_id: req_01hyxk6bzv4n9p8m8j1f4c0a2r
                data:
                  error: internal_error
                  message: An internal error occurred
        "429":
          $ref: "#/components/responses/RateLimited"

  /api/v1/markets:
    get:
      operationId: list_markets
      summary: List markets
      description: Alias of `/api/v1/pairs` with identical pagination and sorting.
      tags:
        - trading
      parameters:
        - $ref: "#/components/parameters/PageLimit"
        - $ref: "#/components/parameters/PageCursor"
        - $ref: "#/components/parameters/PageOffset"
      responses:
        "200":
          description: List of active markets
          headers:
            Deprecation:
              $ref: "#/components/headers/DeprecationHeader"
            Sunset:
              $ref: "#/components/headers/SunsetHeader"
            Link:
              $ref: "#/components/headers/DeprecationLinkHeader"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PairsResponse"
        "400":
          description: Invalid pagination parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/RateLimited"

  /api/v1/orderbook/{base}/{quote}:
    get:
      operationId: get_orderbook
      summary: Get orderbook
      description: |
        Returns bids and asks for the given base/quote asset pair.

        **Bids** are orders to buy the base asset with the quote asset
        (sorted highest price first).  **Asks** are orders to sell the base
        asset for the quote asset (sorted lowest price first).

        Results are cached for **10 seconds**.
      tags:
        - trading
      parameters:
        - $ref: "#/components/parameters/BaseAsset"
        - $ref: "#/components/parameters/QuoteAsset"
      responses:
        "200":
          description: Orderbook data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrderbookResponse"
              example:
                base_asset:
                  asset_type: native
                  asset_code: null
                  asset_issuer: null
                quote_asset:
                  asset_type: credit_alphanum4
                  asset_code: USDC
                  asset_issuer: GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN
                bids:
                  - price: "0.1050000"
                    amount: "500.0000000"
                    total: "52.5000000"
                asks:
                  - price: "0.1060000"
                    amount: "300.0000000"
                    total: "31.8000000"
                summary:
                  bid: "0.1050000"
                  ask: "0.1060000"
                  spread_bps: 95
                  midpoint: "0.1055000"
                timestamp: 1740312000
        "400":
          description: Invalid asset identifier
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                v: 1
                timestamp: 1740312000000
                request_id: req_01hyxk6bzv4n9p8m8j1f4c0a2r
                data:
                  error: invalid_asset
                  message: "Invalid base asset: unknown asset format"
        "404":
          description: Asset pair not found in the orderbook
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                v: 1
                timestamp: 1740312000000
                request_id: req_01hyxk6bzv4n9p8m8j1f4c0a2r
                data:
                  error: not_found
                  message: Asset not found in orderbook
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                v: 1
                timestamp: 1740312000000
                request_id: req_01hyxk6bzv4n9p8m8j1f4c0a2r
                data:
                  error: internal_error
                  message: An internal error occurred
        "429":
          $ref: "#/components/responses/RateLimited"

  /api/v1/price-history/{base}/{quote}:
    get:
      operationId: get_price_history
      summary: Get 24h price history
      description: |
        Returns a lightweight 24h sparkline series for the selected trading pair.

        The backend derives the series from `orderbook_snapshots.mid_price`
        using hourly aggregation buckets. If no snapshots are available in the
        trailing 24h window, the endpoint returns an empty `points` array.
      tags:
        - trading
      parameters:
        - $ref: "#/components/parameters/BaseAsset"
        - $ref: "#/components/parameters/QuoteAsset"
      responses:
        "200":
          description: 24h price history
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PriceHistoryResponse"
              example:
                base_asset:
                  asset_type: native
                  asset_code: null
                  asset_issuer: null
                quote_asset:
                  asset_type: credit_alphanum4
                  asset_code: USDC
                  asset_issuer: GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN
                window: "24h"
                source: orderbook_snapshots.mid_price
                generated_at: 1740312000000
                points:
                  - timestamp: 1740225600000
                    price: "0.1051000"
                  - timestamp: 1740229200000
                    price: "0.1054000"
        "400":
          description: Invalid asset identifier
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Trading pair not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/quote/{base}/{quote}:
    get:
      operationId: get_quote
      summary: Get price quote
      description: |
        Returns the best available price and routing path for trading `amount`
        of the base asset for the quote asset (or vice-versa when
        `quote_type=buy`).

        The router evaluates both SDEX offers and Soroban AMM pools to find
        the optimal execution path.

        Results are cached for **5 seconds**. Large responses honor
        `Accept-Encoding: br` or `Accept-Encoding: gzip`; smaller responses
        remain uncompressed. Prometheus metrics track original versus wire
        response bytes.
      tags:
        - trading
      parameters:
        - $ref: "#/components/parameters/BaseAsset"
        - $ref: "#/components/parameters/QuoteAsset"
        - $ref: "#/components/parameters/RequestIdHeader"
        - name: amount
          in: query
          description: Amount of the base asset to trade (default `1`)
          required: false
          schema:
            type: string
            example: "100"
        - name: slippage_bps
          in: query
          description: Slippage tolerance in basis points (e.g. `50` = 0.50%). Max `10000` (100%).
          required: false
          schema:
            type: integer
            default: 50
            example: 100
        - name: quote_type
          in: query
          description: |
            Direction of the quote:
            - `sell` — how much quote asset you receive when **selling** `amount` of the base asset
            - `buy`  — how much base asset you must spend to **buy** `amount` of the quote asset
          required: false
          schema:
            type: string
            enum: [sell, buy]
            default: sell
        - name: Accept-Encoding
          in: header
          description: Optional response compression negotiation. Large quote responses support `br` and `gzip`; smaller responses remain uncompressed.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Best available price quote
          headers:
            X-Request-ID:
              $ref: "#/components/headers/RequestIdHeader"
            Vary:
              schema:
                type: string
              description: Includes `Accept-Encoding` when quote response compression is negotiated.
            Content-Encoding:
              schema:
                type: string
                enum: [br, gzip]
              description: Present when the quote response is compressed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QuoteResponse"
              example:
                base_asset:
                  asset_type: native
                  asset_code: null
                  asset_issuer: null
                quote_asset:
                  asset_type: credit_alphanum4
                  asset_code: USDC
                  asset_issuer: GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN
                amount: "100.0000000"
                price: "0.1055000"
                total: "10.5500000"
                quote_type: sell
                degraded: false
                path:
                  - from_asset:
                      asset_type: native
                      asset_code: null
                      asset_issuer: null
                    to_asset:
                      asset_type: credit_alphanum4
                      asset_code: USDC
                      asset_issuer: GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN
                    price: "0.1055000"
                    source: sdex
                timestamp: 1740312000
        "400":
          description: Invalid parameters (bad asset format or non-positive amount)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                v: 1
                timestamp: 1740312000000
                request_id: req_01hyxk6bzv4n9p8m8j1f4c0a2r
                data:
                  error: validation_error
                  message: Amount must be greater than zero
        "404":
          description: No trading route found for this pair
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                v: 1
                timestamp: 1740312000000
                request_id: req_01hyxk6bzv4n9p8m8j1f4c0a2r
                data:
                  error: no_route
                  message: No trading route found for this pair
        "422":
          description: Stale market data — all data sources are too old to provide a quote
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: stale_market_data
                message: All market data inputs are stale
                details:
                  stale_count: 5
                  fresh_count: 0
                  threshold_secs_sdex: 60
                  threshold_secs_amm: 120
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                v: 1
                timestamp: 1740312000000
                request_id: req_01hyxk6bzv4n9p8m8j1f4c0a2r
                data:
                  error: internal_error
                  message: An internal error occurred
        "429":
          $ref: "#/components/responses/RateLimited"

  /api/v1/route/{base}/{quote}:
    get:
      operationId: get_route
      summary: Get trading route
      deprecated: true
      description: |
        Returns only the optimal execution path and routing steps for trading
        `amount` of the base asset for the quote asset.

        Unlike the quote endpoint, this returns a simplified response without
        detailed pricing breakdown or venue evaluations.

        This legacy route is deprecated in favor of `/api/v1/routes/{base}/{quote}`.
        Clients should watch the `Deprecation`, `Sunset`, and `Link` headers and
        migrate using the guidance in `docs/api/versioning.md`.
      tags:
        - trading
      parameters:
        - $ref: "#/components/parameters/BaseAsset"
        - $ref: "#/components/parameters/QuoteAsset"
        - name: amount
          in: query
          description: Amount of the base asset to trade (default `1`)
          required: false
          schema:
            type: string
            example: "100"
        - name: slippage_bps
          in: query
          description: Slippage tolerance in basis points (e.g. `50` = 0.50%). Max `10000` (100%).
          required: false
          schema:
            type: integer
            default: 50
            example: 100
        - name: quote_type
          in: query
          description: |
            Direction of the quote:
            - `sell` — how much quote asset you receive when **selling** `amount` of the base asset
            - `buy`  — how much base asset you must spend to **buy** `amount` of the quote asset
          required: false
          schema:
            type: string
            enum: [sell, buy]
            default: sell
      responses:
        "200":
          description: Optimal trading route
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RouteResponse"
        "400":
          description: Invalid parameters (bad asset format or invalid slippage)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: No trading route found for this pair
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/RateLimited"

components:
  parameters:
    RequestIdHeader:
      name: X-Request-ID
      in: header
      required: false
      description: Optional client-supplied correlation ID echoed back by the API.
      schema:
        type: string
        example: support-ticket-42
    BaseAsset:
      name: base
      in: path
      required: true
      description: |
        Base asset identifier. One of:
        - `native` — XLM
        - `CODE` — issued asset code only (e.g. `USDC`)
        - `CODE:ISSUER` — fully-qualified issued asset (e.g. `USDC:GA5Z...`)
      schema:
        type: string
        example: native
    QuoteAsset:
      name: quote
      in: path
      required: true
      description: |
        Quote asset identifier. One of:
        - `native` — XLM
        - `CODE` — issued asset code only (e.g. `USDC`)
        - `CODE:ISSUER` — fully-qualified issued asset (e.g. `USDC:GA5Z...`)
      schema:
        type: string
        example: USDC
    PageLimit:
      name: limit
      in: query
      required: false
      description: Page size. Default 25, max 100.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
    PageCursor:
      name: cursor
      in: query
      required: false
      description: Cursor for the next page (numeric offset token).
      schema:
        type: string
        example: "25"
    PageOffset:
      name: offset
      in: query
      required: false
      description: Offset fallback for pagination when cursor is not used.
      schema:
        type: integer
        minimum: 0
        example: 50

  responses:
    RateLimited:
      description: Rate limit exceeded
      headers:
        X-RateLimit-Limit:
          description: Maximum number of requests allowed in the current window
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Number of requests remaining in the current window
          schema:
            type: integer
        X-RateLimit-Reset:
          description: Unix timestamp when the rate limit window resets
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: rate_limit_exceeded
            message: Too many requests — please slow down

  headers:
    RequestIdHeader:
      description: Correlation ID for the request. Echoes the client-provided value or a server-generated UUID.
      schema:
        type: string
        example: 6b20dc6f-0cab-4f3f-b4eb-4638dbfd0f9d
    DeprecationHeader:
      description: Indicates that the endpoint version is deprecated.
      schema:
        type: string
        example: "true"
    SunsetHeader:
      description: RFC 7231 IMF-fixdate indicating planned v1 sunset.
      schema:
        type: string
        example: "Wed, 31 Dec 2026 23:59:59 GMT"
    DeprecationLinkHeader:
      description: Link to migration guidance for deprecated v1 routes.
      schema:
        type: string
        example: '</docs/api/v1-migration-guide>; rel="deprecation"'

  schemas:
    HealthResponse:
      type: object
      required: [status, timestamp, version, components]
      description: Service health check result
      properties:
        status:
          type: string
          description: Overall health status
          enum: [healthy, unhealthy]
          example: healthy
        timestamp:
          type: string
          format: date-time
          description: ISO-8601 UTC timestamp of the health check
          example: "2026-02-23T12:00:00Z"
        version:
          type: string
          description: Deployed crate version
          example: "0.1.0"
        components:
          type: object
          description: Per-dependency health status
          additionalProperties:
            type: string
          example:
            database: healthy
            redis: not_configured
            horizon: not_configured
            soroban_rpc: not_configured

    DependenciesHealthResponse:
      type: object
      required: [status, timestamp, components]
      description: Dependency-only health status for readiness checks
      properties:
        status:
          type: string
          enum: [ok, degraded]
          example: ok
        timestamp:
          type: string
          format: date-time
          example: "2026-02-23T12:00:00Z"
        components:
          type: object
          additionalProperties:
            type: string
          example:
            database: healthy
            redis: healthy
            horizon: healthy
            soroban_rpc: degraded

    AssetInfo:
      type: object
      required: [asset_type]
      description: Stellar asset descriptor
      properties:
        asset_type:
          type: string
          description: Stellar asset type
          enum: [native, credit_alphanum4, credit_alphanum12]
          example: credit_alphanum4
        asset_code:
          type: string
          nullable: true
          description: Asset code (null for native XLM)
          example: USDC
        asset_issuer:
          type: string
          nullable: true
          description: G-address of the issuing account (null for native XLM)
          example: GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN

    TradingPair:
      type: object
      required: [base, counter, base_asset, counter_asset, offer_count]
      description: A tradeable asset pair with active orderbook depth
      properties:
        base:
          type: string
          description: Human-readable base asset code
          example: XLM
        counter:
          type: string
          description: Human-readable counter asset code
          example: USDC
        base_asset:
          type: string
          description: Canonical base asset identifier (`native` or `CODE:ISSUER`)
          example: native
        counter_asset:
          type: string
          description: Canonical counter asset identifier (`native` or `CODE:ISSUER`)
          example: "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
        offer_count:
          type: integer
          format: int64
          description: Number of active offers for this pair
          example: 42
        last_updated:
          type: string
          format: date-time
          nullable: true
          description: RFC-3339 timestamp of the most recent offer update
          example: "2026-02-23T11:59:00Z"

    PairsResponse:
      type: object
      required: [pairs, total]
      description: List of active trading pairs
      properties:
        pairs:
          type: array
          items:
            $ref: "#/components/schemas/TradingPair"
        total:
          type: integer
          description: Total number of pairs available across all pages
          example: 2
        limit:
          type: integer
          nullable: true
          description: Effective page size used for this response
          example: 25
        next_cursor:
          type: string
          nullable: true
          description: Cursor token for the next page, if any
          example: "25"
        prev_cursor:
          type: string
          nullable: true
          description: Cursor token for the previous page, if any
          example: "0"

    AssetMetadataResponse:
      type: object
      required: [code, decimals, asset_type]
      description: Enriched asset metadata
      properties:
        code:
          type: string
          description: Asset code
          example: USDC
        issuer:
          type: string
          nullable: true
          description: G-address of the issuer
          example: GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN
        decimals:
          type: integer
          description: Number of decimal places for the asset
          example: 7
        asset_type:
          type: string
          description: Stellar asset type
          example: credit_alphanum4
        display_name:
          type: string
          nullable: true
          description: Human-readable display name or issuer label
          example: USDC
        icon_url:
          type: string
          nullable: true
          format: uri
          description: URL to the asset's icon/logo
          example: https://stellar.org/images/lumens-logo.svg
        domain:
          type: string
          nullable: true
          description: Home domain of the issuer
          example: centre.io

    AssetMetadataBulkResponse:
      type: object
      required: [assets]
      properties:
        assets:
          type: array
          items:
            $ref: "#/components/schemas/AssetMetadataResponse"

    OrderbookLevel:
      type: object
      required: [price, amount, total]
      description: A single price level in the orderbook
      properties:
        price:
          type: string
          description: Price as a decimal string (7 decimal places)
          example: "0.1050000"
        amount:
          type: string
          description: Available amount at this price level
          example: "500.0000000"
        total:
          type: string
          description: Total value at this price level (`price × amount`)
          example: "52.5000000"

    OrderbookResponse:
      type: object
      required: [base_asset, quote_asset, bids, asks, timestamp]
      description: Full orderbook snapshot for a trading pair
      properties:
        base_asset:
          $ref: "#/components/schemas/AssetInfo"
        quote_asset:
          $ref: "#/components/schemas/AssetInfo"
        bids:
          type: array
          description: Buy orders sorted highest price first
          items:
            $ref: "#/components/schemas/OrderbookLevel"
        asks:
          type: array
          description: Sell orders sorted lowest price first
          items:
            $ref: "#/components/schemas/OrderbookLevel"
        timestamp:
          type: integer
          format: int64
          description: Unix timestamp of the snapshot
          example: 1740312000

    PriceHistoryPoint:
      type: object
      required: [timestamp, price]
      description: Aggregated mid-price sample for a 24h sparkline
      properties:
        timestamp:
          type: integer
          format: int64
          description: Unix timestamp in milliseconds for the sampling bucket
          example: 1740225600000
        price:
          type: string
          description: Average mid-price for the bucket
          example: "0.1051000"

    PriceHistoryResponse:
      type: object
      required: [base_asset, quote_asset, window, source, generated_at, points]
      description: Historical price series derived from orderbook snapshots
      properties:
        base_asset:
          $ref: "#/components/schemas/AssetInfo"
        quote_asset:
          $ref: "#/components/schemas/AssetInfo"
        window:
          type: string
          description: Fixed time window for the series
          example: "24h"
        source:
          type: string
          description: Backend data source contract
          example: orderbook_snapshots.mid_price
        generated_at:
          type: integer
          format: int64
          description: Unix timestamp in milliseconds when the series was generated
          example: 1740312000000
        points:
          type: array
          items:
            $ref: "#/components/schemas/PriceHistoryPoint"

    PathStep:
      type: object
      required: [from_asset, to_asset, price, source]
      description: A single hop in the optimal execution path
      properties:
        from_asset:
          $ref: "#/components/schemas/AssetInfo"
        to_asset:
          $ref: "#/components/schemas/AssetInfo"
        price:
          type: string
          description: Exchange rate for this hop
          example: "0.1055000"
        source:
          type: string
          description: |
            Liquidity source for this hop:
            - `sdex` — Stellar Distributed Exchange
            - `amm:<pool_address>` — Soroban AMM pool
          example: sdex

    QuoteResponse:
      type: object
      required:
        [
          base_asset,
          quote_asset,
          amount,
          price,
          total,
          quote_type,
          degraded,
          path,
          timestamp,
        ]
      description: Best available price quote with full routing path
      properties:
        base_asset:
          $ref: "#/components/schemas/AssetInfo"
        quote_asset:
          $ref: "#/components/schemas/AssetInfo"
        amount:
          type: string
          description: Input amount that was quoted
          example: "100.0000000"
        price:
          type: string
          description: Effective price (quote asset per base asset unit)
          example: "0.1055000"
        total:
          type: string
          description: Total output amount (`amount × price`)
          example: "10.5500000"
        quote_type:
          type: string
          description: Direction of the quote
          enum: [sell, buy]
          example: sell
        degraded:
          type: boolean
          description: True when Soroban RPC is degraded and quote quality is reduced.
          example: false
        path:
          type: array
          description: Ordered list of hops in the optimal execution path
          items:
            $ref: "#/components/schemas/PathStep"
        timestamp:
          type: integer
          format: int64
          description: Unix timestamp when the quote was generated
          example: 1740312000

    RouteResponse:
      type: object
      required: [base_asset, quote_asset, amount, path, slippage_bps, timestamp]
      description: Optimal trading route without pricing details
      properties:
        base_asset:
          $ref: "#/components/schemas/AssetInfo"
        quote_asset:
          $ref: "#/components/schemas/AssetInfo"
        amount:
          type: string
          description: Amount of base asset being traded
          example: "100.0000000"
        path:
          type: array
          description: List of execution steps
          items:
            $ref: "#/components/schemas/PathStep"
        slippage_bps:
          type: integer
          description: Slippage tolerance in basis points
          example: 50
        timestamp:
          type: integer
          format: int64
          description: Unix timestamp of the route calculation
          example: 1740312000

    ErrorResponse:
      type: object
      required: [error, message]
      description: Standard API error format
      properties:
        error:
          type: string
          description: Machine-readable error code
          example: validation_error
        message:
          type: string
          description: Human-readable error description
          example: "Amount must be greater than zero"
        details:
          type: object
          nullable: true
          description: Optional structured context about the error
          example:
            parameter: slippage_bps
            min: 0
            max: 10000

    SwapActivityItem:
      type: object
      required: [event_id, contract_id, ledger, paging_token, sender, amount_in, amount_out, fee_amount, route]
      description: A single indexed on-chain swap event
      properties:
        event_id:
          type: string
          description: Unique event identifier
          example: "evt_abc123"
        contract_id:
          type: string
          description: Soroban contract address that emitted the event
          example: "CBKMVLHBS2SNEQIS3EMU3Q4A2OGG5OQ5Z23Q7ITX5DOFGZQD5OZ6PQZ4"
        ledger:
          type: integer
          format: int64
          description: Stellar ledger sequence when the event was recorded
          example: 499999
        ledger_closed_at:
          type: string
          format: date-time
          nullable: true
          description: RFC-3339 timestamp when the ledger closed
          example: "2026-08-20T14:30:00Z"
        paging_token:
          type: string
          description: Cursor token for pagination
          example: "499999-0"
        sender:
          type: string
          description: Stellar account that initiated the swap
          example: "GBV4FDE6VRZHQ2YG5NKB7RJE36GDEW3Y3L6YQ4Q5UZ6VJZGJLKZ46AAA"
        amount_in:
          type: string
          description: Input amount (decimal string)
          example: "10.0000000"
        amount_out:
          type: string
          description: Output amount (decimal string)
          example: "1.0500000"
        fee_amount:
          type: string
          description: Fee paid (decimal string)
          example: "0.0000100"
        route:
          type: object
          description: Execution route summary (JSON object)
          example:
            from_asset: native
            to_asset: "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
            source: sdex
        source_asset:
          type: string
          nullable: true
          description: Canonical source asset identifier
          example: native
        destination_asset:
          type: string
          nullable: true
          description: Canonical destination asset identifier
          example: "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"

    SwapActivityResponse:
      type: object
      required: [swaps]
      description: Paginated swap activity listing
      properties:
        swaps:
          type: array
          items:
            $ref: "#/components/schemas/SwapActivityItem"

  # Authentication is planned for a future release.
  # securitySchemes:
  #   bearerAuth:
  #     type: http
  #     scheme: bearer
  #     bearerFormat: JWT
  #     description: |
  #       API key authentication (Phase 2).
  #       Pass a JWT obtained from the /auth/token endpoint.