{
  "openapi": "3.1.0",
  "info": {
    "title": "Polyrouter API",
    "version": "2.0.0",
    "description": "Unified API for prediction market platforms (Polymarket, Kalshi, Limitless, Manifold)",
    "contact": {
      "name": "Polyrouter",
      "url": "https://polyrouter.io"
    }
  },
  "servers": [
    {
      "url": "https://api-v2.polyrouter.io",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Health",
      "description": "Health check and API info"
    },
    {
      "name": "Markets",
      "description": "Prediction market operations"
    },
    {
      "name": "Events",
      "description": "Event operations"
    },
    {
      "name": "Series",
      "description": "Series operations"
    },
    {
      "name": "Platforms",
      "description": "Platform information"
    },
    {
      "name": "Search",
      "description": "Search across platforms"
    },
    {
      "name": "Trades",
      "description": "Historical trades data"
    },
    {
      "name": "Orderbook",
      "description": "Orderbook data (real-time and historical)"
    },
    {
      "name": "Sports",
      "description": "Sports betting markets - games, awards, futures, and league info"
    },
    {
      "name": "Profile",
      "description": "User profiles, trading metrics, and trade history"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API key for authentication"
      }
    },
    "schemas": {
      "HealthCheck": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "database"
          },
          "status": {
            "type": "string",
            "enum": [
              "pass",
              "fail",
              "warn"
            ],
            "example": "pass"
          },
          "response_time_ms": {
            "type": "number",
            "example": 15
          }
        },
        "required": [
          "name",
          "status"
        ]
      },
      "HealthResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "healthy",
                  "degraded",
                  "unhealthy"
                ],
                "example": "healthy"
              },
              "checks": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/HealthCheck"
                }
              },
              "uptime": {
                "type": "number",
                "example": 86400
              },
              "version": {
                "type": "string",
                "example": "2.0.0"
              },
              "timestamp": {
                "type": "string",
                "format": "date-time"
              }
            },
            "required": [
              "status",
              "checks",
              "uptime",
              "version",
              "timestamp"
            ]
          },
          "meta": {
            "type": "object",
            "properties": {
              "request_time": {
                "type": "number",
                "example": 50
              }
            },
            "required": [
              "request_time"
            ]
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "ApiInfo": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "Polyrouter API"
          },
          "version": {
            "type": "string",
            "example": "2.0.0"
          },
          "endpoints": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "name",
          "version",
          "endpoints"
        ]
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "total": {
            "type": "number",
            "example": 50
          },
          "limit": {
            "type": "number",
            "example": 50
          },
          "has_more": {
            "type": "boolean",
            "example": true
          },
          "next_cursor": {
            "type": "string",
            "nullable": true,
            "example": "WzMsW1swLDEsM11dXQ"
          }
        },
        "required": [
          "total",
          "limit",
          "has_more",
          "next_cursor"
        ]
      },
      "Outcome": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "yes"
          },
          "name": {
            "type": "string",
            "example": "Yes"
          }
        },
        "required": [
          "id",
          "name"
        ]
      },
      "PriceDetail": {
        "type": "object",
        "properties": {
          "price": {
            "type": "number",
            "example": 0.65
          },
          "bid": {
            "type": "number",
            "example": 0.64
          },
          "ask": {
            "type": "number",
            "example": 0.66
          }
        },
        "required": [
          "price"
        ]
      },
      "LastTradeInfo": {
        "type": "object",
        "properties": {
          "price": {
            "type": "number",
            "example": 0.65
          },
          "timestamp": {
            "type": "string",
            "example": "2025-01-01T00:00:00.000Z"
          },
          "size": {
            "type": "number",
            "example": 100
          }
        },
        "required": [
          "price",
          "timestamp",
          "size"
        ]
      },
      "MarketMetadata": {
        "type": "object",
        "properties": {
          "conditionId": {
            "type": "string",
            "nullable": true
          },
          "ammType": {
            "type": "string",
            "nullable": true
          },
          "marketType": {
            "type": "string",
            "nullable": true
          },
          "formatType": {
            "type": "string",
            "nullable": true
          },
          "competitive": {
            "type": "number",
            "example": 0
          },
          "score": {
            "type": "number",
            "example": 0
          },
          "bestBid": {
            "type": "number",
            "example": 0.64
          },
          "bestAsk": {
            "type": "number",
            "example": 0.66
          },
          "spread": {
            "type": "number",
            "example": 0.02
          },
          "clobTokenIds": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Market": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "KXELONMARS-99"
          },
          "platform": {
            "type": "string",
            "example": "kalshi"
          },
          "platform_id": {
            "type": "string",
            "example": "KXELONMARS-99"
          },
          "event_id": {
            "type": "string",
            "example": "KXELONMARS-99"
          },
          "event_name": {
            "type": "string",
            "example": "Will Elon Musk visit Mars?"
          },
          "event_slug": {
            "type": "string",
            "nullable": true,
            "example": "elon-musk-mars"
          },
          "series_id": {
            "type": "string"
          },
          "slug": {
            "type": "string",
            "example": "kxelonmars-99"
          },
          "market_slug": {
            "type": "string",
            "example": "kxelonmars-99"
          },
          "title": {
            "type": "string",
            "example": "Will Elon Musk visit Mars before Aug 1, 2099?"
          },
          "description": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "example": "Science"
          },
          "subcategory": {
            "type": "string",
            "nullable": true
          },
          "tags": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            }
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "paused",
              "resolved",
              "cancelled"
            ],
            "example": "open"
          },
          "market_type": {
            "type": "string",
            "enum": [
              "binary",
              "categorical",
              "scalar"
            ],
            "example": "binary"
          },
          "outcomes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Outcome"
            }
          },
          "current_prices": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/PriceDetail"
            }
          },
          "volume_24h": {
            "type": "number",
            "nullable": true,
            "example": 10000
          },
          "volume_7d": {
            "type": "number",
            "nullable": true,
            "example": 50000
          },
          "volume_total": {
            "type": "number",
            "nullable": true,
            "example": 500000
          },
          "liquidity": {
            "type": "number",
            "nullable": true
          },
          "liquidity_score": {
            "type": "number"
          },
          "open_interest": {
            "type": "number",
            "nullable": true
          },
          "unique_traders": {
            "type": "number",
            "nullable": true
          },
          "fee_rate": {
            "type": "number",
            "nullable": true
          },
          "trading_fee": {
            "type": "number",
            "nullable": true
          },
          "withdrawal_fee": {
            "type": "number",
            "nullable": true
          },
          "source_url": {
            "type": "string",
            "example": "https://kalshi.com/markets/kxelonmars-99"
          },
          "image_url": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "trading_start_at": {
            "type": "string",
            "nullable": true
          },
          "trading_end_at": {
            "type": "string"
          },
          "resolution_date": {
            "type": "string"
          },
          "resolved_at": {
            "type": "string",
            "nullable": true
          },
          "resolution_criteria": {
            "type": "string",
            "nullable": true
          },
          "resolution_source": {
            "type": "string",
            "nullable": true
          },
          "price_24h_changes": {
            "type": "object",
            "nullable": true,
            "additionalProperties": {
              "type": "number"
            }
          },
          "price_7d_changes": {
            "type": "object",
            "nullable": true,
            "additionalProperties": {
              "type": "number"
            }
          },
          "last_trades": {
            "type": "object",
            "nullable": true,
            "additionalProperties": {
              "$ref": "#/components/schemas/LastTradeInfo"
            }
          },
          "metadata": {
            "$ref": "#/components/schemas/MarketMetadata"
          },
          "last_synced_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "platform",
          "platform_id",
          "title",
          "status",
          "market_type",
          "outcomes",
          "current_prices",
          "last_synced_at"
        ]
      },
      "Meta": {
        "type": "object",
        "properties": {
          "platforms_queried": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "polymarket",
              "kalshi"
            ]
          },
          "request_time": {
            "type": "number",
            "example": 150
          },
          "cache_hit": {
            "type": "boolean",
            "example": false
          },
          "data_freshness": {
            "type": "string",
            "format": "date-time",
            "example": "2025-01-01T00:00:00.000Z"
          }
        },
        "required": [
          "platforms_queried",
          "request_time",
          "cache_hit",
          "data_freshness"
        ]
      },
      "MarketsResponse": {
        "type": "object",
        "properties": {
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "markets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Market"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": [
          "pagination",
          "markets",
          "meta"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "example": "NOT_FOUND"
              },
              "message": {
                "type": "string",
                "example": "Resource not found"
              },
              "timestamp": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-01T00:00:00.000Z"
              }
            },
            "required": [
              "code",
              "message",
              "timestamp"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "MarketResponse": {
        "type": "object",
        "properties": {
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "markets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Market"
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "request_time": {
                "type": "number"
              },
              "cache_hit": {
                "type": "boolean"
              },
              "data_freshness": {
                "type": "string"
              }
            },
            "required": [
              "request_time",
              "cache_hit",
              "data_freshness"
            ]
          }
        },
        "required": [
          "pagination",
          "markets",
          "meta"
        ]
      },
      "OrderbookOrder": {
        "type": "object",
        "properties": {
          "price": {
            "type": "number",
            "example": 0.65
          },
          "size": {
            "type": "number",
            "example": 1000
          }
        },
        "required": [
          "price",
          "size"
        ]
      },
      "OrderbookSide": {
        "type": "object",
        "properties": {
          "bids": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderbookOrder"
            }
          },
          "asks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderbookOrder"
            }
          },
          "depth": {
            "type": "number",
            "example": 50000
          }
        },
        "required": [
          "bids",
          "asks"
        ]
      },
      "OrderbookData": {
        "type": "object",
        "properties": {
          "market_id": {
            "type": "string",
            "example": "524153"
          },
          "platform": {
            "type": "string",
            "example": "polymarket"
          },
          "timestamp": {
            "type": "string",
            "example": "2025-01-01T00:00:00.000Z"
          },
          "yes": {
            "$ref": "#/components/schemas/OrderbookSide"
          },
          "no": {
            "$ref": "#/components/schemas/OrderbookSide"
          },
          "metadata": {
            "type": "object",
            "properties": {
              "min_order_size": {
                "type": "number",
                "example": 5
              },
              "tick_size": {
                "type": "number",
                "example": 0.001
              },
              "neg_risk": {
                "type": "boolean",
                "example": false
              }
            }
          }
        },
        "required": [
          "market_id",
          "platform",
          "timestamp",
          "yes",
          "no"
        ]
      },
      "OrderbookResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/OrderbookData"
          },
          "meta": {
            "type": "object",
            "properties": {
              "request_time": {
                "type": "number",
                "example": 150
              }
            },
            "required": [
              "request_time"
            ]
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "Event": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "4690"
          },
          "platform": {
            "type": "string",
            "example": "polymarket"
          },
          "platform_id": {
            "type": "string"
          },
          "series_id": {
            "type": "string"
          },
          "title": {
            "type": "string",
            "example": "US Presidential Election 2024"
          },
          "slug": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "image_url": {
            "type": "string"
          },
          "resolution_source_url": {
            "type": "string"
          },
          "event_start_at": {
            "type": "string"
          },
          "event_end_at": {
            "type": "string"
          },
          "market_count": {
            "type": "number",
            "example": 5
          },
          "total_volume": {
            "type": "number"
          },
          "last_synced_at": {
            "type": "string"
          },
          "markets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Market"
            }
          }
        },
        "required": [
          "id",
          "platform",
          "platform_id",
          "title",
          "last_synced_at"
        ]
      },
      "EventsResponse": {
        "type": "object",
        "properties": {
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Event"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": [
          "pagination",
          "events",
          "meta"
        ]
      },
      "EventResponse": {
        "type": "object",
        "properties": {
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Event"
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "request_time": {
                "type": "number"
              },
              "cache_hit": {
                "type": "boolean"
              },
              "data_freshness": {
                "type": "string"
              }
            },
            "required": [
              "request_time",
              "cache_hit",
              "data_freshness"
            ]
          }
        },
        "required": [
          "pagination",
          "events",
          "meta"
        ]
      },
      "Series": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "1"
          },
          "platform": {
            "type": "string",
            "example": "polymarket"
          },
          "platform_id": {
            "type": "string"
          },
          "title": {
            "type": "string",
            "example": "NFL 2024 Season"
          },
          "slug": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "image_url": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "event_count": {
            "type": "number"
          },
          "market_count": {
            "type": "number"
          },
          "total_volume": {
            "type": "number"
          },
          "last_synced_at": {
            "type": "string"
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Event"
            }
          }
        },
        "required": [
          "id",
          "platform",
          "platform_id",
          "title",
          "last_synced_at"
        ]
      },
      "SeriesListResponse": {
        "type": "object",
        "properties": {
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "series": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Series"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": [
          "pagination",
          "series",
          "meta"
        ]
      },
      "SeriesResponse": {
        "type": "object",
        "properties": {
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "series": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Series"
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "request_time": {
                "type": "number"
              },
              "cache_hit": {
                "type": "boolean"
              },
              "data_freshness": {
                "type": "string"
              }
            },
            "required": [
              "request_time",
              "cache_hit",
              "data_freshness"
            ]
          }
        },
        "required": [
          "pagination",
          "series",
          "meta"
        ]
      },
      "PlatformEndpoint": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "markets"
          },
          "available": {
            "type": "boolean",
            "example": true
          }
        },
        "required": [
          "name",
          "available"
        ]
      },
      "PlatformInfo": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "polymarket"
          },
          "name": {
            "type": "string",
            "example": "Polymarket"
          },
          "status": {
            "type": "string",
            "enum": [
              "available",
              "unavailable",
              "degraded"
            ],
            "example": "available"
          },
          "health": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "pass",
                  "fail",
                  "warn"
                ],
                "example": "pass"
              },
              "last_check": {
                "type": "string",
                "example": "2025-01-01T00:00:00.000Z"
              },
              "response_time_ms": {
                "type": "number",
                "example": 150
              }
            },
            "required": [
              "status",
              "last_check"
            ]
          },
          "endpoints": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlatformEndpoint"
            }
          },
          "features": {
            "type": "object",
            "properties": {
              "orderbook": {
                "type": "boolean",
                "example": true
              },
              "trades": {
                "type": "boolean",
                "example": true
              },
              "historical_data": {
                "type": "boolean",
                "example": true
              },
              "user_profiles": {
                "type": "boolean",
                "example": true
              }
            },
            "required": [
              "orderbook",
              "trades",
              "historical_data",
              "user_profiles"
            ]
          }
        },
        "required": [
          "id",
          "name",
          "status"
        ]
      },
      "PlatformsResponse": {
        "type": "object",
        "properties": {
          "platforms": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlatformInfo"
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "request_time": {
                "type": "number"
              },
              "total": {
                "type": "number"
              }
            },
            "required": [
              "request_time",
              "total"
            ]
          }
        },
        "required": [
          "platforms",
          "meta"
        ]
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "markets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Market"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": [
          "markets",
          "pagination",
          "meta"
        ]
      },
      "TradeUser": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "trader123"
          },
          "pseudonym": {
            "type": "string",
            "example": "Anonymous Trader"
          },
          "profile_image": {
            "type": "string"
          }
        }
      },
      "Trade": {
        "type": "object",
        "properties": {
          "trade_id": {
            "type": "string",
            "example": "0x123abc..."
          },
          "market_id": {
            "type": "string",
            "example": "524153"
          },
          "platform": {
            "type": "string",
            "example": "polymarket"
          },
          "side": {
            "type": "string",
            "enum": [
              "buy",
              "sell",
              "yes",
              "no"
            ],
            "example": "buy"
          },
          "price": {
            "type": "number",
            "example": 0.65
          },
          "size": {
            "type": "number",
            "example": 100
          },
          "timestamp": {
            "type": "number",
            "description": "Unix timestamp in seconds",
            "example": 1704067200
          },
          "outcome": {
            "type": "string",
            "example": "Yes"
          },
          "taker": {
            "type": "boolean",
            "example": true
          },
          "transaction_hash": {
            "type": "string",
            "example": "0x456def..."
          },
          "user": {
            "$ref": "#/components/schemas/TradeUser"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "nullable": true
            }
          }
        },
        "required": [
          "trade_id",
          "market_id",
          "platform",
          "side",
          "price",
          "size",
          "timestamp"
        ]
      },
      "TradesResponse": {
        "type": "object",
        "properties": {
          "trades": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Trade"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "meta": {
            "type": "object",
            "properties": {
              "request_time": {
                "type": "number",
                "example": 150
              },
              "market_id": {
                "type": "string",
                "example": "524153"
              },
              "platform": {
                "type": "string",
                "example": "polymarket"
              },
              "data_freshness": {
                "type": "string",
                "example": "2025-01-01T00:00:00.000Z"
              }
            },
            "required": [
              "request_time",
              "market_id",
              "platform",
              "data_freshness"
            ]
          }
        },
        "required": [
          "trades",
          "pagination",
          "meta"
        ]
      },
      "OrderbookSnapshot": {
        "type": "object",
        "properties": {
          "snapshot_id": {
            "type": "string",
            "example": "snap_123"
          },
          "market_id": {
            "type": "string",
            "example": "524153"
          },
          "platform": {
            "type": "string",
            "example": "polymarket"
          },
          "timestamp": {
            "type": "string",
            "example": "2025-01-01T00:00:00.000Z"
          },
          "yes": {
            "$ref": "#/components/schemas/OrderbookSide"
          },
          "no": {
            "$ref": "#/components/schemas/OrderbookSide"
          },
          "metadata": {
            "type": "object",
            "properties": {
              "yes_hash": {
                "type": "string"
              },
              "no_hash": {
                "type": "string"
              },
              "yes_asset_id": {
                "type": "string"
              },
              "no_asset_id": {
                "type": "string"
              },
              "yes_timestamp": {
                "type": "string"
              },
              "no_timestamp": {
                "type": "string"
              },
              "tick_size": {
                "type": "string"
              },
              "min_order_size": {
                "type": "string"
              },
              "neg_risk": {
                "type": "boolean"
              }
            }
          }
        },
        "required": [
          "snapshot_id",
          "market_id",
          "platform",
          "timestamp",
          "yes",
          "no"
        ]
      },
      "HistoricalOrderbookResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "market_id": {
                "type": "string"
              },
              "platform": {
                "type": "string"
              },
              "snapshots": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/OrderbookSnapshot"
                }
              },
              "count": {
                "type": "number"
              },
              "start_time": {
                "type": "string"
              },
              "end_time": {
                "type": "string"
              },
              "limit": {
                "type": "number"
              }
            },
            "required": [
              "market_id",
              "platform",
              "snapshots",
              "count",
              "start_time",
              "end_time",
              "limit"
            ]
          },
          "meta": {
            "type": "object",
            "properties": {
              "request_time": {
                "type": "number",
                "example": 250
              }
            },
            "required": [
              "request_time"
            ]
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "SportsEventWithoutMarkets": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "KCvSF20250209@NFL"
          },
          "title": {
            "type": "string",
            "example": "Chiefs vs 49ers"
          },
          "teams": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "Kansas City Chiefs",
              "San Francisco 49ers"
            ]
          },
          "sport": {
            "type": "string",
            "example": "Football"
          },
          "league": {
            "type": "string",
            "example": "NFL"
          },
          "description": {
            "type": "string",
            "example": "Super Bowl LVIII"
          },
          "scheduled_at": {
            "type": "string",
            "example": "2025-02-09T23:30:00.000Z"
          },
          "status": {
            "type": "string",
            "example": "not_started"
          },
          "image_url": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "example": "sports"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "nfl",
              "super-bowl",
              "championship"
            ]
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "nullable": true
            }
          }
        },
        "required": [
          "id",
          "title",
          "teams",
          "sport",
          "league",
          "description",
          "scheduled_at",
          "status",
          "category",
          "tags",
          "metadata"
        ]
      },
      "SportsPagination": {
        "type": "object",
        "properties": {
          "total": {
            "type": "number",
            "example": 50
          },
          "limit": {
            "type": "number",
            "example": 50
          },
          "has_more": {
            "type": "boolean",
            "example": true
          },
          "next_cursor": {
            "type": "string",
            "nullable": true,
            "example": "eyJvZmZzZXQiOjUwfQ"
          }
        },
        "required": [
          "total",
          "limit",
          "has_more",
          "next_cursor"
        ]
      },
      "SportsPlatform": {
        "type": "string",
        "enum": [
          "polymarket",
          "kalshi",
          "prophetx",
          "novig",
          "sxbet"
        ]
      },
      "SportsMeta": {
        "type": "object",
        "properties": {
          "platforms_queried": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SportsPlatform"
            },
            "example": [
              "polymarket",
              "kalshi",
              "prophetx"
            ]
          },
          "request_time": {
            "type": "number",
            "example": 250
          },
          "platform_errors": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "data_freshness": {
            "type": "string",
            "example": "2025-01-01T00:00:00.000Z"
          }
        },
        "required": [
          "platforms_queried",
          "request_time",
          "data_freshness"
        ]
      },
      "GamesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "games": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/SportsEventWithoutMarkets"
                }
              },
              "pagination": {
                "$ref": "#/components/schemas/SportsPagination"
              }
            },
            "required": [
              "games",
              "pagination"
            ]
          },
          "meta": {
            "$ref": "#/components/schemas/SportsMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "League": {
        "type": "string",
        "enum": [
          "nfl",
          "nba",
          "nhl",
          "mlb"
        ],
        "description": "League to query (required)"
      },
      "SportsOrderbookEntry": {
        "type": "object",
        "properties": {
          "price": {
            "type": "number",
            "example": 0.65
          },
          "qty": {
            "type": "number",
            "example": 100
          },
          "status": {
            "type": "string",
            "example": "active"
          },
          "side": {
            "type": "string",
            "enum": [
              "yes",
              "no"
            ],
            "example": "yes"
          },
          "timestamp": {
            "type": "string",
            "example": "2025-01-01T00:00:00.000Z"
          }
        },
        "required": [
          "price",
          "qty",
          "status",
          "side",
          "timestamp"
        ]
      },
      "PlatformMarket": {
        "type": "object",
        "properties": {
          "outcome_id": {
            "type": "string",
            "example": "outcome_123"
          },
          "platform_id": {
            "type": "string",
            "nullable": true,
            "example": "pm_456"
          },
          "name": {
            "type": "string",
            "example": "Kansas City Chiefs"
          },
          "price": {
            "type": "number",
            "example": 0.65
          },
          "volume": {
            "type": "number",
            "example": 50000
          },
          "status": {
            "type": "string",
            "example": "active"
          },
          "liquidity": {
            "type": "number",
            "example": 25000
          },
          "order_book": {
            "type": "object",
            "properties": {
              "yes": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/SportsOrderbookEntry"
                }
              },
              "no": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/SportsOrderbookEntry"
                }
              }
            },
            "required": [
              "yes",
              "no"
            ]
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "nullable": true
            }
          }
        },
        "required": [
          "outcome_id",
          "platform_id",
          "name",
          "price",
          "volume",
          "status",
          "liquidity",
          "order_book"
        ]
      },
      "PlatformMarketList": {
        "type": "object",
        "properties": {
          "platform": {
            "type": "string",
            "example": "polymarket"
          },
          "event_id": {
            "type": "string",
            "example": "evt_123"
          },
          "event_name": {
            "type": "string",
            "example": "Super Bowl LVIII"
          },
          "event_slug": {
            "type": "string",
            "example": "super-bowl-lviii"
          },
          "outcomes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlatformMarket"
            }
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "nullable": true
            }
          }
        },
        "required": [
          "platform",
          "event_id",
          "outcomes",
          "metadata"
        ]
      },
      "SportsEvent": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "KCvSF20250209@NFL"
          },
          "title": {
            "type": "string",
            "example": "Chiefs vs 49ers"
          },
          "teams": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "Kansas City Chiefs",
              "San Francisco 49ers"
            ]
          },
          "sport": {
            "type": "string",
            "example": "Football"
          },
          "league": {
            "type": "string",
            "example": "NFL"
          },
          "description": {
            "type": "string",
            "example": "Super Bowl LVIII"
          },
          "scheduled_at": {
            "type": "string",
            "example": "2025-02-09T23:30:00.000Z"
          },
          "status": {
            "type": "string",
            "example": "not_started"
          },
          "image_url": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "example": "sports"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "nfl",
              "super-bowl",
              "championship"
            ]
          },
          "markets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlatformMarketList"
            }
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "nullable": true
            }
          }
        },
        "required": [
          "id",
          "title",
          "teams",
          "sport",
          "league",
          "description",
          "scheduled_at",
          "status",
          "category",
          "tags",
          "markets",
          "metadata"
        ]
      },
      "GameResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/SportsEvent"
          },
          "meta": {
            "$ref": "#/components/schemas/SportsMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "SportsMarketType": {
        "type": "string",
        "enum": [
          "moneyline",
          "spread",
          "total",
          "prop"
        ],
        "description": "Filter by market type"
      },
      "OddsFormat": {
        "type": "string",
        "enum": [
          "american",
          "decimal",
          "probability"
        ],
        "description": "Odds format for market odds (american, decimal, fractional)",
        "example": "american"
      },
      "AwardInfo": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "nfl_mvp_2024"
          },
          "award_name": {
            "type": "string",
            "example": "NFL MVP"
          },
          "league": {
            "type": "string",
            "example": "nfl"
          },
          "season": {
            "type": "number",
            "example": 2024
          },
          "award_type": {
            "type": "string",
            "example": "mvp"
          },
          "platform_markets": {
            "type": "object",
            "properties": {
              "polymarket": {
                "type": "object",
                "properties": {
                  "market_id": {
                    "type": "string"
                  },
                  "clob_token_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "required": [
                  "market_id"
                ]
              },
              "kalshi": {
                "type": "object",
                "properties": {
                  "event_ticker": {
                    "type": "string"
                  }
                },
                "required": [
                  "event_ticker"
                ]
              },
              "prophetx": {
                "type": "object",
                "properties": {
                  "tournament_id": {
                    "type": "string"
                  }
                },
                "required": [
                  "tournament_id"
                ]
              },
              "novig": {
                "type": "object",
                "properties": {
                  "market_slug": {
                    "type": "string"
                  }
                },
                "required": [
                  "market_slug"
                ]
              },
              "sxbet": {
                "type": "object",
                "properties": {
                  "league_id": {
                    "type": "number"
                  }
                },
                "required": [
                  "league_id"
                ]
              }
            }
          },
          "metadata": {
            "type": "object",
            "properties": {
              "deadline": {
                "type": "string"
              },
              "description": {
                "type": "string"
              },
              "eligibility": {
                "type": "string"
              }
            },
            "additionalProperties": {
              "nullable": true
            }
          }
        },
        "required": [
          "id",
          "award_name",
          "league",
          "season",
          "award_type",
          "platform_markets",
          "metadata"
        ]
      },
      "ListAwardsResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "awards": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AwardInfo"
                }
              }
            },
            "required": [
              "awards"
            ]
          },
          "meta": {
            "$ref": "#/components/schemas/SportsMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "OddsFormats": {
        "type": "object",
        "properties": {
          "american": {
            "type": "string",
            "example": "+150"
          },
          "decimal": {
            "type": "number",
            "example": 2.5
          },
          "implied_probability": {
            "type": "number",
            "example": 0.4
          }
        },
        "required": [
          "american",
          "decimal",
          "implied_probability"
        ]
      },
      "AwardCandidate": {
        "type": "object",
        "properties": {
          "player_name": {
            "type": "string",
            "example": "Patrick Mahomes"
          },
          "team_polyrouter_id": {
            "type": "string",
            "example": "nfl_kc"
          },
          "odds": {
            "$ref": "#/components/schemas/OddsFormats"
          },
          "volume_24h": {
            "type": "number",
            "example": 15000
          },
          "last_trade_price": {
            "type": "number",
            "example": 0.35
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "nullable": true
            }
          }
        },
        "required": [
          "player_name",
          "odds"
        ]
      },
      "AwardPlatformMarket": {
        "type": "object",
        "properties": {
          "platform": {
            "type": "string",
            "example": "polymarket"
          },
          "market_id": {
            "type": "string",
            "example": "pm_mvp_2024"
          },
          "candidates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AwardCandidate"
            }
          }
        },
        "required": [
          "platform",
          "market_id",
          "candidates"
        ]
      },
      "AwardMarket": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "nfl_mvp_2024"
          },
          "award_name": {
            "type": "string",
            "example": "NFL MVP"
          },
          "league": {
            "type": "string",
            "example": "nfl"
          },
          "season": {
            "type": "number",
            "example": 2024
          },
          "award_type": {
            "type": "string",
            "example": "mvp"
          },
          "markets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AwardPlatformMarket"
            }
          },
          "metadata": {
            "type": "object",
            "properties": {
              "deadline": {
                "type": "string"
              },
              "description": {
                "type": "string"
              },
              "eligibility": {
                "type": "string"
              }
            },
            "additionalProperties": {
              "nullable": true
            }
          }
        },
        "required": [
          "id",
          "award_name",
          "league",
          "season",
          "award_type",
          "markets",
          "metadata"
        ]
      },
      "AwardResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/AwardMarket"
          },
          "meta": {
            "$ref": "#/components/schemas/SportsMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "FutureInfo": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "nfl_superbowl_2025"
          },
          "future_name": {
            "type": "string",
            "example": "Super Bowl LIX Winner"
          },
          "league": {
            "type": "string",
            "example": "nfl"
          },
          "season": {
            "type": "number",
            "example": 2024
          },
          "future_type": {
            "type": "string",
            "example": "championship"
          },
          "category": {
            "type": "string",
            "example": "team"
          },
          "platform_markets": {
            "type": "object",
            "properties": {
              "polymarket": {
                "type": "object",
                "properties": {
                  "market_id": {
                    "type": "string"
                  },
                  "clob_token_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "required": [
                  "market_id"
                ]
              },
              "kalshi": {
                "type": "object",
                "properties": {
                  "event_ticker": {
                    "type": "string"
                  }
                },
                "required": [
                  "event_ticker"
                ]
              },
              "prophetx": {
                "type": "object",
                "properties": {
                  "tournament_id": {
                    "type": "string"
                  }
                },
                "required": [
                  "tournament_id"
                ]
              },
              "novig": {
                "type": "object",
                "properties": {
                  "market_slug": {
                    "type": "string"
                  }
                },
                "required": [
                  "market_slug"
                ]
              },
              "sxbet": {
                "type": "object",
                "properties": {
                  "league_id": {
                    "type": "number"
                  }
                },
                "required": [
                  "league_id"
                ]
              }
            }
          },
          "metadata": {
            "type": "object",
            "properties": {
              "deadline": {
                "type": "string"
              },
              "description": {
                "type": "string"
              },
              "eligible_teams": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "additionalProperties": {
              "nullable": true
            }
          }
        },
        "required": [
          "id",
          "future_name",
          "league",
          "season",
          "future_type",
          "category",
          "platform_markets",
          "metadata"
        ]
      },
      "ListFuturesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "futures": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/FutureInfo"
                }
              }
            },
            "required": [
              "futures"
            ]
          },
          "meta": {
            "$ref": "#/components/schemas/SportsMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "FutureOutcome": {
        "type": "object",
        "properties": {
          "team_polyrouter_id": {
            "type": "string",
            "example": "nfl_kc"
          },
          "outcome_name": {
            "type": "string",
            "example": "Kansas City Chiefs"
          },
          "odds": {
            "$ref": "#/components/schemas/OddsFormats"
          },
          "volume_24h": {
            "type": "number",
            "example": 25000
          },
          "last_trade_price": {
            "type": "number",
            "example": 0.15
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "nullable": true
            }
          }
        },
        "required": [
          "outcome_name",
          "odds"
        ]
      },
      "FuturePlatformMarket": {
        "type": "object",
        "properties": {
          "platform": {
            "type": "string",
            "example": "polymarket"
          },
          "market_id": {
            "type": "string",
            "example": "pm_sb_2025"
          },
          "outcomes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FutureOutcome"
            }
          }
        },
        "required": [
          "platform",
          "market_id",
          "outcomes"
        ]
      },
      "FutureMarket": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "nfl_superbowl_2025"
          },
          "future_name": {
            "type": "string",
            "example": "Super Bowl LIX Winner"
          },
          "league": {
            "type": "string",
            "example": "nfl"
          },
          "season": {
            "type": "number",
            "example": 2024
          },
          "future_type": {
            "type": "string",
            "example": "championship"
          },
          "category": {
            "type": "string",
            "example": "team"
          },
          "markets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FuturePlatformMarket"
            }
          },
          "metadata": {
            "type": "object",
            "properties": {
              "deadline": {
                "type": "string"
              },
              "description": {
                "type": "string"
              },
              "eligible_teams": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "additionalProperties": {
              "nullable": true
            }
          }
        },
        "required": [
          "id",
          "future_name",
          "league",
          "season",
          "future_type",
          "category",
          "markets",
          "metadata"
        ]
      },
      "FutureResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/FutureMarket"
          },
          "meta": {
            "$ref": "#/components/schemas/SportsMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "TeamPlatformIds": {
        "type": "object",
        "properties": {
          "polymarket": {
            "type": "string"
          },
          "kalshi": {
            "type": "string"
          },
          "prophetx": {
            "type": "string"
          },
          "novig": {
            "type": "string"
          },
          "sxbet": {
            "type": "string"
          }
        }
      },
      "TeamInfo": {
        "type": "object",
        "properties": {
          "polyrouter_id": {
            "type": "string",
            "example": "nfl_kc"
          },
          "name": {
            "type": "string",
            "example": "Kansas City Chiefs"
          },
          "abbreviation": {
            "type": "string",
            "example": "KC"
          },
          "city": {
            "type": "string",
            "example": "Kansas City"
          },
          "state": {
            "type": "string",
            "example": "Missouri"
          },
          "conference": {
            "type": "string",
            "example": "AFC"
          },
          "division": {
            "type": "string",
            "example": "West"
          },
          "platform_ids": {
            "$ref": "#/components/schemas/TeamPlatformIds"
          },
          "metadata": {
            "type": "object",
            "properties": {
              "logo_url": {
                "type": "string"
              },
              "colors": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "founded": {
                "type": "number"
              },
              "stadium": {
                "type": "string"
              }
            },
            "additionalProperties": {
              "nullable": true
            }
          }
        },
        "required": [
          "polyrouter_id",
          "name",
          "abbreviation",
          "city",
          "platform_ids",
          "metadata"
        ]
      },
      "LeagueInfo": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "nfl"
          },
          "name": {
            "type": "string",
            "example": "National Football League"
          },
          "abbreviation": {
            "type": "string",
            "example": "NFL"
          },
          "sport": {
            "type": "string",
            "example": "Football"
          },
          "season": {
            "type": "object",
            "properties": {
              "year": {
                "type": "number",
                "example": 2024
              },
              "start_date": {
                "type": "string",
                "example": "2024-09-05"
              },
              "end_date": {
                "type": "string",
                "example": "2025-02-09"
              }
            },
            "required": [
              "year",
              "start_date",
              "end_date"
            ]
          },
          "endpoints": {
            "type": "object",
            "properties": {
              "awards": {
                "type": "boolean"
              },
              "futures": {
                "type": "boolean"
              },
              "games": {
                "type": "boolean"
              },
              "list_games": {
                "type": "boolean"
              },
              "list_awards": {
                "type": "boolean"
              },
              "list_futures": {
                "type": "boolean"
              }
            },
            "required": [
              "awards",
              "futures",
              "games",
              "list_games",
              "list_awards",
              "list_futures"
            ]
          },
          "counts": {
            "type": "object",
            "properties": {
              "teams": {
                "type": "number",
                "example": 32
              },
              "awards": {
                "type": "number",
                "example": 10
              },
              "futures": {
                "type": "number",
                "example": 15
              }
            },
            "required": [
              "teams",
              "awards",
              "futures"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "operational",
              "limited"
            ],
            "example": "operational"
          },
          "teams": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TeamInfo"
            }
          }
        },
        "required": [
          "id",
          "name",
          "abbreviation",
          "sport",
          "season",
          "endpoints",
          "counts",
          "status"
        ]
      },
      "LeagueInfoResponse": {
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/LeagueInfo"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "request_time": {
                    "type": "number",
                    "example": 50
                  }
                },
                "required": [
                  "request_time"
                ]
              }
            },
            "required": [
              "data",
              "meta"
            ]
          },
          {
            "type": "object",
            "properties": {
              "leagues": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/LeagueInfo"
                }
              },
              "meta": {
                "type": "object",
                "properties": {
                  "request_time": {
                    "type": "number",
                    "example": 50
                  }
                },
                "required": [
                  "request_time"
                ]
              }
            },
            "required": [
              "leagues",
              "meta"
            ]
          }
        ]
      },
      "ProfilePlatform": {
        "type": "string",
        "enum": [
          "kalshi",
          "polymarket"
        ]
      },
      "UserProfile": {
        "type": "object",
        "properties": {
          "platform": {
            "$ref": "#/components/schemas/ProfilePlatform"
          },
          "user_id": {
            "type": "string",
            "example": "trader123"
          },
          "display_name": {
            "type": "string",
            "example": "Top Trader"
          },
          "profile_image": {
            "type": "string",
            "example": "https://example.com/avatar.png"
          },
          "description": {
            "type": "string",
            "example": "Prediction market enthusiast"
          },
          "joined_at": {
            "type": "string",
            "example": "2023-01-15T00:00:00Z"
          },
          "follower_count": {
            "type": "number",
            "example": 150
          },
          "following_count": {
            "type": "number",
            "example": 75
          },
          "profile_view_count": {
            "type": "number",
            "example": 5000
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "nullable": true
            }
          }
        },
        "required": [
          "platform",
          "user_id",
          "metadata"
        ]
      },
      "TradingMetrics": {
        "type": "object",
        "properties": {
          "volume": {
            "type": "number",
            "example": 50000
          },
          "pnl": {
            "type": "number",
            "example": 2500
          },
          "roi": {
            "type": "number",
            "example": 0.15
          },
          "num_markets_traded": {
            "type": "number",
            "example": 42
          },
          "portfolio_value": {
            "type": "number",
            "example": 10000
          },
          "open_interest": {
            "type": "number",
            "example": 3500
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "nullable": true
            }
          }
        },
        "required": [
          "volume",
          "pnl",
          "num_markets_traded",
          "metadata"
        ]
      },
      "ProfileMeta": {
        "type": "object",
        "properties": {
          "request_time": {
            "type": "number",
            "example": 150
          },
          "platform": {
            "$ref": "#/components/schemas/ProfilePlatform"
          },
          "data_freshness": {
            "type": "string",
            "example": "2024-11-01T12:30:00Z"
          }
        },
        "required": [
          "request_time",
          "platform",
          "data_freshness"
        ]
      },
      "ProfileInfoResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "profile": {
                "$ref": "#/components/schemas/UserProfile"
              },
              "metrics": {
                "$ref": "#/components/schemas/TradingMetrics"
              }
            },
            "required": [
              "profile"
            ]
          },
          "meta": {
            "$ref": "#/components/schemas/ProfileMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "TradeSide": {
        "type": "string",
        "enum": [
          "buy",
          "sell"
        ]
      },
      "TradeOutcome": {
        "type": "string",
        "enum": [
          "yes",
          "no"
        ]
      },
      "UserTrade": {
        "type": "object",
        "properties": {
          "platform": {
            "$ref": "#/components/schemas/ProfilePlatform"
          },
          "trade_id": {
            "type": "string",
            "example": "trade_abc123"
          },
          "user_id": {
            "type": "string",
            "example": "trader123"
          },
          "market_id": {
            "type": "string",
            "example": "market_xyz"
          },
          "ticker": {
            "type": "string",
            "example": "ELECTION-2024"
          },
          "title": {
            "type": "string",
            "example": "Will X win the election?"
          },
          "side": {
            "$ref": "#/components/schemas/TradeSide"
          },
          "outcome": {
            "$ref": "#/components/schemas/TradeOutcome"
          },
          "price": {
            "type": "number",
            "example": 0.65
          },
          "size": {
            "type": "number",
            "example": 100
          },
          "timestamp": {
            "type": "string",
            "example": "2024-11-01T12:30:00Z"
          },
          "transaction_hash": {
            "type": "string",
            "example": "0x123..."
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "nullable": true
            }
          }
        },
        "required": [
          "platform",
          "trade_id",
          "user_id",
          "market_id",
          "ticker",
          "title",
          "side",
          "outcome",
          "price",
          "size",
          "timestamp",
          "metadata"
        ]
      },
      "ProfileTradesPagination": {
        "type": "object",
        "properties": {
          "total": {
            "type": "number",
            "example": 100
          },
          "limit": {
            "type": "number",
            "example": 50
          },
          "has_more": {
            "type": "boolean",
            "example": true
          },
          "next_cursor": {
            "type": "string",
            "nullable": true,
            "example": "eyJvZmZzZXQiOjUwfQ"
          }
        },
        "required": [
          "total",
          "limit",
          "has_more",
          "next_cursor"
        ]
      },
      "ProfileTradesResponse": {
        "type": "object",
        "properties": {
          "trades": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UserTrade"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/ProfileTradesPagination"
          },
          "meta": {
            "$ref": "#/components/schemas/ProfileMeta"
          }
        },
        "required": [
          "trades",
          "pagination",
          "meta"
        ]
      },
      "OHLCPrice": {
        "type": "object",
        "properties": {
          "close": {
            "type": "number",
            "example": 0.65
          },
          "open": {
            "type": "number",
            "example": 0.6
          },
          "high": {
            "type": "number",
            "example": 0.7
          },
          "low": {
            "type": "number",
            "example": 0.55
          }
        },
        "required": [
          "close"
        ]
      },
      "BidAsk": {
        "type": "object",
        "properties": {
          "bid": {
            "$ref": "#/components/schemas/OHLCPrice"
          },
          "ask": {
            "$ref": "#/components/schemas/OHLCPrice"
          }
        },
        "required": [
          "bid",
          "ask"
        ]
      },
      "PriceHistoryPoint": {
        "type": "object",
        "properties": {
          "timestamp": {
            "type": "number",
            "example": 1700000000
          },
          "price": {
            "$ref": "#/components/schemas/OHLCPrice"
          },
          "volume": {
            "type": "number",
            "example": 10000
          },
          "openInterest": {
            "type": "number",
            "example": 5000
          },
          "bidAsk": {
            "$ref": "#/components/schemas/BidAsk"
          },
          "platform": {
            "type": "string",
            "example": "kalshi"
          },
          "marketId": {
            "type": "string",
            "example": "KXELONMARS-99"
          },
          "outcomeId": {
            "type": "string",
            "example": "yes"
          }
        },
        "required": [
          "timestamp",
          "price",
          "platform",
          "marketId"
        ]
      },
      "PriceHistoryResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PriceHistoryPoint"
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "total_points": {
                "type": "number",
                "example": 500
              },
              "platforms": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "example": [
                  "polymarket",
                  "kalshi"
                ]
              },
              "time_range": {
                "type": "object",
                "properties": {
                  "start": {
                    "type": "number",
                    "example": 1700000000
                  },
                  "end": {
                    "type": "number",
                    "example": 1700100000
                  }
                },
                "required": [
                  "start",
                  "end"
                ]
              },
              "interval": {
                "type": "string",
                "example": "1h"
              },
              "request_time": {
                "type": "number",
                "example": 250
              },
              "cache_hit": {
                "type": "boolean"
              },
              "data_freshness": {
                "type": "string"
              }
            },
            "required": [
              "total_points",
              "platforms",
              "time_range",
              "interval",
              "request_time"
            ]
          }
        },
        "required": [
          "data",
          "meta"
        ]
      }
    },
    "parameters": {}
  },
  "paths": {
    "/health": {
      "get": {
        "operationId": "healthCheck",
        "tags": [
          "Health"
        ],
        "summary": "Health check",
        "description": "Returns the health status of the API with detailed checks",
        "responses": {
          "200": {
            "description": "API is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/": {
      "get": {
        "operationId": "getApiInfo",
        "tags": [
          "Health"
        ],
        "summary": "API information",
        "description": "Returns basic information about the API and available endpoints",
        "responses": {
          "200": {
            "description": "API information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiInfo"
                }
              }
            }
          }
        }
      }
    },
    "/markets": {
      "get": {
        "operationId": "listMarkets",
        "tags": [
          "Markets"
        ],
        "summary": "List markets",
        "description": "Fetch markets from prediction market platforms with pagination",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "Number of items to return (max 100)",
              "example": "50"
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Pagination cursor from previous response"
            },
            "required": false,
            "name": "cursor",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "polymarket",
                "kalshi",
                "limitless",
                "manifold",
                "context"
              ],
              "description": "Filter by specific platform"
            },
            "required": false,
            "name": "platform",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "open",
                "closed",
                "resolved",
                "paused",
                "unopened"
              ],
              "description": "Filter by market status"
            },
            "required": false,
            "name": "status",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Search query - when provided, switches to search mode",
              "example": "bitcoin"
            },
            "required": false,
            "name": "query",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "description": "Include raw platform response data in metadata._raw"
            },
            "required": false,
            "name": "include_raw",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "List of markets",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MarketsResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/markets/{id}": {
      "get": {
        "operationId": "getMarketById",
        "tags": [
          "Markets"
        ],
        "summary": "Get market by ID",
        "description": "Fetch a single market by its ID",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "example": "KXELONMARS-99"
            },
            "required": true,
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "polymarket",
                "kalshi",
                "limitless",
                "manifold",
                "context"
              ],
              "description": "Specify platform to search"
            },
            "required": false,
            "name": "platform",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Include raw platform data in metadata",
              "example": "false"
            },
            "required": false,
            "name": "include_raw",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Market details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MarketResponse"
                }
              }
            }
          },
          "404": {
            "description": "Market not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/markets/{id}/orderbook": {
      "get": {
        "operationId": "getMarketOrderbook",
        "tags": [
          "Markets"
        ],
        "summary": "Get market orderbook",
        "description": "Fetch real-time orderbook (bids and asks) for a market. Supports Polymarket, Kalshi, Limitless, and Manifold.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "example": "KXELONMARS-99"
            },
            "required": true,
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "polymarket",
                "kalshi",
                "limitless",
                "manifold"
              ],
              "description": "Specify platform to fetch orderbook from. If not specified, auto-detects from market ID"
            },
            "required": false,
            "name": "platform",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "description": "Include raw platform response data in metadata._raw"
            },
            "required": false,
            "name": "include_raw",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Orderbook data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderbookResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Orderbook not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/events": {
      "get": {
        "operationId": "listEvents",
        "tags": [
          "Events"
        ],
        "summary": "List events",
        "description": "Fetch events from prediction market platforms with pagination. Only Polymarket and Kalshi support events.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "Number of items to return (max 100)",
              "example": "50"
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Pagination cursor from previous response"
            },
            "required": false,
            "name": "cursor",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "polymarket",
                "kalshi"
              ],
              "description": "Filter by specific platform (only polymarket and kalshi support events)"
            },
            "required": false,
            "name": "platform",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Search query - when provided, switches to search mode",
              "example": "bitcoin"
            },
            "required": false,
            "name": "query",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "description": "Include raw platform response data"
            },
            "required": false,
            "name": "include_raw",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "description": "Include nested markets in events. Defaults to false for v1 compatibility"
            },
            "required": false,
            "name": "include_nested",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "List of events",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventsResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}": {
      "get": {
        "operationId": "getEventById",
        "tags": [
          "Events"
        ],
        "summary": "Get event by ID",
        "description": "Fetch a single event by its ID",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "example": "KXELONMARS-99"
            },
            "required": true,
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "polymarket",
                "kalshi"
              ],
              "description": "Specify platform to search (only polymarket and kalshi support events)"
            },
            "required": false,
            "name": "platform",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "description": "Include raw platform response data"
            },
            "required": false,
            "name": "include_raw",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "description": "Include nested markets in event"
            },
            "required": false,
            "name": "include_nested",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Event details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventResponse"
                }
              }
            }
          },
          "404": {
            "description": "Event not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/series": {
      "get": {
        "operationId": "listSeries",
        "tags": [
          "Series"
        ],
        "summary": "List series",
        "description": "Fetch series from prediction market platforms with pagination. Only Polymarket and Kalshi support series.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "Number of items to return (max 100)",
              "example": "50"
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Pagination cursor from previous response"
            },
            "required": false,
            "name": "cursor",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "polymarket",
                "kalshi"
              ],
              "description": "Filter by specific platform (only polymarket and kalshi support series)"
            },
            "required": false,
            "name": "platform",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Search query - when provided, switches to search mode",
              "example": "bitcoin"
            },
            "required": false,
            "name": "query",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "description": "Include raw platform response data"
            },
            "required": false,
            "name": "include_raw",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "description": "Include nested events in series. Defaults to false for v1 compatibility"
            },
            "required": false,
            "name": "include_nested",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "List of series",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SeriesListResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/series/{id}": {
      "get": {
        "operationId": "getSeriesById",
        "tags": [
          "Series"
        ],
        "summary": "Get series by ID",
        "description": "Fetch a single series by its ID",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "example": "KXELONMARS-99"
            },
            "required": true,
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "polymarket",
                "kalshi"
              ],
              "description": "Specify platform to search (only polymarket and kalshi support series)"
            },
            "required": false,
            "name": "platform",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "description": "Include raw platform response data"
            },
            "required": false,
            "name": "include_raw",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "description": "Include nested events in series"
            },
            "required": false,
            "name": "include_nested",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Series details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SeriesResponse"
                }
              }
            }
          },
          "404": {
            "description": "Series not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/platforms": {
      "get": {
        "operationId": "listPlatforms",
        "tags": [
          "Platforms"
        ],
        "summary": "List platforms",
        "description": "Get all available prediction market platforms",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "List of platforms",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/search": {
      "get": {
        "operationId": "searchMarkets",
        "tags": [
          "Search"
        ],
        "summary": "Search markets",
        "description": "Search for markets across all platforms by keyword",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "Search query string",
              "example": "bitcoin"
            },
            "required": true,
            "name": "q",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Number of results to return (max 100)",
              "example": "20"
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "polymarket",
                "kalshi",
                "limitless",
                "manifold",
                "context"
              ],
              "description": "Filter by specific platform"
            },
            "required": false,
            "name": "platform",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing query",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/trades": {
      "get": {
        "operationId": "getTrades",
        "tags": [
          "Trades"
        ],
        "summary": "Get trades for a market",
        "description": "Fetch historical trades for a specific market with pagination",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "Market ID to fetch trades for",
              "example": "524153"
            },
            "required": true,
            "name": "market_id",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Number of trades to return (max 1000)",
              "example": "100"
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Pagination cursor from previous response"
            },
            "required": false,
            "name": "cursor",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "description": "Filter to taker-only trades (Polymarket only)",
              "example": "true"
            },
            "required": false,
            "name": "takerOnly",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "List of trades",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TradesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/historical-orderbook": {
      "get": {
        "operationId": "getHistoricalOrderbook",
        "tags": [
          "Orderbook"
        ],
        "summary": "Get historical orderbook snapshots",
        "description": "Fetch historical orderbook snapshots for a market within a time range. Data is collected every 30 minutes.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "Market ID to fetch historical orderbook for",
              "example": "524153"
            },
            "required": true,
            "name": "market_id",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Start timestamp (Unix milliseconds)",
              "example": "1700000000000"
            },
            "required": true,
            "name": "start_time",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "End timestamp (Unix milliseconds)",
              "example": "1700100000000"
            },
            "required": true,
            "name": "end_time",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "polymarket",
                "kalshi"
              ],
              "description": "Platform (defaults to polymarket)",
              "example": "polymarket"
            },
            "required": false,
            "name": "platform",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Maximum number of snapshots to return (max 500)",
              "example": "100"
            },
            "required": false,
            "name": "limit",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Historical orderbook snapshots",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HistoricalOrderbookResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/list-games": {
      "get": {
        "operationId": "listGames",
        "tags": [
          "Sports"
        ],
        "summary": "List games",
        "description": "Fetch upcoming and recent games from sports prediction markets",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "$ref": "#/components/schemas/League"
            },
            "required": true,
            "name": "league",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "List of games",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GamesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/games/{id}": {
      "get": {
        "operationId": "getGameById",
        "tags": [
          "Sports"
        ],
        "summary": "Get game by ID",
        "description": "Fetch a single game by its ID with market data from all platforms",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "Game ID (format: {Away}v{Home}{YYYYMMDD}@{LEAGUE})",
              "example": "KCvSF20250209@NFL"
            },
            "required": true,
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/SportsPlatform"
                },
                {
                  "description": "Filter by platform"
                }
              ]
            },
            "required": false,
            "name": "platform",
            "in": "query"
          },
          {
            "schema": {
              "$ref": "#/components/schemas/SportsMarketType"
            },
            "required": false,
            "name": "market_type",
            "in": "query"
          },
          {
            "schema": {
              "$ref": "#/components/schemas/OddsFormat"
            },
            "required": false,
            "name": "odds_format",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Game details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GameResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Game not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/list-awards": {
      "get": {
        "operationId": "listAwards",
        "tags": [
          "Sports"
        ],
        "summary": "List awards",
        "description": "Fetch available award markets (MVP, DPOY, etc.) for a league",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "$ref": "#/components/schemas/League"
            },
            "required": true,
            "name": "league",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter by award type (mvp, dpoy, opoy, etc.)",
              "example": "mvp"
            },
            "required": false,
            "name": "award_type",
            "in": "query"
          },
          {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/SportsPlatform"
                },
                {
                  "description": "Filter by platform"
                }
              ]
            },
            "required": false,
            "name": "platform",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "List of awards",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListAwardsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/awards/{id}": {
      "get": {
        "operationId": "getAwardById",
        "tags": [
          "Sports"
        ],
        "summary": "Get award by ID",
        "description": "Fetch a single award with live market data from all platforms",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "Award ID",
              "example": "nfl_mvp_2024"
            },
            "required": true,
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Award details with market data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AwardResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Award not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/list-futures": {
      "get": {
        "operationId": "listFutures",
        "tags": [
          "Sports"
        ],
        "summary": "List futures",
        "description": "Fetch available futures markets (Super Bowl, division winners, etc.) for a league",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "$ref": "#/components/schemas/League"
            },
            "required": true,
            "name": "league",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter by future type (championship, division, conference)",
              "example": "championship"
            },
            "required": false,
            "name": "future_type",
            "in": "query"
          },
          {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/SportsPlatform"
                },
                {
                  "description": "Filter by platform"
                }
              ]
            },
            "required": false,
            "name": "platform",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "List of futures",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListFuturesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/futures/{id}": {
      "get": {
        "operationId": "getFutureById",
        "tags": [
          "Sports"
        ],
        "summary": "Get future by ID",
        "description": "Fetch a single future with live market data from all platforms",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "Future ID",
              "example": "nfl_superbowl_2025"
            },
            "required": true,
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Future details with market data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FutureResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Future not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/league-info": {
      "get": {
        "operationId": "getLeagueInfo",
        "tags": [
          "Sports"
        ],
        "summary": "Get league information",
        "description": "Fetch information about supported sports leagues, including available endpoints and team counts",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/League"
                },
                {
                  "description": "Specific league to query (optional, returns all if not specified)"
                }
              ]
            },
            "required": false,
            "name": "league",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Include team information in response",
              "example": "true"
            },
            "required": false,
            "name": "include_teams",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "League information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LeagueInfoResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "League not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/profile/info": {
      "get": {
        "operationId": "getProfileInfo",
        "tags": [
          "Profile"
        ],
        "summary": "Get user profile",
        "description": "Fetch user profile information and optionally trading metrics from Kalshi or Polymarket",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/ProfilePlatform"
                },
                {
                  "description": "Platform to query (kalshi or polymarket)"
                }
              ]
            },
            "required": true,
            "name": "platform",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "description": "User identifier (nickname for Kalshi, wallet address for Polymarket)",
              "example": "trader123"
            },
            "required": true,
            "name": "user",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "description": "Include trading metrics in response (true/false)",
              "example": "true"
            },
            "required": false,
            "name": "include_metrics",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "User profile information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProfileInfoResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "User not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/profile/trades": {
      "get": {
        "operationId": "getProfileTrades",
        "tags": [
          "Profile"
        ],
        "summary": "Get user trades",
        "description": "Fetch trade history for a user from Kalshi or Polymarket",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/ProfilePlatform"
                },
                {
                  "description": "Platform to query (kalshi or polymarket)"
                }
              ]
            },
            "required": true,
            "name": "platform",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "description": "User identifier (nickname for Kalshi, wallet address for Polymarket)",
              "example": "trader123"
            },
            "required": true,
            "name": "user",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Number of trades to return (max 100)",
              "example": "50"
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Pagination cursor"
            },
            "required": false,
            "name": "cursor",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "User trade history",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProfileTradesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/price-history": {
      "get": {
        "operationId": "getPriceHistory",
        "tags": [
          "Markets"
        ],
        "summary": "Get price history for markets",
        "description": "Fetch historical price data (OHLC candlesticks) for one or more markets",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated list of market IDs (max 10)",
              "example": "524153,KXELONMARS-99"
            },
            "required": true,
            "name": "market_ids",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Start timestamp (Unix seconds)",
              "example": "1700000000"
            },
            "required": true,
            "name": "start_ts",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "End timestamp (Unix seconds)",
              "example": "1700100000"
            },
            "required": true,
            "name": "end_ts",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "1",
                "60",
                "1440"
              ],
              "description": "Time interval in minutes. Supported: 1 (1 minute), 60 (1 hour), 1440 (1 day)",
              "example": "60"
            },
            "required": false,
            "name": "interval",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Maximum number of points to return (max 5000)",
              "example": "1000"
            },
            "required": false,
            "name": "limit",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Price history data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PriceHistoryResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  }
}