openapi.json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Lens API",
    "description": "Unified Stellar price API aggregating SDEX + AMM prices.\nCache 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.",
    "version": "0.1.0",
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "http://localhost:4000",
      "description": "Local development server"
    }
  ],
  "paths": {
    "/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
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/status": {
      "get": {
        "operationId": "getStatus",
        "summary": "Get API status and indexer state",
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/NetworkQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "API status",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "network": {
                      "type": "string",
                      "enum": [
                        "testnet",
                        "mainnet"
                      ]
                    },
                    "watchedPairs": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "lastIndexedLedger": {
                      "type": "integer",
                      "nullable": true
                    },
                    "lastProcessedAt": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "ingestLagSeconds": {
                      "type": "integer",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/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"
          }
        ],
        "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"
          }
        }
      }
    },
    "/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"
            }
          },
          {
            "name": "assetB",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "amount",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "default": 1000
            }
          },
          {
            "$ref": "#/components/parameters/NetworkQuery"
          }
        ],
        "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"
          }
        }
      }
    },
    "/price/{assetA}/{assetB}/history": {
      "get": {
        "operationId": "getPriceHistory",
        "summary": "Get price history buckets",
        "security": [],
        "parameters": [
          {
            "name": "assetA",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "assetB",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "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"
          }
        ],
        "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"
          }
        }
      }
    },
    "/pools": {
      "get": {
        "operationId": "getPools",
        "summary": "Get AMM liquidity pool reserves and spot prices",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/NetworkQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "List of pools",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pools": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "pool_id": {
                            "type": "string"
                          },
                          "asset_a": {
                            "type": "string"
                          },
                          "asset_b": {
                            "type": "string"
                          },
                          "reserve_a": {
                            "type": "number"
                          },
                          "reserve_b": {
                            "type": "number"
                          },
                          "spot_price": {
                            "type": "number"
                          },
                          "fee_bp": {
                            "type": "integer"
                          },
                          "timestamp": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/candles/{assetA}/{assetB}": {
      "get": {
        "operationId": "getCandles",
        "summary": "Get OHLCV candle data",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "assetA",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "assetB",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "interval",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1m",
                "5m",
                "15m",
                "1h",
                "4h",
                "1d"
              ],
              "default": "1h"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Candle data",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pairKey": {
                      "type": "string"
                    },
                    "interval": {
                      "type": "string"
                    },
                    "from": {
                      "type": "string"
                    },
                    "to": {
                      "type": "string"
                    },
                    "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"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/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. Snapshots are retained for ~30 days. 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,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "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/NetworkQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Historical price snapshots",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "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",
                  "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"
                    },
                    "points": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "ts": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "price": {
                            "type": "number"
                          },
                          "volume": {
                            "type": "number"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/pairs": {
      "get": {
        "operationId": "listPairs",
        "summary": "List all active trading pairs",
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/NetworkQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "List of pairs",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "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
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "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:GBBD47..."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Pair added"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Unauthorized"
          },
          "409": {
            "description": "Pair already exists"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/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"
          }
        ],
        "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"
          }
        }
      }
    },
    "/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"
          }
        ],
        "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"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "description": "No source could be read; response provenance identifies failed venues.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BookResponse"
                }
              }
            }
          }
        }
      }
    },
    "/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"
            }
          },
          {
            "name": "assetB",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "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"
          }
        ],
        "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"
          }
        }
      }
    },
    "/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"
            }
          },
          {
            "name": "assetB",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "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"
            }
          }
        ],
        "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"
          }
        }
      }
    },
    "/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.",
        "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"
          }
        }
      }
    },
    "/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"
          }
        }
      }
    },
    "/compare/{asset}": {
      "get": {
        "operationId": "compareAsset",
        "summary": "Compare Lens prices with every configured external oracle",
        "security": [],
        "parameters": [
          {
            "name": "asset",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "XLM"
          },
          {
            "$ref": "#/components/parameters/NetworkQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Price comparison",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompareResponse"
                }
              }
            }
          },
          "404": {
            "description": "No price data found for the asset"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/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,
            "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"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque cursor returned as `nextCursor` by the previous page.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "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"
          }
        }
      }
    },
    "/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"
          }
        }
      }
    },
    "/basket": {
      "get": {
        "operationId": "getBasket",
        "summary": "Compute the weighted price of a basket of assets",
        "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",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BasketResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing assets or mismatched/invalid weights"
          },
          "404": {
            "description": "No price data for one or more assets"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/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"
          }
        }
      }
    },
    "/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"
          }
        }
      }
    },
    "/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"
          }
        }
      }
    },
    "/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"
          }
        }
      }
    },
    "/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"
                }
              }
            }
          }
        }
      }
    },
    "/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"
                }
              }
            }
          }
        }
      }
    },
    "/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"
                }
              }
            }
          }
        }
      }
    },
    "/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"
          }
        }
      }
    }
  },
  "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": {
      "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"
        }
      }
    },
    "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"
                }
              }
            }
          }
        }
      }
    },
    "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": {
      "Asset": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "issuer": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "AggregatedPrice": {
        "type": "object",
        "properties": {
          "assetA": {
            "type": "string"
          },
          "assetB": {
            "type": "string"
          },
          "pairKey": {
            "type": "string"
          },
          "price": {
            "type": "number"
          },
          "sdexPrice": {
            "type": "number"
          },
          "ammPrice": {
            "type": "number"
          },
          "bestRoute": {
            "type": "string",
            "enum": [
              "SDEX",
              "AMM",
              "SPLIT",
              "UNKNOWN"
            ]
          },
          "volume24h": {
            "type": "number"
          },
          "sdexVolume24h": {
            "type": "number"
          },
          "ammVolume24h": {
            "type": "number"
          },
          "vwap1m": {
            "type": "number"
          },
          "vwap5m": {
            "type": "number"
          },
          "vwap1h": {
            "type": "number"
          },
          "vwap24h": {
            "type": "number"
          },
          "priceChange24h": {
            "type": "number"
          },
          "lastUpdated": {
            "type": "string",
            "format": "date-time"
          },
          "sources": {
            "type": "integer"
          },
          "confidence": {
            "type": "string",
            "enum": [
              "high",
              "medium",
              "low",
              "unknown"
            ]
          },
          "lastTradeAgeSeconds": {
            "type": "integer",
            "nullable": true
          }
        }
      },
      "RouteInfo": {
        "type": "object",
        "properties": {
          "route": {
            "type": "string",
            "enum": [
              "SDEX",
              "AMM",
              "SPLIT",
              "UNKNOWN"
            ]
          },
          "sdexPrice": {
            "type": "number"
          },
          "ammPrice": {
            "type": "number"
          },
          "estimatedOutput": {
            "type": "number"
          },
          "slippagePct": {
            "type": "number"
          },
          "recommendation": {
            "type": "string"
          }
        }
      },
      "PriceBucket": {
        "type": "object",
        "properties": {
          "bucket": {
            "type": "string",
            "format": "date-time"
          },
          "window": {
            "type": "string"
          },
          "vwap": {
            "type": "number"
          },
          "sdexVwap": {
            "type": "number",
            "nullable": true
          },
          "ammVwap": {
            "type": "number",
            "nullable": true
          },
          "volume": {
            "type": "number"
          },
          "tradeCount": {
            "type": "integer"
          },
          "open": {
            "type": "number",
            "nullable": true
          },
          "close": {
            "type": "number",
            "nullable": true
          },
          "high": {
            "type": "number",
            "nullable": true
          },
          "low": {
            "type": "number",
            "nullable": true
          }
        }
      },
      "PriceLevel": {
        "type": "object",
        "required": [
          "price",
          "size"
        ],
        "additionalProperties": false,
        "properties": {
          "price": {
            "type": "number"
          },
          "size": {
            "type": "number"
          }
        }
      },
      "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": {
            "type": "number"
          },
          "executionPrice": {
            "type": "number"
          },
          "slippagePct": {
            "type": "number"
          },
          "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": {
            "type": "number",
            "description": "Quote-asset units per base-asset unit."
          },
          "size": {
            "type": "number",
            "description": "Base-asset size at this level."
          },
          "cumulativeSize": {
            "type": "number",
            "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"
                }
              }
            }
          }
        }
      },
      "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": {
            "type": "number"
          },
          "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",
          "vwap",
          "windowMinutes",
          "source",
          "startTime",
          "endTime",
          "sampleCount",
          "volumeTotal",
          "outlierRejected",
          "filterMethod"
        ],
        "additionalProperties": false,
        "properties": {
          "assetA": {
            "type": "string"
          },
          "assetB": {
            "type": "string"
          },
          "pairKey": {
            "type": "string"
          },
          "vwap": {
            "type": "number"
          },
          "windowMinutes": {
            "type": "integer"
          },
          "source": {
            "type": "string"
          },
          "startTime": {
            "type": "string",
            "format": "date-time"
          },
          "endTime": {
            "type": "string",
            "format": "date-time"
          },
          "sampleCount": {
            "type": "integer"
          },
          "volumeTotal": {
            "type": "number"
          },
          "outlierRejected": {
            "type": "integer"
          },
          "filterMethod": {
            "type": "string",
            "enum": [
              "iqr",
              "modified_zscore"
            ]
          }
        }
      },
      "VolumeResponse": {
        "type": "object",
        "required": [
          "asset",
          "window",
          "startTime",
          "endTime",
          "totalVolume",
          "byVenue",
          "venues",
          "tradeCount"
        ],
        "additionalProperties": false,
        "properties": {
          "asset": {
            "type": "string"
          },
          "window": {
            "type": "string",
            "enum": [
              "24h",
              "7d",
              "30d"
            ]
          },
          "startTime": {
            "type": "string",
            "format": "date-time"
          },
          "endTime": {
            "type": "string",
            "format": "date-time"
          },
          "totalVolume": {
            "type": "number"
          },
          "byVenue": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            }
          },
          "venues": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "tradeCount": {
            "type": "integer"
          }
        }
      },
      "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"
              }
            ]
          }
        }
      },
      "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"
          }
        }
      },
      "ScreenerResponse": {
        "type": "object",
        "required": [
          "data",
          "nextCursor",
          "hasMore",
          "total"
        ],
        "additionalProperties": false,
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ScreenerRow"
            }
          },
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "hasMore": {
            "type": "boolean"
          },
          "total": {
            "type": "integer",
            "nullable": true
          }
        }
      },
      "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"
          }
        }
      },
      "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"
          }
        }
      },
      "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"
                }
              }
            }
          }
        }
      }
    }
  }
}