{ "openapi": "3.1.0", "info": { "title": "Marilux 明海数据 · 美股股票与期权数据 API", "version": "2026-10-20", "description": "美股股票、ETF 与期权数据 API。接口路径和返回结构与 Polygon 一致，可直接使用 Polygon SDK（把 base 改成本服务地址）。\n\n- 套餐：Starter（延迟约 15 分钟、5 年历史）、Advanced（实时、20 年以上历史、逐笔与基本面、WebSocket）、期权套餐（可单独购买，与股票共用同一个 Key）。各接口标注了 x-plan。\n- 调用套餐外的接口返回 404，超出套餐历史范围返回 403，不会静默返回错误数据。\n- 列表接口用响应里的 next_url 翻页，next_url 已带上全部查询条件。\n- WebSocket 实时推送（Advanced）：wss://marilux.dev/stocks，协议与 Polygon WebSocket 一致，不在本文件内描述，见 https://marilux.dev/docs/websocket。\n- 额度、速率与响应头见 https://marilux.dev/docs/limits，错误码见 https://marilux.dev/docs/errors。", "contact": { "name": "Marilux 明海数据", "url": "https://marilux.dev", "email": "Contact@marilux.dev" } }, "externalDocs": { "description": "中文文档", "url": "https://marilux.dev/docs" }, "servers": [ { "url": "https://marilux.dev" } ], "security": [ { "bearerAuth": [] }, { "apiKeyQuery": [] } ], "tags": [ { "name": "股票行情", "description": "K线、全市场日线、单日开高低收" }, { "name": "参考数据", "description": "股票代码、交易所、市场状态" }, { "name": "公司行为", "description": "拆股、分红、代码变更、IPO" }, { "name": "快照", "description": "最新价格、涨跌榜" }, { "name": "逐笔与基本面", "description": "Advanced 套餐：逐笔成交与报价、财务数据、卖空、流通股" }, { "name": "期权", "description": "期权套餐：合约、期权链快照（希腊值、隐含波动率）。期权K线和逐笔数据使用股票行情接口，把代码换成期权代码" }, { "name": "Flat Files", "description": "全市场历史K线批量下载" } ], "paths": { "/v2/aggs/ticker/{ticker}/range/{multiplier}/{timespan}/{from}/{to}": { "get": { "operationId": "getAggregates", "tags": [ "股票行情" ], "summary": "历史K线", "description": "指定时间粒度和区间的K线（聚合行情）。期权K线把 ticker 换成期权代码即可。Starter 可查最近 5 年，Advanced 20 年以上，超出范围返回 403。", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "股票代码，如 AAPL；期权代码如 O:AAPL271217C00300000 同样适用（需开通期权套餐）", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "multiplier", "in": "path", "required": true, "description": "粒度倍数，如 5 表示 5 分钟K", "schema": { "type": "integer" }, "example": 1 }, { "name": "timespan", "in": "path", "required": true, "description": "粒度单位", "schema": { "type": "string", "enum": [ "second", "minute", "hour", "day", "week", "month", "quarter", "year" ] }, "example": "day" }, { "name": "from", "in": "path", "required": true, "description": "开始日期（YYYY-MM-DD）或毫秒时间戳", "schema": { "type": "string", "format": "date" }, "example": "2024-01-02" }, { "name": "to", "in": "path", "required": true, "description": "结束日期（YYYY-MM-DD）或毫秒时间戳", "schema": { "type": "string", "format": "date" }, "example": "2024-01-05" }, { "name": "adjusted", "in": "query", "required": false, "description": "是否按拆股复权，默认 true", "schema": { "type": "boolean" }, "example": true }, { "name": "sort", "in": "query", "required": false, "description": "按时间排序", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "limit", "in": "query", "required": false, "description": "每页条数，最大 50000。更多数据用响应里的 next_url 翻页", "schema": { "type": "integer", "minimum": 1, "maximum": 50000 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AggsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/aggs/ticker/{ticker}/prev": { "get": { "operationId": "getPreviousClose", "tags": [ "股票行情" ], "summary": "上一交易日K线", "description": "上一交易日的开高低收。", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "股票代码，如 AAPL；期权代码如 O:AAPL271217C00300000 同样适用（需开通期权套餐）", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "adjusted", "in": "query", "required": false, "description": "是否按拆股复权，默认 true", "schema": { "type": "boolean" }, "example": true } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AggsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/aggs/grouped/locale/us/market/stocks/{date}": { "get": { "operationId": "getGroupedDaily", "tags": [ "股票行情" ], "summary": "全市场日线", "description": "某个交易日全市场股票的日K，量化回测、复盘常用。", "parameters": [ { "name": "date", "in": "path", "required": true, "description": "交易日", "schema": { "type": "string", "format": "date" }, "example": "2024-01-02" }, { "name": "adjusted", "in": "query", "required": false, "description": "是否按拆股复权，默认 true", "schema": { "type": "boolean" }, "example": true }, { "name": "include_otc", "in": "query", "required": false, "description": "是否包含 OTC 股票", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupedResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/open-close/{ticker}/{date}": { "get": { "operationId": "getDailyOpenClose", "tags": [ "股票行情" ], "summary": "单日开高低收", "description": "指定股票（或期权合约）在某个交易日的开高低收，含盘前盘后价。", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "股票代码，如 AAPL；期权代码如 O:AAPL271217C00300000 同样适用（需开通期权套餐）", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "date", "in": "path", "required": true, "description": "交易日", "schema": { "type": "string", "format": "date" }, "example": "2024-01-02" }, { "name": "adjusted", "in": "query", "required": false, "description": "是否按拆股复权，默认 true", "schema": { "type": "boolean" }, "example": true } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenClose" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v3/reference/tickers": { "get": { "operationId": "listTickers", "tags": [ "参考数据" ], "summary": "股票代码列表", "description": "股票、ETF 基础信息检索，支持按代码、类型、交易所、状态过滤。", "parameters": [ { "name": "ticker", "in": "query", "required": false, "description": "精确匹配代码", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "type", "in": "query", "required": false, "description": "证券类型，如 CS（普通股）、ETF", "schema": { "type": "string" } }, { "name": "market", "in": "query", "required": false, "description": "市场", "schema": { "type": "string", "enum": [ "stocks", "otc" ] } }, { "name": "exchange", "in": "query", "required": false, "description": "主交易所 MIC，如 XNAS", "schema": { "type": "string" } }, { "name": "cik", "in": "query", "required": false, "description": "SEC CIK", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "按代码或名称模糊搜索", "schema": { "type": "string" } }, { "name": "active", "in": "query", "required": false, "description": "是否仍在交易，默认 true", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "required": false, "description": "排序字段", "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "description": "排序方向", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "limit", "in": "query", "required": false, "description": "每页条数，最大 1000。更多数据用响应里的 next_url 翻页", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "request_id": { "type": "string" }, "count": { "type": "integer" }, "next_url": { "type": "string", "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Ticker" } } }, "required": [ "results" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v3/reference/tickers/{ticker}": { "get": { "operationId": "getTickerDetails", "tags": [ "参考数据" ], "summary": "股票详情", "description": "单只股票/ETF 的详细资料：CIK、FIGI、市值、行业分类、上市日期等。品牌图片链接暂不提供下载。", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "股票代码，如 AAPL；期权代码如 O:AAPL271217C00300000 同样适用（需开通期权套餐）", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "date", "in": "query", "required": false, "description": "查某一天当时的资料（YYYY-MM-DD）", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "results": { "$ref": "#/components/schemas/TickerDetails" } }, "required": [ "results" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v3/reference/splits": { "get": { "operationId": "listSplits", "tags": [ "公司行为" ], "summary": "拆股历史", "description": "拆股/合股历史，计算复权价时和分红数据一起使用。", "parameters": [ { "name": "ticker", "in": "query", "required": false, "description": "股票代码", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "execution_date", "in": "query", "required": false, "description": "生效日期", "schema": { "type": "string" } }, { "name": "execution_date.gte", "in": "query", "required": false, "description": "生效日期（大于等于）", "schema": { "type": "string" } }, { "name": "execution_date.lte", "in": "query", "required": false, "description": "生效日期（小于等于）", "schema": { "type": "string" } }, { "name": "execution_date.gt", "in": "query", "required": false, "description": "生效日期（大于）", "schema": { "type": "string" } }, { "name": "execution_date.lt", "in": "query", "required": false, "description": "生效日期（小于）", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "排序字段", "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "description": "排序方向", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "limit", "in": "query", "required": false, "description": "每页条数，最大 1000。更多数据用响应里的 next_url 翻页", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "request_id": { "type": "string" }, "count": { "type": "integer" }, "next_url": { "type": "string", "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Split" } } }, "required": [ "results" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v3/reference/dividends": { "get": { "operationId": "listDividends", "tags": [ "公司行为" ], "summary": "分红历史", "description": "现金分红历史。", "parameters": [ { "name": "ticker", "in": "query", "required": false, "description": "股票代码", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "ex_dividend_date", "in": "query", "required": false, "description": "除息日", "schema": { "type": "string" } }, { "name": "ex_dividend_date.gte", "in": "query", "required": false, "description": "除息日（大于等于）", "schema": { "type": "string" } }, { "name": "ex_dividend_date.lte", "in": "query", "required": false, "description": "除息日（小于等于）", "schema": { "type": "string" } }, { "name": "ex_dividend_date.gt", "in": "query", "required": false, "description": "除息日（大于）", "schema": { "type": "string" } }, { "name": "ex_dividend_date.lt", "in": "query", "required": false, "description": "除息日（小于）", "schema": { "type": "string" } }, { "name": "frequency", "in": "query", "required": false, "description": "每年分红次数", "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "required": false, "description": "排序字段", "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "description": "排序方向", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "limit", "in": "query", "required": false, "description": "每页条数，最大 1000。更多数据用响应里的 next_url 翻页", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "request_id": { "type": "string" }, "count": { "type": "integer" }, "next_url": { "type": "string", "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Dividend" } } }, "required": [ "results" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/stocks/v1/splits": { "get": { "operationId": "listSplitsWithFactors", "tags": [ "公司行为" ], "summary": "拆股（含复权因子）", "description": "新版拆股接口，比 /v3/reference/splits 多了 adjustment_type 和 historical_adjustment_factor（历史复权因子）。", "parameters": [ { "name": "ticker", "in": "query", "required": false, "description": "股票代码", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "execution_date", "in": "query", "required": false, "description": "生效日期", "schema": { "type": "string" } }, { "name": "execution_date.gte", "in": "query", "required": false, "description": "生效日期（大于等于）", "schema": { "type": "string" } }, { "name": "execution_date.lte", "in": "query", "required": false, "description": "生效日期（小于等于）", "schema": { "type": "string" } }, { "name": "execution_date.gt", "in": "query", "required": false, "description": "生效日期（大于）", "schema": { "type": "string" } }, { "name": "execution_date.lt", "in": "query", "required": false, "description": "生效日期（小于）", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "排序，如 execution_date.desc", "schema": { "type": "string" }, "example": "execution_date.desc" }, { "name": "limit", "in": "query", "required": false, "description": "每页条数，最大 5000。更多数据用响应里的 next_url 翻页", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "request_id": { "type": "string" }, "count": { "type": "integer" }, "next_url": { "type": "string", "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SplitV1" } } }, "required": [ "results" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/stocks/v1/dividends": { "get": { "operationId": "listDividendsWithFactors", "tags": [ "公司行为" ], "summary": "分红（含复权因子）", "description": "新版分红接口，多了 historical_adjustment_factor（分红复权因子）和 split_adjusted_cash_amount。", "parameters": [ { "name": "ticker", "in": "query", "required": false, "description": "股票代码", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "ex_dividend_date", "in": "query", "required": false, "description": "除息日", "schema": { "type": "string" } }, { "name": "ex_dividend_date.gte", "in": "query", "required": false, "description": "除息日（大于等于）", "schema": { "type": "string" } }, { "name": "ex_dividend_date.lte", "in": "query", "required": false, "description": "除息日（小于等于）", "schema": { "type": "string" } }, { "name": "ex_dividend_date.gt", "in": "query", "required": false, "description": "除息日（大于）", "schema": { "type": "string" } }, { "name": "ex_dividend_date.lt", "in": "query", "required": false, "description": "除息日（小于）", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "排序，如 ex_dividend_date.desc", "schema": { "type": "string" }, "example": "ex_dividend_date.desc" }, { "name": "limit", "in": "query", "required": false, "description": "每页条数，最大 5000。更多数据用响应里的 next_url 翻页", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 }, "example": 4 } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "request_id": { "type": "string" }, "count": { "type": "integer" }, "next_url": { "type": "string", "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/DividendV1" } } }, "required": [ "results" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/vX/reference/tickers/{id}/events": { "get": { "operationId": "getTickerEvents", "tags": [ "公司行为" ], "summary": "代码变更历史", "description": "改名、换代码历史。做历史回测时用它把旧代码对应到现在的公司，比如 FB → META。", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "股票代码、CUSIP 或 composite FIGI", "schema": { "type": "string" }, "example": "META" }, { "name": "types", "in": "query", "required": false, "description": "事件类型，目前为 ticker_change", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TickerEvents" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/vX/reference/ipos": { "get": { "operationId": "listIpos", "tags": [ "公司行为" ], "summary": "IPO 日历", "description": "即将上市、正在发行和已上市的新股，含发行价区间、发行股数、上市日期和状态。数据每天更新。", "parameters": [ { "name": "ticker", "in": "query", "required": false, "description": "股票代码", "schema": { "type": "string" } }, { "name": "ipo_status", "in": "query", "required": false, "description": "IPO 状态", "schema": { "type": "string", "enum": [ "direct_listing_process", "history", "new", "pending", "postponed", "rumor", "withdrawn" ] }, "example": "history" }, { "name": "listing_date", "in": "query", "required": false, "description": "上市日期（只能用于筛选，返回结果里没有这个字段）", "schema": { "type": "string" } }, { "name": "listing_date.gte", "in": "query", "required": false, "description": "上市日期（只能用于筛选，返回结果里没有这个字段）（大于等于）", "schema": { "type": "string" } }, { "name": "listing_date.lte", "in": "query", "required": false, "description": "上市日期（只能用于筛选，返回结果里没有这个字段）（小于等于）", "schema": { "type": "string" } }, { "name": "listing_date.gt", "in": "query", "required": false, "description": "上市日期（只能用于筛选，返回结果里没有这个字段）（大于）", "schema": { "type": "string" } }, { "name": "listing_date.lt", "in": "query", "required": false, "description": "上市日期（只能用于筛选，返回结果里没有这个字段）（小于）", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "排序字段，默认按上市日期", "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "description": "排序方向", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "limit", "in": "query", "required": false, "description": "每页条数，最大 1000。更多数据用响应里的 next_url 翻页", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 }, "example": 10 } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "request_id": { "type": "string" }, "count": { "type": "integer" }, "next_url": { "type": "string", "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Ipo" } } }, "required": [ "results" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v3/reference/exchanges": { "get": { "operationId": "listExchanges", "tags": [ "参考数据" ], "summary": "交易所列表", "description": "交易所及基础信息。", "parameters": [ { "name": "asset_class", "in": "query", "required": false, "description": "资产类别", "schema": { "type": "string", "enum": [ "stocks", "options" ] }, "example": "stocks" }, { "name": "locale", "in": "query", "required": false, "description": "地区", "schema": { "type": "string", "enum": [ "us" ] } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "count": { "type": "integer" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Exchange" } } }, "required": [ "results" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/marketstatus/now": { "get": { "operationId": "getMarketStatus", "tags": [ "参考数据" ], "summary": "当前市场状态", "description": "美股当前是否开盘、盘前盘后状态。", "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/marketstatus/upcoming": { "get": { "operationId": "getMarketHolidays", "tags": [ "参考数据" ], "summary": "即将到来的休市日", "description": "即将到来的休市和提前收盘安排。", "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MarketHoliday" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/snapshot/locale/us/markets/stocks/tickers": { "get": { "operationId": "getStockSnapshots", "tags": [ "快照" ], "summary": "全市场快照", "description": "全市场（或用 tickers 指定的多只）股票的最新价格、当日K线和上一交易日数据。价格按套餐的延迟规则提供。", "parameters": [ { "name": "tickers", "in": "query", "required": false, "description": "逗号分隔的代码，不填为全市场", "schema": { "type": "string" }, "example": "AAPL,MSFT" }, { "name": "include_otc", "in": "query", "required": false, "description": "是否包含 OTC", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "count": { "type": "integer" }, "tickers": { "type": "array", "items": { "$ref": "#/components/schemas/StockSnapshot" } } }, "required": [ "tickers" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/snapshot/locale/us/markets/stocks/tickers/{ticker}": { "get": { "operationId": "getStockSnapshot", "tags": [ "快照" ], "summary": "单只股票快照", "description": "单只股票的最新价格、当日K线和上一交易日数据。", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "股票代码，如 AAPL；期权代码如 O:AAPL271217C00300000 同样适用（需开通期权套餐）", "schema": { "type": "string" }, "example": "AAPL" } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "ticker": { "$ref": "#/components/schemas/StockSnapshot" } }, "required": [ "ticker" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/snapshot/locale/us/markets/stocks/{direction}": { "get": { "operationId": "getGainersLosers", "tags": [ "快照" ], "summary": "涨跌榜", "description": "当日涨幅榜（gainers）或跌幅榜（losers）前 20 名。", "parameters": [ { "name": "direction", "in": "path", "required": true, "description": "涨幅榜或跌幅榜", "schema": { "type": "string", "enum": [ "gainers", "losers" ] }, "example": "gainers" }, { "name": "include_otc", "in": "query", "required": false, "description": "是否包含 OTC", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "tickers": { "type": "array", "items": { "$ref": "#/components/schemas/StockSnapshot" } } }, "required": [ "tickers" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v3/trades/{ticker}": { "get": { "operationId": "listTrades", "tags": [ "逐笔与基本面" ], "summary": "逐笔成交", "description": "**Advanced 套餐专属**，Starter 套餐调用返回 404。指定股票在时间范围内的逐笔成交。期权逐笔成交把 ticker 换成期权代码（需期权套餐）。", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "股票代码，如 AAPL；期权代码如 O:AAPL271217C00300000 同样适用（需开通期权套餐）", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "timestamp", "in": "query", "required": false, "description": "按日期（YYYY-MM-DD）或纳秒时间戳筛选", "schema": { "type": "string" }, "example": "2024-01-02" }, { "name": "timestamp.gte", "in": "query", "required": false, "description": "时间下限（含）", "schema": { "type": "string" } }, { "name": "timestamp.lt", "in": "query", "required": false, "description": "时间上限（不含）", "schema": { "type": "string" } }, { "name": "timestamp.lte", "in": "query", "required": false, "description": "时间上限（含）", "schema": { "type": "string" } }, { "name": "timestamp.gt", "in": "query", "required": false, "description": "时间下限（不含）", "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "description": "排序方向", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "sort", "in": "query", "required": false, "description": "排序字段，默认 timestamp", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "每页条数，最大 50000。更多数据用响应里的 next_url 翻页", "schema": { "type": "integer", "minimum": 1, "maximum": 50000 }, "example": 10 } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "request_id": { "type": "string" }, "count": { "type": "integer" }, "next_url": { "type": "string", "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Trade" } } }, "required": [ "results" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-plan": "advanced" } }, "/v3/quotes/{ticker}": { "get": { "operationId": "listQuotes", "tags": [ "逐笔与基本面" ], "summary": "逐笔报价（NBBO）", "description": "**Advanced 套餐专属**，Starter 套餐调用返回 404。指定股票在时间范围内的买一卖一报价。期权报价把 ticker 换成期权代码（需期权套餐）。", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "股票代码，如 AAPL；期权代码如 O:AAPL271217C00300000 同样适用（需开通期权套餐）", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "timestamp", "in": "query", "required": false, "description": "按日期（YYYY-MM-DD）或纳秒时间戳筛选", "schema": { "type": "string" }, "example": "2024-01-02" }, { "name": "timestamp.gte", "in": "query", "required": false, "description": "时间下限（含）", "schema": { "type": "string" } }, { "name": "timestamp.lt", "in": "query", "required": false, "description": "时间上限（不含）", "schema": { "type": "string" } }, { "name": "timestamp.lte", "in": "query", "required": false, "description": "时间上限（含）", "schema": { "type": "string" } }, { "name": "timestamp.gt", "in": "query", "required": false, "description": "时间下限（不含）", "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "description": "排序方向", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "sort", "in": "query", "required": false, "description": "排序字段，默认 timestamp", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "每页条数，最大 50000。更多数据用响应里的 next_url 翻页", "schema": { "type": "integer", "minimum": 1, "maximum": 50000 }, "example": 10 } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "request_id": { "type": "string" }, "count": { "type": "integer" }, "next_url": { "type": "string", "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Quote" } } }, "required": [ "results" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-plan": "advanced" } }, "/stocks/financials/v1/ratios": { "get": { "operationId": "listFinancialRatios", "tags": [ "逐笔与基本面" ], "summary": "财务比率", "description": "**Advanced 套餐专属**，Starter 套餐调用返回 404。估值、盈利能力、偿债能力等财务比率。注意参数名是 ticker（单数）。", "parameters": [ { "name": "ticker", "in": "query", "required": false, "description": "股票代码", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "limit", "in": "query", "required": false, "description": "每页条数，最大 50000。更多数据用响应里的 next_url 翻页", "schema": { "type": "integer", "minimum": 1, "maximum": 50000 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "request_id": { "type": "string" }, "count": { "type": "integer" }, "next_url": { "type": "string", "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Ratios" } } }, "required": [ "results" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-plan": "advanced" } }, "/stocks/financials/v1/income-statements": { "get": { "operationId": "listIncomeStatements", "tags": [ "逐笔与基本面" ], "summary": "利润表", "description": "**Advanced 套餐专属**，Starter 套餐调用返回 404。注意参数名是 tickers（复数）。参数名写错不会报错，而是返回未筛选的全市场数据。", "parameters": [ { "name": "tickers", "in": "query", "required": false, "description": "股票代码", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "cik", "in": "query", "required": false, "description": "SEC CIK", "schema": { "type": "string" } }, { "name": "fiscal_year", "in": "query", "required": false, "description": "财年", "schema": { "type": "integer" }, "example": 2024 }, { "name": "fiscal_quarter", "in": "query", "required": false, "description": "财季 1–4", "schema": { "type": "integer" } }, { "name": "timeframe", "in": "query", "required": false, "description": "报告周期", "schema": { "type": "string", "enum": [ "annual", "quarterly", "trailing_twelve_months" ] } }, { "name": "sort", "in": "query", "required": false, "description": "排序", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "每页条数，最大 50000。更多数据用响应里的 next_url 翻页", "schema": { "type": "integer", "minimum": 1, "maximum": 50000 }, "example": 4 } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "request_id": { "type": "string" }, "count": { "type": "integer" }, "next_url": { "type": "string", "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/IncomeStatement" } } }, "required": [ "results" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-plan": "advanced" } }, "/stocks/financials/v1/balance-sheets": { "get": { "operationId": "listBalanceSheets", "tags": [ "逐笔与基本面" ], "summary": "资产负债表", "description": "**Advanced 套餐专属**，Starter 套餐调用返回 404。注意参数名是 tickers（复数）。参数名写错不会报错，而是返回未筛选的全市场数据。", "parameters": [ { "name": "tickers", "in": "query", "required": false, "description": "股票代码", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "cik", "in": "query", "required": false, "description": "SEC CIK", "schema": { "type": "string" } }, { "name": "fiscal_year", "in": "query", "required": false, "description": "财年", "schema": { "type": "integer" }, "example": 2024 }, { "name": "fiscal_quarter", "in": "query", "required": false, "description": "财季 1–4", "schema": { "type": "integer" } }, { "name": "timeframe", "in": "query", "required": false, "description": "报告周期", "schema": { "type": "string", "enum": [ "annual", "quarterly", "trailing_twelve_months" ] } }, { "name": "sort", "in": "query", "required": false, "description": "排序", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "每页条数，最大 50000。更多数据用响应里的 next_url 翻页", "schema": { "type": "integer", "minimum": 1, "maximum": 50000 }, "example": 4 } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "request_id": { "type": "string" }, "count": { "type": "integer" }, "next_url": { "type": "string", "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/BalanceSheet" } } }, "required": [ "results" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-plan": "advanced" } }, "/stocks/financials/v1/cash-flow-statements": { "get": { "operationId": "listCashFlowStatements", "tags": [ "逐笔与基本面" ], "summary": "现金流量表", "description": "**Advanced 套餐专属**，Starter 套餐调用返回 404。注意参数名是 tickers（复数）。参数名写错不会报错，而是返回未筛选的全市场数据。", "parameters": [ { "name": "tickers", "in": "query", "required": false, "description": "股票代码", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "cik", "in": "query", "required": false, "description": "SEC CIK", "schema": { "type": "string" } }, { "name": "fiscal_year", "in": "query", "required": false, "description": "财年", "schema": { "type": "integer" }, "example": 2024 }, { "name": "fiscal_quarter", "in": "query", "required": false, "description": "财季 1–4", "schema": { "type": "integer" } }, { "name": "timeframe", "in": "query", "required": false, "description": "报告周期", "schema": { "type": "string", "enum": [ "annual", "quarterly", "trailing_twelve_months" ] } }, { "name": "sort", "in": "query", "required": false, "description": "排序", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "每页条数，最大 50000。更多数据用响应里的 next_url 翻页", "schema": { "type": "integer", "minimum": 1, "maximum": 50000 }, "example": 4 } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "request_id": { "type": "string" }, "count": { "type": "integer" }, "next_url": { "type": "string", "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CashFlowStatement" } } }, "required": [ "results" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-plan": "advanced" } }, "/stocks/v1/short-interest": { "get": { "operationId": "listShortInterest", "tags": [ "逐笔与基本面" ], "summary": "卖空持仓", "description": "**Advanced 套餐专属**，Starter 套餐调用返回 404。每半月结算一次的卖空股数、日均成交量和回补天数。", "parameters": [ { "name": "ticker", "in": "query", "required": false, "description": "股票代码", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "settlement_date", "in": "query", "required": false, "description": "结算日", "schema": { "type": "string" } }, { "name": "settlement_date.gte", "in": "query", "required": false, "description": "结算日（大于等于）", "schema": { "type": "string" } }, { "name": "settlement_date.lte", "in": "query", "required": false, "description": "结算日（小于等于）", "schema": { "type": "string" } }, { "name": "settlement_date.gt", "in": "query", "required": false, "description": "结算日（大于）", "schema": { "type": "string" } }, { "name": "settlement_date.lt", "in": "query", "required": false, "description": "结算日（小于）", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "排序，如 settlement_date.desc", "schema": { "type": "string" }, "example": "settlement_date.desc" }, { "name": "limit", "in": "query", "required": false, "description": "每页条数，最大 50000。更多数据用响应里的 next_url 翻页", "schema": { "type": "integer", "minimum": 1, "maximum": 50000 }, "example": 1 } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "request_id": { "type": "string" }, "count": { "type": "integer" }, "next_url": { "type": "string", "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ShortInterest" } } }, "required": [ "results" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-plan": "advanced" } }, "/stocks/v1/short-volume": { "get": { "operationId": "listShortVolume", "tags": [ "逐笔与基本面" ], "summary": "每日卖空成交量", "description": "**Advanced 套餐专属**，Starter 套餐调用返回 404。每日卖空成交量和卖空占比。", "parameters": [ { "name": "ticker", "in": "query", "required": false, "description": "股票代码", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "date", "in": "query", "required": false, "description": "日期", "schema": { "type": "string" } }, { "name": "date.gte", "in": "query", "required": false, "description": "日期（大于等于）", "schema": { "type": "string" } }, { "name": "date.lte", "in": "query", "required": false, "description": "日期（小于等于）", "schema": { "type": "string" } }, { "name": "date.gt", "in": "query", "required": false, "description": "日期（大于）", "schema": { "type": "string" } }, { "name": "date.lt", "in": "query", "required": false, "description": "日期（小于）", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "排序，如 date.desc", "schema": { "type": "string" }, "example": "date.desc" }, { "name": "limit", "in": "query", "required": false, "description": "每页条数，最大 50000。更多数据用响应里的 next_url 翻页", "schema": { "type": "integer", "minimum": 1, "maximum": 50000 }, "example": 1 } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "request_id": { "type": "string" }, "count": { "type": "integer" }, "next_url": { "type": "string", "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ShortVolume" } } }, "required": [ "results" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-plan": "advanced" } }, "/stocks/vX/float": { "get": { "operationId": "getFloat", "tags": [ "逐笔与基本面" ], "summary": "流通股", "description": "**Advanced 套餐专属**，Starter 套餐调用返回 404。流通股数量及流通比例。", "parameters": [ { "name": "ticker", "in": "query", "required": false, "description": "股票代码", "schema": { "type": "string" }, "example": "AAPL" } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "request_id": { "type": "string" }, "count": { "type": "integer" }, "next_url": { "type": "string", "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Float" } } }, "required": [ "results" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-plan": "advanced" } }, "/v3/reference/options/contracts": { "get": { "operationId": "listOptionContracts", "tags": [ "期权" ], "summary": "期权合约列表", "description": "**需要开通期权套餐**。按标的、到期日、看涨/看跌、行权价查合约。查已到期的合约必须加 expired=true。", "parameters": [ { "name": "underlying_ticker", "in": "query", "required": false, "description": "标的代码", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "contract_type", "in": "query", "required": false, "description": "看涨或看跌", "schema": { "type": "string", "enum": [ "call", "put" ] }, "example": "call" }, { "name": "expiration_date", "in": "query", "required": false, "description": "到期日", "schema": { "type": "string" } }, { "name": "expiration_date.gte", "in": "query", "required": false, "description": "到期日（大于等于）", "schema": { "type": "string" }, "example": "2027-12-01" }, { "name": "expiration_date.lte", "in": "query", "required": false, "description": "到期日（小于等于）", "schema": { "type": "string" }, "example": "2027-12-31" }, { "name": "expiration_date.gt", "in": "query", "required": false, "description": "到期日（大于）", "schema": { "type": "string" } }, { "name": "expiration_date.lt", "in": "query", "required": false, "description": "到期日（小于）", "schema": { "type": "string" } }, { "name": "strike_price", "in": "query", "required": false, "description": "行权价", "schema": { "type": "number" } }, { "name": "strike_price.gte", "in": "query", "required": false, "description": "行权价（大于等于）", "schema": { "type": "number" }, "example": 290 }, { "name": "strike_price.lte", "in": "query", "required": false, "description": "行权价（小于等于）", "schema": { "type": "number" }, "example": 310 }, { "name": "strike_price.gt", "in": "query", "required": false, "description": "行权价（大于）", "schema": { "type": "number" } }, { "name": "strike_price.lt", "in": "query", "required": false, "description": "行权价（小于）", "schema": { "type": "number" } }, { "name": "expired", "in": "query", "required": false, "description": "是否查已到期的合约，默认 false", "schema": { "type": "boolean" } }, { "name": "as_of", "in": "query", "required": false, "description": "查某一天当时挂牌的合约（YYYY-MM-DD）", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "排序字段", "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "description": "排序方向", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "limit", "in": "query", "required": false, "description": "每页条数，最大 1000。更多数据用响应里的 next_url 翻页", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 }, "example": 100 } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "request_id": { "type": "string" }, "count": { "type": "integer" }, "next_url": { "type": "string", "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/OptionContract" } } }, "required": [ "results" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-plan": "options" } }, "/v3/reference/options/contracts/{options_ticker}": { "get": { "operationId": "getOptionContract", "tags": [ "期权" ], "summary": "期权合约详情", "description": "**需要开通期权套餐**。单个合约的标的、到期日、行权价、行权方式、合约乘数。", "parameters": [ { "name": "options_ticker", "in": "path", "required": true, "description": "期权代码，格式见 https://marilux.dev/learn/option-symbol", "schema": { "type": "string" }, "example": "O:AAPL271217C00300000" }, { "name": "as_of", "in": "query", "required": false, "description": "查某一天的合约信息", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "results": { "$ref": "#/components/schemas/OptionContract" } }, "required": [ "results" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-plan": "options" } }, "/v3/snapshot/options/{underlying}": { "get": { "operationId": "getOptionChain", "tags": [ "期权" ], "summary": "期权链快照", "description": "**需要开通期权套餐**。标的所有合约的最新报价、成交、当日K线、希腊值、隐含波动率和未平仓量。深度实值或长期无成交的合约没有 greeks 和 implied_volatility 字段。", "parameters": [ { "name": "underlying", "in": "path", "required": true, "description": "标的股票代码", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "contract_type", "in": "query", "required": false, "description": "看涨或看跌", "schema": { "type": "string", "enum": [ "call", "put" ] }, "example": "call" }, { "name": "expiration_date", "in": "query", "required": false, "description": "到期日", "schema": { "type": "string" } }, { "name": "expiration_date.gte", "in": "query", "required": false, "description": "到期日（大于等于）", "schema": { "type": "string" }, "example": "2027-12-01" }, { "name": "expiration_date.lte", "in": "query", "required": false, "description": "到期日（小于等于）", "schema": { "type": "string" }, "example": "2027-12-31" }, { "name": "expiration_date.gt", "in": "query", "required": false, "description": "到期日（大于）", "schema": { "type": "string" } }, { "name": "expiration_date.lt", "in": "query", "required": false, "description": "到期日（小于）", "schema": { "type": "string" } }, { "name": "strike_price", "in": "query", "required": false, "description": "行权价", "schema": { "type": "number" } }, { "name": "strike_price.gte", "in": "query", "required": false, "description": "行权价（大于等于）", "schema": { "type": "number" }, "example": 290 }, { "name": "strike_price.lte", "in": "query", "required": false, "description": "行权价（小于等于）", "schema": { "type": "number" }, "example": 310 }, { "name": "strike_price.gt", "in": "query", "required": false, "description": "行权价（大于）", "schema": { "type": "number" } }, { "name": "strike_price.lt", "in": "query", "required": false, "description": "行权价（小于）", "schema": { "type": "number" } }, { "name": "sort", "in": "query", "required": false, "description": "排序字段", "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "description": "排序方向", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "limit", "in": "query", "required": false, "description": "每页条数，最大 250。更多数据用响应里的 next_url 翻页", "schema": { "type": "integer", "minimum": 1, "maximum": 250 }, "example": 50 } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "request_id": { "type": "string" }, "count": { "type": "integer" }, "next_url": { "type": "string", "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/OptionSnapshot" } } }, "required": [ "results" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-plan": "options" } }, "/v3/snapshot/options/{underlying}/{options_ticker}": { "get": { "operationId": "getOptionSnapshot", "tags": [ "期权" ], "summary": "单个期权合约快照", "description": "**需要开通期权套餐**。返回结构和期权链快照里的单个元素相同。", "parameters": [ { "name": "underlying", "in": "path", "required": true, "description": "标的股票代码", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "options_ticker", "in": "path", "required": true, "description": "期权代码，格式见 https://marilux.dev/learn/option-symbol", "schema": { "type": "string" }, "example": "O:AAPL271217C00300000" } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "results": { "$ref": "#/components/schemas/OptionSnapshot" } }, "required": [ "results" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-plan": "options" } }, "/v1/flatfiles/us_stocks_sip/{dataset}/{yyyy}/{mm}/{file}": { "get": { "operationId": "downloadFlatFile", "tags": [ "Flat Files" ], "summary": "全市场K线文件下载", "description": "按交易日打包的全市场日K（day_aggs_v1）或分钟K（minute_aggs_v1），gzip 压缩的 CSV。列：ticker,volume,open,close,high,low,window_start,transactions，window_start 为纳秒时间戳。按每日下载文件数计额度，不占用 REST 调用额度；体验套餐不含。", "parameters": [ { "name": "dataset", "in": "path", "required": true, "description": "日K或分钟K", "schema": { "type": "string", "enum": [ "day_aggs_v1", "minute_aggs_v1" ] }, "example": "day_aggs_v1" }, { "name": "yyyy", "in": "path", "required": true, "description": "年", "schema": { "type": "string" }, "example": "2024" }, { "name": "mm", "in": "path", "required": true, "description": "月（两位）", "schema": { "type": "string" }, "example": "01" }, { "name": "file", "in": "path", "required": true, "description": "文件名：交易日.csv.gz", "schema": { "type": "string" }, "example": "2024-01-02.csv.gz" } ], "responses": { "200": { "description": "gzip 压缩的 CSV 文件", "content": { "application/gzip": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInPlan" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "请求头 Authorization: Bearer （推荐）" }, "apiKeyQuery": { "type": "apiKey", "in": "query", "name": "apiKey", "description": "兼容方式：查询参数 apiKey=" } }, "schemas": { "Error": { "type": "object", "properties": { "status": { "type": "string", "example": "ERROR" }, "error": { "type": "string", "example": "今日调用量已达上限 50000 次，次日 UTC 00:00 重置，或升级套餐" } }, "required": [ "error" ] }, "Bar": { "type": "object", "properties": { "T": { "type": "string", "description": "代码（全市场日线、上一交易日接口才有）" }, "t": { "type": "integer", "description": "K线起始时间，毫秒时间戳；日K为美东时间 0 点" }, "o": { "type": "number" }, "h": { "type": "number" }, "l": { "type": "number" }, "c": { "type": "number" }, "v": { "type": "number", "description": "成交量" }, "vw": { "type": "number", "description": "成交量加权均价" }, "n": { "type": "integer", "description": "成交笔数" } }, "required": [ "t", "o", "h", "l", "c", "v" ] }, "AggsResponse": { "type": "object", "properties": { "ticker": { "type": "string" }, "adjusted": { "type": "boolean" }, "queryCount": { "type": "integer" }, "resultsCount": { "type": "integer" }, "status": { "type": "string" }, "request_id": { "type": "string" }, "count": { "type": "integer" }, "next_url": { "type": "string", "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Bar" } } }, "required": [ "status" ] }, "GroupedResponse": { "type": "object", "properties": { "adjusted": { "type": "boolean" }, "queryCount": { "type": "integer" }, "resultsCount": { "type": "integer" }, "status": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Bar" } } }, "required": [ "status" ] }, "OpenClose": { "type": "object", "properties": { "status": { "type": "string" }, "from": { "type": "string", "format": "date" }, "symbol": { "type": "string" }, "open": { "type": "number" }, "high": { "type": "number" }, "low": { "type": "number" }, "close": { "type": "number" }, "volume": { "type": "number" }, "afterHours": { "type": "number" }, "preMarket": { "type": "number" } }, "required": [ "symbol", "open", "close" ] }, "Ticker": { "type": "object", "properties": { "ticker": { "type": "string" }, "name": { "type": "string" }, "market": { "type": "string" }, "locale": { "type": "string" }, "primary_exchange": { "type": "string" }, "type": { "type": "string" }, "active": { "type": "boolean" }, "currency_name": { "type": "string" }, "cik": { "type": "string" }, "composite_figi": { "type": "string" }, "share_class_figi": { "type": "string" }, "last_updated_utc": { "type": "string" } }, "required": [ "ticker" ] }, "TickerDetails": { "type": "object", "properties": { "ticker": { "type": "string" }, "ticker_root": { "type": "string" }, "name": { "type": "string" }, "market": { "type": "string" }, "locale": { "type": "string" }, "primary_exchange": { "type": "string" }, "type": { "type": "string" }, "active": { "type": "boolean" }, "currency_name": { "type": "string" }, "cik": { "type": "string" }, "composite_figi": { "type": "string" }, "share_class_figi": { "type": "string" }, "market_cap": { "type": "number" }, "phone_number": { "type": "string" }, "description": { "type": "string" }, "sic_code": { "type": "string" }, "sic_description": { "type": "string" }, "homepage_url": { "type": "string" }, "total_employees": { "type": "integer" }, "list_date": { "type": "string" }, "share_class_shares_outstanding": { "type": "number" }, "weighted_shares_outstanding": { "type": "number" }, "round_lot": { "type": "integer" }, "branding": { "type": "object", "properties": { "logo_url": { "type": "string" }, "icon_url": { "type": "string" } } }, "address": { "type": "object", "properties": { "address1": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" } } } }, "required": [ "ticker" ] }, "Split": { "type": "object", "properties": { "ticker": { "type": "string" }, "execution_date": { "type": "string" }, "split_from": { "type": "number" }, "split_to": { "type": "number" }, "id": { "type": "string" } }, "required": [ "ticker", "execution_date" ] }, "Dividend": { "type": "object", "properties": { "ticker": { "type": "string" }, "ex_dividend_date": { "type": "string" }, "record_date": { "type": "string" }, "pay_date": { "type": "string" }, "declaration_date": { "type": "string" }, "cash_amount": { "type": "number" }, "currency": { "type": "string" }, "frequency": { "type": "integer" }, "dividend_type": { "type": "string" }, "id": { "type": "string" } }, "required": [ "ticker", "ex_dividend_date" ] }, "SplitV1": { "type": "object", "properties": { "ticker": { "type": "string" }, "execution_date": { "type": "string" }, "split_from": { "type": "number" }, "split_to": { "type": "number" }, "adjustment_type": { "type": "string", "description": "如 forward_split（正拆）、reverse_split（反拆）" }, "historical_adjustment_factor": { "type": "number", "description": "历史复权因子，可直接乘到历史价格上" } }, "required": [ "ticker", "execution_date" ] }, "DividendV1": { "type": "object", "properties": { "ticker": { "type": "string" }, "ex_dividend_date": { "type": "string" }, "record_date": { "type": "string" }, "pay_date": { "type": "string" }, "declaration_date": { "type": "string" }, "cash_amount": { "type": "number" }, "currency": { "type": "string" }, "frequency": { "type": "integer" }, "distribution_type": { "type": "string" }, "historical_adjustment_factor": { "type": "number", "description": "分红复权因子" }, "split_adjusted_cash_amount": { "type": "number", "description": "按拆股调整后的每股分红" } }, "required": [ "ticker", "ex_dividend_date" ] }, "TickerEvents": { "type": "object", "properties": { "status": { "type": "string" }, "results": { "type": "object", "properties": { "name": { "type": "string" }, "composite_figi": { "type": "string" }, "cik": { "type": "string" }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "date": { "type": "string" }, "ticker_change": { "type": "object", "properties": { "ticker": { "type": "string" } } } } } } } } }, "required": [ "results" ] }, "Ipo": { "type": "object", "properties": { "ticker": { "type": "string" }, "issuer_name": { "type": "string" }, "ipo_status": { "type": "string" }, "announced_date": { "type": "string" }, "primary_exchange": { "type": "string" }, "security_type": { "type": "string" }, "security_description": { "type": "string" }, "currency_code": { "type": "string" }, "lot_size": { "type": "integer" }, "isin": { "type": "string" }, "us_code": { "type": "string", "description": "CUSIP" }, "shares_outstanding": { "type": "number" }, "max_shares_offered": { "type": "number" }, "lowest_offer_price": { "type": "number" }, "highest_offer_price": { "type": "number" }, "final_issue_price": { "type": "number" }, "total_offer_size": { "type": "number" }, "last_updated": { "type": "string" } }, "required": [ "ticker", "ipo_status" ] }, "Exchange": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "asset_class": { "type": "string" }, "locale": { "type": "string" }, "name": { "type": "string" }, "acronym": { "type": "string" }, "mic": { "type": "string" }, "operating_mic": { "type": "string" }, "participant_id": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "name" ] }, "MarketStatus": { "type": "object", "properties": { "market": { "type": "string", "description": "open / closed / extended-hours" }, "serverTime": { "type": "string" }, "earlyHours": { "type": "boolean" }, "afterHours": { "type": "boolean" }, "exchanges": { "type": "object", "properties": { "nasdaq": { "type": "string" }, "nyse": { "type": "string" }, "otc": { "type": "string" } } }, "currencies": { "type": "object", "properties": { "fx": { "type": "string" }, "crypto": { "type": "string" } } } }, "required": [ "market" ] }, "MarketHoliday": { "type": "object", "properties": { "exchange": { "type": "string" }, "name": { "type": "string" }, "date": { "type": "string" }, "status": { "type": "string" }, "open": { "type": "string" }, "close": { "type": "string" } }, "required": [ "exchange", "date", "status" ] }, "StockSnapshot": { "type": "object", "properties": { "ticker": { "type": "string" }, "todaysChange": { "type": "number" }, "todaysChangePerc": { "type": "number" }, "updated": { "type": "integer" }, "day": { "type": "object", "properties": { "o": { "type": "number" }, "h": { "type": "number" }, "l": { "type": "number" }, "c": { "type": "number" }, "v": { "type": "number" }, "vw": { "type": "number" } } }, "min": { "type": "object", "properties": { "t": { "type": "integer" }, "o": { "type": "number" }, "h": { "type": "number" }, "l": { "type": "number" }, "c": { "type": "number" }, "v": { "type": "number" }, "vw": { "type": "number" }, "n": { "type": "integer" }, "av": { "type": "number" } } }, "prevDay": { "type": "object", "properties": { "o": { "type": "number" }, "h": { "type": "number" }, "l": { "type": "number" }, "c": { "type": "number" }, "v": { "type": "number" }, "vw": { "type": "number" } } }, "lastTrade": { "type": "object", "properties": { "p": { "type": "number" }, "s": { "type": "number" }, "t": { "type": "integer" }, "x": { "type": "integer" }, "c": { "type": "array", "items": { "type": "integer" } }, "i": { "type": "string" } } }, "lastQuote": { "type": "object", "properties": { "P": { "type": "number" }, "S": { "type": "number" }, "p": { "type": "number" }, "s": { "type": "number" }, "t": { "type": "integer" } } } }, "required": [ "ticker" ] }, "Trade": { "type": "object", "properties": { "price": { "type": "number" }, "size": { "type": "number" }, "exchange": { "type": "integer" }, "conditions": { "type": "array", "items": { "type": "integer" } }, "id": { "type": "string" }, "sip_timestamp": { "type": "integer", "description": "纳秒时间戳" }, "participant_timestamp": { "type": "integer" }, "sequence_number": { "type": "integer" }, "tape": { "type": "integer" } }, "required": [ "price", "size", "sip_timestamp" ] }, "Quote": { "type": "object", "properties": { "bid_price": { "type": "number" }, "bid_size": { "type": "number" }, "bid_exchange": { "type": "integer" }, "ask_price": { "type": "number" }, "ask_size": { "type": "number" }, "ask_exchange": { "type": "integer" }, "sip_timestamp": { "type": "integer", "description": "纳秒时间戳" }, "participant_timestamp": { "type": "integer" }, "sequence_number": { "type": "integer" }, "conditions": { "type": "array", "items": { "type": "integer" } }, "indicators": { "type": "array", "items": { "type": "integer" } }, "tape": { "type": "integer" } }, "required": [ "sip_timestamp" ] }, "Ratios": { "type": "object", "properties": { "ticker": { "type": "string" }, "cik": { "type": "string" }, "date": { "type": "string" }, "price": { "type": "number" }, "average_volume": { "type": "number" }, "market_cap": { "type": "number" }, "enterprise_value": { "type": "number" }, "earnings_per_share": { "type": "number" }, "price_to_earnings": { "type": "number" }, "price_to_book": { "type": "number" }, "price_to_sales": { "type": "number" }, "price_to_cash_flow": { "type": "number" }, "price_to_free_cash_flow": { "type": "number" }, "ev_to_sales": { "type": "number" }, "ev_to_ebitda": { "type": "number" }, "dividend_yield": { "type": "number" }, "return_on_equity": { "type": "number" }, "return_on_assets": { "type": "number" }, "debt_to_equity": { "type": "number" }, "current": { "type": "number", "description": "流动比率" }, "quick": { "type": "number", "description": "速动比率" }, "cash": { "type": "number" }, "free_cash_flow": { "type": "number" } }, "required": [ "ticker" ] }, "IncomeStatement": { "type": "object", "properties": { "tickers": { "type": "array", "items": { "type": "string" } }, "cik": { "type": "string" }, "period_end": { "type": "string" }, "filing_date": { "type": "string" }, "fiscal_year": { "type": "integer" }, "fiscal_quarter": { "type": "integer" }, "timeframe": { "type": "string" }, "revenue": { "type": "number" }, "cost_of_revenue": { "type": "number" }, "gross_profit": { "type": "number" }, "research_development": { "type": "number" }, "selling_general_administrative": { "type": "number" }, "total_operating_expenses": { "type": "number" }, "operating_income": { "type": "number" }, "income_before_income_taxes": { "type": "number" }, "income_taxes": { "type": "number" }, "consolidated_net_income_loss": { "type": "number" }, "net_income_loss_attributable_common_shareholders": { "type": "number" }, "basic_earnings_per_share": { "type": "number" }, "diluted_earnings_per_share": { "type": "number" }, "basic_shares_outstanding": { "type": "number" }, "diluted_shares_outstanding": { "type": "number" }, "ebitda": { "type": "number" } }, "required": [ "tickers", "period_end" ] }, "BalanceSheet": { "type": "object", "properties": { "tickers": { "type": "array", "items": { "type": "string" } }, "cik": { "type": "string" }, "period_end": { "type": "string" }, "filing_date": { "type": "string" }, "fiscal_year": { "type": "integer" }, "fiscal_quarter": { "type": "integer" }, "timeframe": { "type": "string" }, "cash_and_equivalents": { "type": "number" }, "short_term_investments": { "type": "number" }, "receivables": { "type": "number" }, "inventories": { "type": "number" }, "total_current_assets": { "type": "number" }, "property_plant_equipment_net": { "type": "number" }, "goodwill": { "type": "number" }, "intangible_assets_net": { "type": "number" }, "total_assets": { "type": "number" }, "accounts_payable": { "type": "number" }, "total_current_liabilities": { "type": "number" }, "total_liabilities": { "type": "number" }, "retained_earnings_deficit": { "type": "number" }, "total_equity": { "type": "number" }, "total_liabilities_and_equity": { "type": "number" } }, "required": [ "tickers", "period_end" ] }, "CashFlowStatement": { "type": "object", "properties": { "tickers": { "type": "array", "items": { "type": "string" } }, "cik": { "type": "string" }, "period_end": { "type": "string" }, "filing_date": { "type": "string" }, "fiscal_year": { "type": "integer" }, "fiscal_quarter": { "type": "integer" }, "timeframe": { "type": "string" }, "net_income": { "type": "number" }, "depreciation_depletion_and_amortization": { "type": "number" }, "net_cash_from_operating_activities": { "type": "number" }, "purchase_of_property_plant_and_equipment": { "type": "number" }, "net_cash_from_investing_activities": { "type": "number" }, "dividends": { "type": "number" }, "net_cash_from_financing_activities": { "type": "number" }, "change_in_cash_and_equivalents": { "type": "number" } }, "required": [ "tickers", "period_end" ] }, "ShortInterest": { "type": "object", "properties": { "ticker": { "type": "string" }, "settlement_date": { "type": "string" }, "short_interest": { "type": "number" }, "avg_daily_volume": { "type": "number" }, "days_to_cover": { "type": "number" } }, "required": [ "ticker", "settlement_date" ] }, "ShortVolume": { "type": "object", "properties": { "ticker": { "type": "string" }, "date": { "type": "string" }, "total_volume": { "type": "number" }, "short_volume": { "type": "number" }, "exempt_volume": { "type": "number" }, "non_exempt_volume": { "type": "number" }, "short_volume_ratio": { "type": "number", "description": "卖空占比（百分数，如 58.33 表示 58.33%）" } }, "required": [ "ticker", "date" ] }, "Float": { "type": "object", "properties": { "ticker": { "type": "string" }, "free_float": { "type": "number" }, "free_float_percent": { "type": "number" }, "effective_date": { "type": "string" } }, "required": [ "ticker" ] }, "OptionContract": { "type": "object", "properties": { "ticker": { "type": "string", "description": "期权代码，如 O:AAPL271217C00300000" }, "underlying_ticker": { "type": "string" }, "contract_type": { "type": "string", "enum": [ "call", "put", "other" ] }, "expiration_date": { "type": "string" }, "strike_price": { "type": "number" }, "exercise_style": { "type": "string" }, "shares_per_contract": { "type": "number" }, "primary_exchange": { "type": "string" }, "cfi": { "type": "string" } }, "required": [ "ticker", "underlying_ticker", "contract_type", "expiration_date", "strike_price" ] }, "OptionSnapshot": { "type": "object", "properties": { "break_even_price": { "type": "number" }, "implied_volatility": { "type": "number", "description": "隐含波动率，0.373 表示 37.3%；深度实值或无成交的合约可能没有" }, "open_interest": { "type": "number", "description": "未平仓量（合约数）" }, "details": { "type": "object", "properties": { "ticker": { "type": "string" }, "contract_type": { "type": "string" }, "exercise_style": { "type": "string" }, "expiration_date": { "type": "string" }, "shares_per_contract": { "type": "number" }, "strike_price": { "type": "number" } }, "required": [ "ticker", "contract_type", "expiration_date", "strike_price" ] }, "greeks": { "type": "object", "properties": { "delta": { "type": "number" }, "gamma": { "type": "number" }, "theta": { "type": "number", "description": "每天的时间价值变化" }, "vega": { "type": "number", "description": "隐含波动率每变动 1 个百分点的价格变化" } } }, "day": { "type": "object", "properties": { "open": { "type": "number" }, "high": { "type": "number" }, "low": { "type": "number" }, "close": { "type": "number" }, "volume": { "type": "number" }, "vwap": { "type": "number" }, "change": { "type": "number" }, "change_percent": { "type": "number" }, "previous_close": { "type": "number" }, "last_updated": { "type": "integer" } } }, "last_quote": { "type": "object", "properties": { "bid": { "type": "number" }, "ask": { "type": "number" }, "bid_size": { "type": "number" }, "ask_size": { "type": "number" }, "midpoint": { "type": "number" }, "last_updated": { "type": "integer" }, "timeframe": { "type": "string" } } }, "last_trade": { "type": "object", "properties": { "price": { "type": "number" }, "size": { "type": "number" }, "exchange": { "type": "integer" }, "conditions": { "type": "array", "items": { "type": "integer" } }, "sip_timestamp": { "type": "integer" }, "timeframe": { "type": "string" } } }, "underlying_asset": { "type": "object", "properties": { "ticker": { "type": "string" }, "price": { "type": "number" }, "change_to_break_even": { "type": "number" }, "last_updated": { "type": "integer" }, "timeframe": { "type": "string" } } } }, "required": [ "details" ] } }, "responses": { "Unauthorized": { "description": "API Key 缺失或无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Key 已停用或到期、未开通对应产品（如没买期权套餐请求期权数据）、或超出套餐历史范围", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotInPlan": { "description": "接口不在当前套餐范围内（如 Starter 调用 Advanced 专属接口）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooManyRequests": { "description": "超出速率、并发、每日调用、月流量或 Flat Files 下载额度。按 Retry-After 响应头等待后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }