{
  "openapi": "3.1.0",
  "info": {
    "title": "SupaGamma API",
    "version": "1.0.0",
    "description": "REST API for Polymarket historical data. Per-data-type pricing: Trades $1/MB, OHLCV $8/MB, Orderbook $2/MB. $10 minimum order.",
    "contact": {
      "name": "SupaGamma",
      "url": "https://supagamma.com"
    }
  },
  "servers": [
    {
      "url": "https://api.supagamma.com/v1",
      "description": "Production"
    }
  ],
  "security": [
    { "ApiKeyAuth": [] }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API key (format: sg_live_xxxxxxxxxxxx). Get one at https://supagamma.com/dashboard/api-keys"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "JWT token from Supabase Auth (for web dashboard)"
      }
    },
    "schemas": {
      "Market": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "Market ID (condition ID)" },
          "question": { "type": "string", "description": "Market question text" },
          "outcomes": { "type": "array", "items": { "type": "string" }, "description": "Possible outcomes" },
          "status": { "type": "string", "enum": ["active", "resolved", "paused"] },
          "active": { "type": "boolean" },
          "end_date": { "type": "string", "format": "date-time" }
        }
      },
      "Trade": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "market_id": { "type": "string" },
          "timestamp": { "type": "string", "format": "date-time" },
          "block_number": { "type": "integer" },
          "transaction_hash": { "type": "string" },
          "outcome": { "type": "integer", "enum": [0, 1] },
          "side": { "type": "string", "enum": ["buy", "sell"] },
          "price": { "type": "number", "description": "Price in USDC (0-1)" },
          "size": { "type": "number", "description": "Size in USDC" },
          "usd_value": { "type": "number" },
          "maker": { "type": "string" },
          "taker": { "type": "string" },
          "fee": { "type": "number" }
        }
      },
      "OHLCV": {
        "type": "object",
        "properties": {
          "market_id": { "type": "string" },
          "outcome": { "type": "integer" },
          "timestamp": { "type": "string", "format": "date-time" },
          "open": { "type": "number" },
          "high": { "type": "number" },
          "low": { "type": "number" },
          "close": { "type": "number" },
          "volume": { "type": "number" },
          "trade_count": { "type": "integer" }
        }
      }
    }
  },
  "paths": {
    "/markets": {
      "get": {
        "summary": "List markets",
        "description": "List Polymarket prediction markets with optional filters.",
        "parameters": [
          { "name": "active", "in": "query", "schema": { "type": "boolean" }, "description": "Filter by active status" },
          { "name": "resolved", "in": "query", "schema": { "type": "boolean" }, "description": "Filter by resolved status" },
          { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Search by question text" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
        ],
        "responses": {
          "200": { "description": "List of markets", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Market" } } } } }
        }
      }
    },
    "/markets/{market_id}": {
      "get": {
        "summary": "Get market details",
        "parameters": [
          { "name": "market_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Market details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Market" } } } }
        }
      }
    },
    "/markets/{market_id}/stats": {
      "get": {
        "summary": "Get market statistics",
        "description": "Trade count, volume, and price range for a market.",
        "parameters": [
          { "name": "market_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Market statistics" }
        }
      }
    },
    "/trades": {
      "get": {
        "summary": "List trades",
        "description": "Query indexed on-chain trades from the Polymarket CTF Exchange.",
        "parameters": [
          { "name": "market_id", "in": "query", "schema": { "type": "string" } },
          { "name": "start", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Start timestamp (ISO 8601)" },
          { "name": "end", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "End timestamp (ISO 8601)" },
          { "name": "outcome", "in": "query", "schema": { "type": "integer", "enum": [0, 1] } },
          { "name": "side", "in": "query", "schema": { "type": "string", "enum": ["buy", "sell"] } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 10000 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
        ],
        "responses": {
          "200": { "description": "List of trades", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Trade" } } } } }
        }
      }
    },
    "/trades/ohlcv": {
      "get": {
        "summary": "Get OHLCV candles",
        "description": "Candlestick data for a market in various timeframes.",
        "parameters": [
          { "name": "market_id", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "outcome", "in": "query", "schema": { "type": "integer", "default": 0 } },
          { "name": "timeframe", "in": "query", "schema": { "type": "string", "enum": ["1m", "5m", "15m", "1h", "4h", "1d"], "default": "1h" } },
          { "name": "start", "in": "query", "schema": { "type": "string", "format": "date-time" } },
          { "name": "end", "in": "query", "schema": { "type": "string", "format": "date-time" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 500, "maximum": 10000 } }
        ],
        "responses": {
          "200": { "description": "OHLCV candle data", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OHLCV" } } } } }
        }
      }
    },
    "/trades/recent": {
      "get": {
        "summary": "Get recent trades",
        "description": "Most recent trades across all markets.",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }
        ],
        "responses": {
          "200": { "description": "Recent trades" }
        }
      }
    },
    "/download/trades": {
      "get": {
        "summary": "Download trades",
        "description": "Download trade data as CSV, Parquet, or JSON file.",
        "parameters": [
          { "name": "market_id", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "start", "in": "query", "schema": { "type": "string", "format": "date-time" } },
          { "name": "end", "in": "query", "schema": { "type": "string", "format": "date-time" } },
          { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["csv", "parquet", "json"], "default": "csv" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100000, "maximum": 1000000 } }
        ],
        "responses": {
          "200": { "description": "File download in requested format" }
        }
      }
    },
    "/download/ohlcv": {
      "get": {
        "summary": "Download OHLCV data",
        "description": "Download OHLCV candlestick data as CSV, Parquet, or JSON file.",
        "parameters": [
          { "name": "market_id", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "timeframe", "in": "query", "schema": { "type": "string", "enum": ["1m", "1h", "1d"], "default": "1h" } },
          { "name": "start", "in": "query", "schema": { "type": "string", "format": "date-time" } },
          { "name": "end", "in": "query", "schema": { "type": "string", "format": "date-time" } },
          { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["csv", "parquet", "json"], "default": "csv" } }
        ],
        "responses": {
          "200": { "description": "File download in requested format" }
        }
      }
    },
    "/user/me": {
      "get": {
        "summary": "Get current user profile",
        "responses": { "200": { "description": "User profile" } }
      }
    },
    "/user/keys": {
      "get": {
        "summary": "List API keys",
        "responses": { "200": { "description": "List of API keys" } }
      },
      "post": {
        "summary": "Create API key",
        "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": ["name"] } } } },
        "responses": { "201": { "description": "New API key created" } }
      }
    },
    "/user/keys/{key_id}": {
      "delete": {
        "summary": "Revoke API key",
        "parameters": [
          { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Key revoked" } }
      }
    },
    "/user/usage": {
      "get": {
        "summary": "Get usage statistics",
        "responses": { "200": { "description": "Usage stats" } }
      }
    },
    "/billing/balance": {
      "get": {
        "summary": "Get credit balance",
        "responses": { "200": { "description": "Current balance" } }
      }
    },
    "/billing/pricing": {
      "get": {
        "summary": "Get pricing info",
        "description": "Returns current per-data-type pricing (Trades $1/MB, OHLCV $8/MB, Orderbook $2/MB) and the $10 minimum order.",
        "responses": { "200": { "description": "Pricing details" } }
      }
    },
    "/billing/transactions": {
      "get": {
        "summary": "Get transaction history",
        "responses": { "200": { "description": "Transaction list" } }
      }
    },
    "/billing/checkout": {
      "post": {
        "summary": "Create payment checkout",
        "description": "Create a Paddle checkout session to purchase credits.",
        "responses": { "200": { "description": "Checkout URL" } }
      }
    }
  }
}