{
  "openapi": "3.0.3",
  "info": {
    "title": "Aevo Exchange Public REST API",
    "description": "Public unauthenticated REST API for Aevo exchange (the trading platform evolved from Ribbon Finance) providing market data, vault statistics, options pricing, funding rates, and other openly available trading information. No authentication required for these endpoints.",
    "version": "1.0.0",
    "contact": {
      "name": "Aevo Support",
      "url": "https://docs.aevo.xyz/"
    }
  },
  "servers": [
    {
      "url": "https://api.aevo.xyz",
      "description": "Aevo Exchange production server"
    }
  ],
  "tags": [
    {
      "name": "Market Data",
      "description": "Public market data endpoints"
    },
    {
      "name": "Instruments",
      "description": "Instrument and market information"
    },
    {
      "name": "Statistics",
      "description": "Exchange statistics and analytics"
    }
  ],
  "paths": {
    "/orderbook": {
      "get": {
        "tags": ["Market Data"],
        "summary": "Get orderbook",
        "description": "Returns the orderbook for a given instrument symbol including bids, asks, and implied volatility.",
        "operationId": "getOrderbook",
        "parameters": [
          {
            "name": "instrument_name",
            "in": "query",
            "required": true,
            "description": "Instrument name.",
            "schema": {
              "type": "string",
              "example": "ETH-30JUN23-1600-C"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Orderbook snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "example": "snapshot"
                    },
                    "instrument_id": {
                      "type": "string",
                      "description": "Numeric instrument identifier"
                    },
                    "instrument_name": {
                      "type": "string",
                      "example": "ETH-30JUN23-1600-C"
                    },
                    "instrument_type": {
                      "type": "string",
                      "enum": ["OPTION", "PERPETUAL", "SPOT"]
                    },
                    "bids": {
                      "type": "array",
                      "description": "Array of [price_USD, contract_amount, IV]",
                      "items": {
                        "type": "array",
                        "items": { "type": "string" }
                      }
                    },
                    "asks": {
                      "type": "array",
                      "description": "Array of [price_USD, contract_amount, IV]",
                      "items": {
                        "type": "array",
                        "items": { "type": "string" }
                      }
                    },
                    "last_updated": {
                      "type": "string",
                      "description": "Last updated timestamp in UNIX nanoseconds"
                    },
                    "checksum": {
                      "type": "string",
                      "description": "Payload verification checksum"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/markets": {
      "get": {
        "tags": ["Instruments"],
        "summary": "Get markets",
        "description": "Returns a list of all available instruments/markets on the exchange.",
        "operationId": "getMarkets",
        "parameters": [
          {
            "name": "asset",
            "in": "query",
            "required": false,
            "description": "Name of underlying asset.",
            "schema": {
              "type": "string",
              "example": "ETH"
            }
          },
          {
            "name": "instrument_type",
            "in": "query",
            "required": false,
            "description": "Type of instrument.",
            "schema": {
              "type": "string",
              "enum": ["OPTION", "PERPETUAL", "SPOT"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of markets",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Instrument"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/index": {
      "get": {
        "tags": ["Market Data"],
        "summary": "Get index price",
        "description": "Returns the current index price for a given underlying asset.",
        "operationId": "getIndex",
        "parameters": [
          {
            "name": "asset",
            "in": "query",
            "required": true,
            "description": "Name of underlying asset.",
            "schema": {
              "type": "string",
              "example": "ETH"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Index price",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "price": {
                      "type": "string",
                      "example": "1850.50"
                    },
                    "timestamp": {
                      "type": "string",
                      "description": "UNIX timestamp in nanoseconds",
                      "example": "1680249600000000000"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/index-history": {
      "get": {
        "tags": ["Market Data"],
        "summary": "Get index price history",
        "description": "Returns historical index price data for a given underlying asset.",
        "operationId": "getIndexHistory",
        "parameters": [
          {
            "name": "asset",
            "in": "query",
            "required": true,
            "description": "Name of underlying asset.",
            "schema": {
              "type": "string",
              "example": "ETH"
            }
          },
          {
            "name": "start_time",
            "in": "query",
            "required": false,
            "description": "Start time in UNIX nanoseconds.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "end_time",
            "in": "query",
            "required": false,
            "description": "End time in UNIX nanoseconds.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Index price history",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "history": {
                      "type": "array",
                      "items": {
                        "type": "array",
                        "items": { "type": "string" },
                        "description": "[timestamp, price]"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/funding": {
      "get": {
        "tags": ["Market Data"],
        "summary": "Get funding rate",
        "description": "Returns the current funding rate for a perpetual instrument.",
        "operationId": "getFunding",
        "parameters": [
          {
            "name": "instrument_name",
            "in": "query",
            "required": true,
            "description": "Instrument name.",
            "schema": {
              "type": "string",
              "example": "ETH-PERP"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Funding rate",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "funding_rate": {
                      "type": "string",
                      "description": "Funding rate in decimals.",
                      "example": "0.00122"
                    },
                    "next_epoch": {
                      "type": "string",
                      "description": "Next epoch in UNIX nanoseconds.",
                      "example": "1680249600000000000"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/funding-history": {
      "get": {
        "tags": ["Market Data"],
        "summary": "Get funding rate history",
        "description": "Returns historical funding rate data for a perpetual instrument.",
        "operationId": "getFundingHistory",
        "parameters": [
          {
            "name": "instrument_name",
            "in": "query",
            "required": true,
            "description": "Instrument name.",
            "schema": {
              "type": "string",
              "example": "ETH-PERP"
            }
          },
          {
            "name": "start_time",
            "in": "query",
            "required": false,
            "description": "Start time in UNIX nanoseconds.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "end_time",
            "in": "query",
            "required": false,
            "description": "End time in UNIX nanoseconds.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Number of results to return.",
            "schema": {
              "type": "integer",
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Funding rate history",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "funding_history": {
                      "type": "array",
                      "items": {
                        "type": "array",
                        "items": { "type": "string" },
                        "description": "[timestamp, funding_rate]"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/statistics": {
      "get": {
        "tags": ["Statistics"],
        "summary": "Get exchange statistics",
        "description": "Returns aggregated trading statistics including volume, open interest, and price data.",
        "operationId": "getStatistics",
        "parameters": [
          {
            "name": "asset",
            "in": "query",
            "required": false,
            "description": "Name of underlying asset.",
            "schema": {
              "type": "string",
              "example": "ETH"
            }
          },
          {
            "name": "instrument_type",
            "in": "query",
            "required": false,
            "description": "Type of instrument.",
            "schema": {
              "type": "string",
              "enum": ["OPTION", "PERPETUAL", "SPOT"]
            }
          },
          {
            "name": "end_time",
            "in": "query",
            "required": false,
            "description": "Entries created after end time are excluded in UNIX nanoseconds.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Exchange statistics",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["daily_volume", "daily_buy_volume", "daily_sell_volume"],
                  "properties": {
                    "daily_volume": { "type": "string" },
                    "daily_buy_volume": { "type": "string" },
                    "daily_sell_volume": { "type": "string" },
                    "asset": { "type": "string" },
                    "open_interest": {
                      "type": "object",
                      "properties": {
                        "calls": { "type": "string" },
                        "puts": { "type": "string" },
                        "total": { "type": "string" }
                      }
                    },
                    "daily_volume_premium": { "type": "string" },
                    "total_volume": { "type": "string" },
                    "total_volume_premium": { "type": "string" },
                    "daily_volume_contracts": { "type": "string" },
                    "index_price": { "type": "string" },
                    "index_daily_change": { "type": "string" },
                    "mark_price": { "type": "string" },
                    "mark_price_24h_ago": { "type": "string" },
                    "mark_daily_change": { "type": "string" },
                    "funding_daily_avg": { "type": "string" },
                    "put_call_ratio": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/mark-history": {
      "get": {
        "tags": ["Market Data"],
        "summary": "Get mark price history",
        "description": "Returns historical mark price data for a given instrument.",
        "operationId": "getMarkHistory",
        "parameters": [
          {
            "name": "instrument_name",
            "in": "query",
            "required": true,
            "description": "Instrument name.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "start_time",
            "in": "query",
            "required": false,
            "schema": { "type": "integer" }
          },
          {
            "name": "end_time",
            "in": "query",
            "required": false,
            "schema": { "type": "integer" }
          }
        ],
        "responses": {
          "200": {
            "description": "Mark price history",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "mark_history": {
                      "type": "array",
                      "items": {
                        "type": "array",
                        "items": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/settlement-history": {
      "get": {
        "tags": ["Market Data"],
        "summary": "Get settlement history",
        "description": "Returns historical settlement price data.",
        "operationId": "getSettlementHistory",
        "parameters": [
          {
            "name": "asset",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "example": "ETH" }
          },
          {
            "name": "start_time",
            "in": "query",
            "required": false,
            "schema": { "type": "integer" }
          },
          {
            "name": "end_time",
            "in": "query",
            "required": false,
            "schema": { "type": "integer" }
          }
        ],
        "responses": {
          "200": {
            "description": "Settlement history",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "settlement_history": {
                      "type": "array",
                      "items": { "type": "object" }
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/options-history": {
      "get": {
        "tags": ["Market Data"],
        "summary": "Get options history",
        "description": "Returns historical options trading data.",
        "operationId": "getOptionsHistory",
        "parameters": [
          {
            "name": "asset",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "example": "ETH" }
          },
          {
            "name": "start_time",
            "in": "query",
            "required": false,
            "schema": { "type": "integer" }
          },
          {
            "name": "end_time",
            "in": "query",
            "required": false,
            "schema": { "type": "integer" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 50 }
          }
        ],
        "responses": {
          "200": {
            "description": "Options history",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "options_history": {
                      "type": "array",
                      "items": { "type": "object" }
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/assets": {
      "get": {
        "tags": ["Instruments"],
        "summary": "Get available assets",
        "description": "Returns a list of all available underlying assets on the exchange.",
        "operationId": "getAssets",
        "responses": {
          "200": {
            "description": "List of assets",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "assets": {
                      "type": "array",
                      "items": { "type": "string" }
                    }
                  }
                }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/expiries": {
      "get": {
        "tags": ["Instruments"],
        "summary": "Get available expiries",
        "description": "Returns the list of available option expiry dates.",
        "operationId": "getExpiries",
        "parameters": [
          {
            "name": "asset",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "example": "ETH" }
          }
        ],
        "responses": {
          "200": {
            "description": "List of expiries",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "expiries": {
                      "type": "array",
                      "items": { "type": "string" }
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/time": {
      "get": {
        "tags": ["Statistics"],
        "summary": "Get server time",
        "description": "Returns the current server time. Used for timestamp synchronization.",
        "operationId": "getTime",
        "responses": {
          "200": {
            "description": "Server time",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "timestamp": {
                      "type": "string",
                      "description": "UNIX timestamp in nanoseconds"
                    }
                  }
                }
              }
            }
          },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/coingecko-statistics": {
      "get": {
        "tags": ["Statistics"],
        "summary": "Get CoinGecko statistics",
        "description": "Returns exchange statistics in CoinGecko format.",
        "operationId": "getCoinGeckoStatistics",
        "responses": {
          "200": {
            "description": "CoinGecko-compatible statistics",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Instrument": {
        "type": "object",
        "properties": {
          "instrument_id": {
            "type": "string",
            "description": "Numeric instrument identifier"
          },
          "instrument_name": {
            "type": "string",
            "example": "ETH-30JUN23-1600-C"
          },
          "instrument_type": {
            "type": "string",
            "enum": ["OPTION", "PERPETUAL", "SPOT"]
          },
          "underlying_asset": {
            "type": "string",
            "example": "ETH"
          },
          "quote_asset": {
            "type": "string",
            "example": "USDC"
          },
          "price_step": {
            "type": "string",
            "description": "Allowed increments in price"
          },
          "amount_step": {
            "type": "string",
            "description": "Allowed increments in contract amount"
          },
          "min_order_value": { "type": "string" },
          "max_order_value": { "type": "string" },
          "max_notional_value": { "type": "string" },
          "mark_price": { "type": "string" },
          "forward_price": { "type": "string" },
          "index_price": { "type": "string" },
          "is_active": {
            "type": "boolean",
            "description": "Whether trading is active"
          },
          "option_type": {
            "type": "string",
            "enum": ["put", "call"],
            "description": "Option type (only for options)"
          },
          "expiry": {
            "type": "string",
            "description": "Expiry timestamp in UNIX nanoseconds (only for options)"
          },
          "strike": {
            "type": "string",
            "description": "Strike price (only for options)"
          },
          "greeks": {
            "type": "object",
            "properties": {
              "delta": { "type": "string" },
              "gamma": { "type": "string" },
              "rho": { "type": "string" },
              "theta": { "type": "string" },
              "vega": { "type": "string" },
              "iv": { "type": "string" }
            }
          },
          "max_leverage": {
            "type": "string",
            "description": "Maximum leverage (only for perpetuals)"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "ERR_MALFORMED_REQUEST"
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Malformed request",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          }
        }
      },
      "InternalError": {
        "description": "Internal server error",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          }
        }
      }
    }
  }
}