{
  "openapi": "3.1.0",
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "info": {
    "title": "Orange HiTick Public Data API",
    "version": "1.0.0",
    "description": "Orange HiTick 为开发者与 AI Agent 提供行情、期权分析与数据检索服务。本描述仅覆盖已公开文档化的数据 HTTP API。\n\n所有请求需携带 X-API-Token。目录接口不计费，其余接口按对应能力计费；不要把计费查询当作免费健康检查。必须检查响应 code，不能仅凭 HTTP 200 判断成功。错误响应及其他可空字段可能因序列化配置而省略。\n\n行情与波动率的 data、因子的 details 为动态 JSON；具体业务字段和使用规则以链接文档为准。"
  },
  "servers": [
    {
      "url": "https://api.hitick.top",
      "description": "Orange HiTick 数据 API"
    }
  ],
  "security": [
    {
      "ApiToken": []
    }
  ],
  "externalDocs": {
    "description": "Orange HiTick 开发者与 Agent 接入文档",
    "url": "https://open.hitick.top/doc/"
  },
  "tags": [
    {
      "name": "基础数据",
      "externalDocs": {
        "description": "基础数据 API / Skill 文档",
        "url": "https://open.hitick.top/doc/api/basic-data-skill/"
      }
    },
    {
      "name": "波动率",
      "externalDocs": {
        "description": "波动率 API / Skill 文档",
        "url": "https://open.hitick.top/doc/api/vol-data-skill/"
      }
    },
    {
      "name": "席位分析",
      "externalDocs": {
        "description": "席位分析 API / Skill 文档",
        "url": "https://open.hitick.top/doc/api/seat-analysis-skill/"
      }
    },
    {
      "name": "主观信号",
      "externalDocs": {
        "description": "主观信号 API / Skill 文档",
        "url": "https://open.hitick.top/doc/api/subjective-signal-skill/"
      }
    },
    {
      "name": "Polymarket Up/Down",
      "externalDocs": {
        "description": "Polymarket Up/Down API / Skill 文档",
        "url": "https://open.hitick.top/doc/api/polymarket-up-down-skill/"
      }
    },
    {
      "name": "Trump Statements",
      "externalDocs": {
        "description": "Trump Statements API / Skill 文档",
        "url": "https://open.hitick.top/doc/api/trump-statements-skill/"
      }
    }
  ],
  "paths": {
    "/api/v1/basic-data/catalog": {
      "get": {
        "tags": [
          "基础数据"
        ],
        "operationId": "getBasicCatalog",
        "summary": "获取可查询标的目录",
        "description": "返回当前可查询标的及到期日、乘数信息。\n\n此目录查询不计费。",
        "responses": {
          "200": {
            "description": "检查 code：0 表示成功；业务错误也可能返回 HTTP 200，code 非零，data 为空或省略。",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/JsonResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ApiError"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "系统异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-billing": {
          "billable": false
        }
      }
    },
    "/api/v1/basic-data/query/by-underlying": {
      "get": {
        "tags": [
          "基础数据"
        ],
        "operationId": "getBasicByUnderlying",
        "summary": "按标的查询基础行情",
        "description": "返回标的及该标的全部到期日、乘数下的期权行情。\n\n业务查询完成后同步计费，扣费失败则返回业务错误；成功的空结果仍可能计费。",
        "responses": {
          "200": {
            "description": "检查 code：0 表示成功；业务错误也可能返回 HTTP 200，code 非零，data 为空或省略。",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/JsonResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ApiError"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "系统异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-billing": {
          "billable": true
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Underlying"
          }
        ]
      }
    },
    "/api/v1/basic-data/query/by-expire": {
      "get": {
        "tags": [
          "基础数据"
        ],
        "operationId": "getBasicByExpire",
        "summary": "按到期日查询基础行情",
        "description": "返回标的及指定到期日下的期权行情。\n\n业务查询完成后同步计费，扣费失败则返回业务错误；成功的空结果仍可能计费。",
        "responses": {
          "200": {
            "description": "检查 code：0 表示成功；业务错误也可能返回 HTTP 200，code 非零，data 为空或省略。",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/JsonResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ApiError"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "系统异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-billing": {
          "billable": true
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Underlying"
          },
          {
            "$ref": "#/components/parameters/RequiredExpire"
          }
        ]
      }
    },
    "/api/v1/basic-data/query/by-symbol": {
      "get": {
        "tags": [
          "基础数据"
        ],
        "operationId": "getBasicBySymbol",
        "summary": "按合约代码查询基础行情",
        "description": "查询一个期权合约或标的代码。\n\n业务查询完成后同步计费，扣费失败则返回业务错误；成功的空结果仍可能计费。",
        "responses": {
          "200": {
            "description": "检查 code：0 表示成功；业务错误也可能返回 HTTP 200，code 非零，data 为空或省略。",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/JsonResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ApiError"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "系统异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-billing": {
          "billable": true
        },
        "parameters": [
          {
            "name": "symbol",
            "in": "query",
            "required": true,
            "description": "期权合约或标的代码。",
            "schema": {
              "type": "string",
              "minLength": 1,
              "example": "cu2607C78000"
            }
          }
        ]
      }
    },
    "/api/v1/vol-data/groups": {
      "get": {
        "tags": [
          "波动率"
        ],
        "operationId": "getVolGroups",
        "summary": "获取波动率分组目录",
        "description": "返回可查询的 underlying、expire_date、multiplier 组合。\n\n此目录查询不计费。",
        "responses": {
          "200": {
            "description": "检查 code：0 表示成功；业务错误也可能返回 HTTP 200，code 非零，data 为空或省略。",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/JsonResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ApiError"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "系统异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-billing": {
          "billable": false
        }
      }
    },
    "/api/v1/vol-data/query/by-underlying": {
      "get": {
        "tags": [
          "波动率"
        ],
        "operationId": "getVolQueryByUnderlying",
        "summary": "按标的查询实时 T 型报价、隐含波动率与 Greeks",
        "description": "按标的选择分组；expire 和 multiplier 可选，建议在已知时显式传入。\n\n业务查询完成后同步计费，扣费失败则返回业务错误；成功的空结果仍可能计费。",
        "responses": {
          "200": {
            "description": "检查 code：0 表示成功；业务错误也可能返回 HTTP 200，code 非零，data 为空或省略。",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/JsonResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ApiError"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "系统异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-billing": {
          "billable": true
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Underlying"
          },
          {
            "$ref": "#/components/parameters/Expire"
          },
          {
            "$ref": "#/components/parameters/Multiplier"
          }
        ]
      }
    },
    "/api/v1/vol-data/query/by-expire": {
      "get": {
        "tags": [
          "波动率"
        ],
        "operationId": "getVolQueryByExpire",
        "summary": "按到期日查询实时 T 型报价、隐含波动率与 Greeks",
        "description": "按标的选择分组；expire 和 multiplier 可选，建议在已知时显式传入。\n\n业务查询完成后同步计费，扣费失败则返回业务错误；成功的空结果仍可能计费。",
        "responses": {
          "200": {
            "description": "检查 code：0 表示成功；业务错误也可能返回 HTTP 200，code 非零，data 为空或省略。",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/JsonResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ApiError"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "系统异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-billing": {
          "billable": true
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Underlying"
          },
          {
            "$ref": "#/components/parameters/Expire"
          },
          {
            "$ref": "#/components/parameters/Multiplier"
          }
        ]
      }
    },
    "/api/v1/vol-data/query/by-multiplier": {
      "get": {
        "tags": [
          "波动率"
        ],
        "operationId": "getVolQueryByMultiplier",
        "summary": "按乘数查询实时 T 型报价、隐含波动率与 Greeks",
        "description": "按标的选择分组；expire 和 multiplier 可选，建议在已知时显式传入。\n\n业务查询完成后同步计费，扣费失败则返回业务错误；成功的空结果仍可能计费。",
        "responses": {
          "200": {
            "description": "检查 code：0 表示成功；业务错误也可能返回 HTTP 200，code 非零，data 为空或省略。",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/JsonResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ApiError"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "系统异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-billing": {
          "billable": true
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Underlying"
          },
          {
            "$ref": "#/components/parameters/Expire"
          },
          {
            "$ref": "#/components/parameters/Multiplier"
          }
        ]
      }
    },
    "/api/v1/vol-data/ts/by-underlying": {
      "get": {
        "tags": [
          "波动率"
        ],
        "operationId": "getVolTsByUnderlying",
        "summary": "按标的查询ATM 隐含波动率、偏度与标的价格时序",
        "description": "按标的选择分组；expire 和 multiplier 可选，建议在已知时显式传入。 时间范围必须满足 0 <= end - start <= 86400000 毫秒。超限返回 code 1001，不自动截断且不扣费。\n\n业务查询完成后同步计费，扣费失败则返回业务错误；成功的空结果仍可能计费。",
        "responses": {
          "200": {
            "description": "检查 code：0 表示成功；业务错误也可能返回 HTTP 200，code 非零，data 为空或省略。",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/JsonResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ApiError"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "系统异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "时序数据暂时不可用（code 5030）。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-billing": {
          "billable": true
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Underlying"
          },
          {
            "$ref": "#/components/parameters/Expire"
          },
          {
            "$ref": "#/components/parameters/TimeSeriesMultiplier"
          },
          {
            "$ref": "#/components/parameters/Start"
          },
          {
            "$ref": "#/components/parameters/End"
          }
        ]
      }
    },
    "/api/v1/vol-data/ts/by-expire": {
      "get": {
        "tags": [
          "波动率"
        ],
        "operationId": "getVolTsByExpire",
        "summary": "按到期日查询ATM 隐含波动率、偏度与标的价格时序",
        "description": "按标的选择分组；expire 和 multiplier 可选，建议在已知时显式传入。 时间范围必须满足 0 <= end - start <= 86400000 毫秒。超限返回 code 1001，不自动截断且不扣费。\n\n业务查询完成后同步计费，扣费失败则返回业务错误；成功的空结果仍可能计费。",
        "responses": {
          "200": {
            "description": "检查 code：0 表示成功；业务错误也可能返回 HTTP 200，code 非零，data 为空或省略。",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/JsonResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ApiError"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "系统异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "时序数据暂时不可用（code 5030）。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-billing": {
          "billable": true
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Underlying"
          },
          {
            "$ref": "#/components/parameters/Expire"
          },
          {
            "$ref": "#/components/parameters/TimeSeriesMultiplier"
          },
          {
            "$ref": "#/components/parameters/Start"
          },
          {
            "$ref": "#/components/parameters/End"
          }
        ]
      }
    },
    "/api/v1/vol-data/ts/by-multiplier": {
      "get": {
        "tags": [
          "波动率"
        ],
        "operationId": "getVolTsByMultiplier",
        "summary": "按乘数查询ATM 隐含波动率、偏度与标的价格时序",
        "description": "按标的选择分组；expire 和 multiplier 可选，建议在已知时显式传入。 时间范围必须满足 0 <= end - start <= 86400000 毫秒。超限返回 code 1001，不自动截断且不扣费。\n\n业务查询完成后同步计费，扣费失败则返回业务错误；成功的空结果仍可能计费。",
        "responses": {
          "200": {
            "description": "检查 code：0 表示成功；业务错误也可能返回 HTTP 200，code 非零，data 为空或省略。",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/JsonResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ApiError"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "系统异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "时序数据暂时不可用（code 5030）。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-billing": {
          "billable": true
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Underlying"
          },
          {
            "$ref": "#/components/parameters/Expire"
          },
          {
            "$ref": "#/components/parameters/TimeSeriesMultiplier"
          },
          {
            "$ref": "#/components/parameters/Start"
          },
          {
            "$ref": "#/components/parameters/End"
          }
        ]
      }
    },
    "/api/v1/vol-data/gex/by-underlying": {
      "get": {
        "tags": [
          "波动率"
        ],
        "operationId": "getVolGexByUnderlying",
        "summary": "按标的查询Gamma Exposure 曲线",
        "description": "按标的选择分组；expire 和 multiplier 可选，建议在已知时显式传入。\n\n业务查询完成后同步计费，扣费失败则返回业务错误；成功的空结果仍可能计费。",
        "responses": {
          "200": {
            "description": "检查 code：0 表示成功；业务错误也可能返回 HTTP 200，code 非零，data 为空或省略。",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/JsonResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ApiError"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "系统异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-billing": {
          "billable": true
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Underlying"
          },
          {
            "$ref": "#/components/parameters/Expire"
          },
          {
            "$ref": "#/components/parameters/Multiplier"
          }
        ]
      }
    },
    "/api/v1/vol-data/gex/by-expire": {
      "get": {
        "tags": [
          "波动率"
        ],
        "operationId": "getVolGexByExpire",
        "summary": "按到期日查询Gamma Exposure 曲线",
        "description": "按标的选择分组；expire 和 multiplier 可选，建议在已知时显式传入。\n\n业务查询完成后同步计费，扣费失败则返回业务错误；成功的空结果仍可能计费。",
        "responses": {
          "200": {
            "description": "检查 code：0 表示成功；业务错误也可能返回 HTTP 200，code 非零，data 为空或省略。",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/JsonResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ApiError"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "系统异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-billing": {
          "billable": true
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Underlying"
          },
          {
            "$ref": "#/components/parameters/Expire"
          },
          {
            "$ref": "#/components/parameters/Multiplier"
          }
        ]
      }
    },
    "/api/v1/vol-data/gex/by-multiplier": {
      "get": {
        "tags": [
          "波动率"
        ],
        "operationId": "getVolGexByMultiplier",
        "summary": "按乘数查询Gamma Exposure 曲线",
        "description": "按标的选择分组；expire 和 multiplier 可选，建议在已知时显式传入。\n\n业务查询完成后同步计费，扣费失败则返回业务错误；成功的空结果仍可能计费。",
        "responses": {
          "200": {
            "description": "检查 code：0 表示成功；业务错误也可能返回 HTTP 200，code 非零，data 为空或省略。",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/JsonResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ApiError"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "系统异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-billing": {
          "billable": true
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Underlying"
          },
          {
            "$ref": "#/components/parameters/Expire"
          },
          {
            "$ref": "#/components/parameters/Multiplier"
          }
        ]
      }
    },
    "/api/v1/vol-data/snapshot/by-underlying": {
      "get": {
        "tags": [
          "波动率"
        ],
        "operationId": "getVolSnapshotByUnderlying",
        "summary": "查询历史 T 型报价小时快照",
        "description": "未指定 expire 时默认最近月；未指定 multiplier 时默认该月最小乘数。found=false 表示对应整点没有可用快照。\n\n业务查询完成后同步计费，扣费失败则返回业务错误；成功的空结果仍可能计费。",
        "responses": {
          "200": {
            "description": "检查 code：0 表示成功；业务错误也可能返回 HTTP 200，code 非零，data 为空或省略。",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/JsonResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ApiError"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "系统异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-billing": {
          "billable": true
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Underlying"
          },
          {
            "$ref": "#/components/parameters/Expire"
          },
          {
            "$ref": "#/components/parameters/Multiplier"
          },
          {
            "$ref": "#/components/parameters/SnapshotTime"
          }
        ]
      }
    },
    "/api/v1/vol-data/gex/snapshot/by-underlying": {
      "get": {
        "tags": [
          "波动率"
        ],
        "operationId": "getGexSnapshotByUnderlying",
        "summary": "查询历史 GEX 小时快照",
        "description": "未指定 expire 时默认最近月；未指定 multiplier 时默认该月最小乘数。found=false 表示对应整点没有可用快照。\n\n业务查询完成后同步计费，扣费失败则返回业务错误；成功的空结果仍可能计费。",
        "responses": {
          "200": {
            "description": "检查 code：0 表示成功；业务错误也可能返回 HTTP 200，code 非零，data 为空或省略。",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/JsonResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ApiError"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "系统异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-billing": {
          "billable": true
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Underlying"
          },
          {
            "$ref": "#/components/parameters/Expire"
          },
          {
            "$ref": "#/components/parameters/Multiplier"
          },
          {
            "$ref": "#/components/parameters/SnapshotTime"
          }
        ]
      }
    },
    "/api/v1/vol-data/gex-image/by-underlying": {
      "get": {
        "tags": [
          "波动率"
        ],
        "operationId": "getGexImageByUnderlying",
        "summary": "获取 GEX 结构图 URL",
        "description": "返回实时或历史 GEX 图的 URL 和生成时间。\n\n业务查询完成后同步计费，扣费失败则返回业务错误；成功的空结果仍可能计费。",
        "responses": {
          "200": {
            "description": "检查 code：0 表示成功；业务错误也可能返回 HTTP 200，code 非零，data 为空或省略。",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/GexImageResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ApiError"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "系统异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-billing": {
          "billable": true
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Underlying"
          },
          {
            "$ref": "#/components/parameters/Expire"
          },
          {
            "$ref": "#/components/parameters/Multiplier"
          },
          {
            "$ref": "#/components/parameters/OptionalSnapshotTime"
          }
        ]
      }
    },
    "/api/v1/seat-analysis/query": {
      "get": {
        "tags": [
          "席位分析"
        ],
        "operationId": "getSeatAnalysis",
        "summary": "查询期货席位四榜",
        "description": "查询每日入库后的净买、净卖、买方持仓、卖方持仓榜；无数据时榜单为空，notice 提供说明。\n\n业务查询完成后同步计费，扣费失败则返回业务错误；成功的空结果仍可能计费。",
        "responses": {
          "200": {
            "description": "检查 code：0 表示成功；业务错误也可能返回 HTTP 200，code 非零，data 为空或省略。",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/SeatResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ApiError"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "系统异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-billing": {
          "billable": true
        },
        "parameters": [
          {
            "name": "tradeDate",
            "in": "query",
            "required": true,
            "description": "交易日，支持 YYYY-MM-DD 或 YYYYMMDD。",
            "schema": {
              "type": "string",
              "pattern": "^(\\d{4}-\\d{2}-\\d{2}|\\d{8})$",
              "example": "2026-07-07"
            }
          },
          {
            "name": "symbol",
            "in": "query",
            "required": true,
            "description": "期货合约代码；自动识别交易所。",
            "schema": {
              "type": "string",
              "minLength": 1,
              "example": "m2609"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "每榜条数，默认 20；必须大于 0，超过 50 时按 50 处理。",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 20
            }
          }
        ]
      }
    },
    "/api/v1/subjective-signal/factors": {
      "get": {
        "tags": [
          "主观信号"
        ],
        "operationId": "listSubjectiveFactors",
        "summary": "获取当前已注册因子及参数",
        "description": "调用 evaluate 前读取当前 factorKey 与 requiredParams、optionalParams。\n\n此目录查询不计费。",
        "responses": {
          "200": {
            "description": "检查 code：0 表示成功；业务错误也可能返回 HTTP 200，code 非零，data 为空或省略。",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/FactorListResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ApiError"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "系统异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-billing": {
          "billable": false
        }
      }
    },
    "/api/v1/subjective-signal/evaluate": {
      "post": {
        "tags": [
          "主观信号"
        ],
        "operationId": "evaluateSubjectiveSignal",
        "summary": "执行主观信号计算",
        "description": "factorKey 决定可用参数、结果结构与计费项目；details 为因子专用 JSON。\n\n业务查询完成后同步计费，扣费失败则返回业务错误；成功的空结果仍可能计费。",
        "responses": {
          "200": {
            "description": "检查 code：0 表示成功；业务错误也可能返回 HTTP 200，code 非零，data 为空或省略。",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/SignalListResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ApiError"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "系统异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-billing": {
          "billable": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EvaluateRequest"
              }
            }
          }
        }
      }
    },
    "/api/v1/polymarket/up-down": {
      "get": {
        "tags": [
          "Polymarket Up/Down"
        ],
        "operationId": "getPolymarketUpDown",
        "summary": "查询 Polymarket Up/Down 最新快照",
        "description": "symbol 大小写不敏感；省略时返回全部当前快照并按 symbol 排序。未知标的返回 count=0。快照保存在服务进程内，重启后可能暂时为空。price 是开盘基准价，不是当前市价。\n\n业务查询完成后同步计费，扣费失败则返回业务错误；成功的空结果仍可能计费。",
        "responses": {
          "200": {
            "description": "检查 code：0 表示成功；业务错误也可能返回 HTTP 200，code 非零，data 为空或省略。",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/PolymarketResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ApiError"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "系统异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-billing": {
          "billable": true
        },
        "parameters": [
          {
            "name": "symbol",
            "in": "query",
            "required": false,
            "description": "可选标的代码，如 WTI 或 BTC。",
            "schema": {
              "type": "string",
              "example": "WTI"
            }
          }
        ]
      }
    },
    "/api/v1/trump/statements": {
      "get": {
        "tags": [
          "Trump Statements"
        ],
        "operationId": "getTrumpStatements",
        "summary": "查询特朗普公开言论与白宫正式内容",
        "description": "查询区间为 [startTime, endTime)，startTime 必须早于 endTime。默认最近 7 天，按 published_at 倒序、同时间按 ID 倒序。响应时间统一为 Asia/Shanghai；引用时保留来源类型、链接与发布时间。\n\n业务查询完成后同步计费，扣费失败则返回业务错误；成功的空结果仍可能计费。",
        "responses": {
          "200": {
            "description": "检查 code：0 表示成功；业务错误也可能返回 HTTP 200，code 非零，data 为空或省略。",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/TrumpResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ApiError"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "系统异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-billing": {
          "billable": true
        },
        "parameters": [
          {
            "name": "startTime",
            "in": "query",
            "required": false,
            "description": "带时区的 ISO-8601 时间；省略时为 endTime 减 7 天。URL 中的 + 应编码为 %2B。",
            "schema": {
              "type": "string",
              "format": "date-time",
              "example": "2026-08-01T00:00:00+08:00"
            }
          },
          {
            "name": "endTime",
            "in": "query",
            "required": false,
            "description": "带时区的 ISO-8601 时间；省略时为当前时间。",
            "schema": {
              "type": "string",
              "format": "date-time",
              "example": "2026-08-08T00:00:00+08:00"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "默认 10；必须大于 0，超过 100 时按 100 处理。",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 10
            }
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiToken": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Token",
        "description": "在 Orange HiTick 账户中创建 Token，并通过请求头传入。不要放入 URL。"
      }
    },
    "parameters": {
      "Underlying": {
        "name": "underlying",
        "in": "query",
        "required": true,
        "description": "标的代码，例如 au2607；先用目录或 MCP 标的解析确认可用代码。",
        "schema": {
          "type": "string",
          "minLength": 1
        }
      },
      "Expire": {
        "name": "expire",
        "in": "query",
        "required": false,
        "description": "到期日，yyyyMMdd；用于选择具体到期日。",
        "schema": {
          "type": "string",
          "pattern": "^\\d{8}$",
          "example": "20260624"
        }
      },
      "RequiredExpire": {
        "name": "expire",
        "in": "query",
        "required": true,
        "description": "到期日，yyyyMMdd。",
        "schema": {
          "type": "string",
          "pattern": "^\\d{8}$",
          "example": "20260624"
        }
      },
      "Multiplier": {
        "name": "multiplier",
        "in": "query",
        "required": false,
        "description": "合约乘数；建议按目录或分组中的值传入。",
        "schema": {
          "type": "string",
          "example": "1000"
        }
      },
      "TimeSeriesMultiplier": {
        "name": "multiplier",
        "in": "query",
        "required": false,
        "description": "合约乘数，必须为正整数。",
        "schema": {
          "type": "integer",
          "format": "int64",
          "minimum": 1,
          "example": 1000
        }
      },
      "SnapshotTime": {
        "name": "snapshotTime",
        "in": "query",
        "required": true,
        "description": "Unix 毫秒时间戳（向下取整到整点）或 last（当前分组最新落库快照）。",
        "schema": {
          "type": "string",
          "pattern": "^(last|-?\\d+)$",
          "example": "last"
        }
      },
      "OptionalSnapshotTime": {
        "name": "snapshotTime",
        "in": "query",
        "required": false,
        "description": "省略时生成实时 GEX 图；Unix 毫秒时间戳表示对应整点历史图；last 表示最新落库快照图。",
        "schema": {
          "type": "string",
          "pattern": "^(last|-?\\d+)$",
          "example": "last"
        }
      },
      "Start": {
        "name": "start",
        "in": "query",
        "required": true,
        "description": "正数为 Unix 毫秒时间戳；非正数为相对该分组最新有效数据时间的毫秒偏移。0 表示最新数据时间，并非服务器当前时间。解析后须满足 0 <= end - start <= 86400000。",
        "schema": {
          "type": "integer",
          "format": "int64",
          "example": -86400000
        }
      },
      "End": {
        "name": "end",
        "in": "query",
        "required": true,
        "description": "正数为 Unix 毫秒时间戳；非正数为相对该分组最新有效数据时间的毫秒偏移。0 表示最新数据时间，并非服务器当前时间。解析后须满足 0 <= end - start <= 86400000。",
        "schema": {
          "type": "integer",
          "format": "int64",
          "example": 0
        }
      }
    },
    "schemas": {
      "JsonData": {
        "description": "按接口返回的业务 JSON；行情、波动率与历史快照字段可随数据源或分组变化，详细语义见对应 API 文档。此 schema 不将示例字段当成固定完整契约。"
      },
      "ApiError": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "not": {
              "const": 0
            },
            "description": "非零业务错误码。"
          },
          "message": {
            "type": "string",
            "description": "可展示的错误说明。"
          },
          "data": {
            "type": "null",
            "description": "错误时为空；服务端可能省略空字段。"
          }
        },
        "required": [
          "code",
          "message"
        ]
      },
      "EvaluateRequest": {
        "type": "object",
        "properties": {
          "factorKey": {
            "type": "string",
            "minLength": 1,
            "example": "AtmVolDivergence",
            "description": "从 factors 获取当前已注册因子的 factorKey；不固定枚举以免因子更新后失效。"
          },
          "params": {
            "type": "object",
            "additionalProperties": true,
            "description": "因子专用参数；按 factors 返回的 requiredParams 和 optionalParams 及主观信号文档传入。省略时使用空对象。",
            "example": {
              "underlyings": [
                "au2607",
                "cu2607"
              ]
            }
          }
        },
        "required": [
          "factorKey"
        ]
      },
      "FactorParam": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        }
      },
      "FactorDescriptor": {
        "type": "object",
        "properties": {
          "factorKey": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "requiredParams": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FactorParam"
            }
          },
          "optionalParams": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FactorParam"
            }
          }
        }
      },
      "SignalResult": {
        "type": "object",
        "properties": {
          "factorKey": {
            "type": "string"
          },
          "signal": {
            "type": "string",
            "description": "由具体因子定义，不作为交易执行指令。"
          },
          "score": {
            "type": [
              "number",
              "null"
            ]
          },
          "summary": {
            "type": "string"
          },
          "details": {
            "description": "因子专用 JSON，结构取决于 factorKey。"
          },
          "generatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "信号生成时间，ISO-8601。"
          }
        }
      },
      "GexImage": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "可直接展示的 GEX 图地址。"
          },
          "generated_at": {
            "type": "integer",
            "format": "int64",
            "description": "生成时间，Unix 毫秒时间戳。"
          }
        },
        "required": [
          "url",
          "generated_at"
        ]
      },
      "SeatRankItem": {
        "type": "object",
        "properties": {
          "rankNo": {
            "type": "integer",
            "minimum": 1
          },
          "brokerName": {
            "type": "string"
          },
          "value": {
            "type": "number",
            "description": "当前榜单数值。"
          },
          "diff": {
            "type": [
              "number",
              "null"
            ],
            "description": "相对前一交易日变化；未知时省略或为空。"
          }
        },
        "required": [
          "rankNo",
          "value"
        ]
      },
      "SeatLists": {
        "type": "object",
        "properties": {
          "netBuy": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SeatRankItem"
            }
          },
          "netSell": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SeatRankItem"
            }
          },
          "longHolding": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SeatRankItem"
            }
          },
          "shortHolding": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SeatRankItem"
            }
          }
        },
        "required": [
          "netBuy",
          "netSell",
          "longHolding",
          "shortHolding"
        ]
      },
      "SeatData": {
        "type": "object",
        "properties": {
          "tradeDate": {
            "type": "string",
            "format": "date"
          },
          "symbol": {
            "type": "string"
          },
          "exchange": {
            "type": [
              "string",
              "null"
            ],
            "description": "自动识别的交易所；无数据时可能省略或为空。"
          },
          "notice": {
            "type": [
              "string",
              "null"
            ],
            "description": "可展示的无数据等提示；无提示时可能省略或为空。"
          },
          "lists": {
            "$ref": "#/components/schemas/SeatLists"
          }
        },
        "required": [
          "tradeDate",
          "symbol",
          "lists"
        ]
      },
      "PolymarketSnapshot": {
        "type": "object",
        "properties": {
          "queried_at": {
            "type": "string",
            "format": "date-time",
            "description": "采集时间，Asia/Shanghai，带 +08:00 偏移。"
          },
          "symbol": {
            "type": "string"
          },
          "price": {
            "type": "number",
            "description": "该场市场的 price_to_beat 开盘基准价，不是当前标的市价。"
          },
          "up_mid_price": {
            "type": "number",
            "description": "Up 合约 (best_bid + best_ask) / 2，不等于严格统计概率。"
          },
          "down_mid_price": {
            "type": "number",
            "description": "Down 合约 (best_bid + best_ask) / 2，不等于严格统计概率。"
          }
        },
        "required": [
          "queried_at",
          "symbol",
          "price",
          "up_mid_price",
          "down_mid_price"
        ]
      },
      "PolymarketData": {
        "type": "object",
        "properties": {
          "count": {
            "type": "integer",
            "minimum": 0
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PolymarketSnapshot"
            }
          }
        },
        "required": [
          "count",
          "items"
        ]
      },
      "TrumpStatement": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "subject_tag": {
            "type": "string"
          },
          "source_type": {
            "type": "string",
            "description": "目前包含 TRUTH_SOCIAL、WHITE_HOUSE_PRESIDENTIAL_ACTION、WHITE_HOUSE_NEWS；区分个人发言与白宫正式内容。"
          },
          "publisher": {
            "type": [
              "string",
              "null"
            ]
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "content_markdown": {
            "type": [
              "string",
              "null"
            ],
            "description": "正文可能保留来源的原始格式。"
          },
          "source_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "引用时保留原始来源。"
          },
          "aggregation_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "media_urls": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true,
            "description": "来源相关附加信息，不依赖未约定的内部字段。"
          },
          "published_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "原始内容发布时间，输出使用 Asia/Shanghai。"
          }
        },
        "required": [
          "id"
        ]
      },
      "TrumpData": {
        "type": "object",
        "properties": {
          "start_time": {
            "type": "string",
            "format": "date-time"
          },
          "end_time": {
            "type": "string",
            "format": "date-time"
          },
          "count": {
            "type": "integer",
            "minimum": 0
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TrumpStatement"
            }
          }
        },
        "required": [
          "start_time",
          "end_time",
          "count",
          "items"
        ]
      },
      "JsonResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "const": 0
          },
          "message": {
            "type": "string",
            "const": "ok"
          },
          "data": {
            "$ref": "#/components/schemas/JsonData"
          }
        },
        "required": [
          "code",
          "message",
          "data"
        ]
      },
      "GexImageResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "const": 0
          },
          "message": {
            "type": "string",
            "const": "ok"
          },
          "data": {
            "$ref": "#/components/schemas/GexImage"
          }
        },
        "required": [
          "code",
          "message",
          "data"
        ]
      },
      "FactorListResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "const": 0
          },
          "message": {
            "type": "string",
            "const": "ok"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FactorDescriptor"
            }
          }
        },
        "required": [
          "code",
          "message",
          "data"
        ]
      },
      "SignalListResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "const": 0
          },
          "message": {
            "type": "string",
            "const": "ok"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SignalResult"
            }
          }
        },
        "required": [
          "code",
          "message",
          "data"
        ]
      },
      "SeatResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "const": 0
          },
          "message": {
            "type": "string",
            "const": "ok"
          },
          "data": {
            "$ref": "#/components/schemas/SeatData"
          }
        },
        "required": [
          "code",
          "message",
          "data"
        ]
      },
      "PolymarketResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "const": 0
          },
          "message": {
            "type": "string",
            "const": "ok"
          },
          "data": {
            "$ref": "#/components/schemas/PolymarketData"
          }
        },
        "required": [
          "code",
          "message",
          "data"
        ]
      },
      "TrumpResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "const": 0
          },
          "message": {
            "type": "string",
            "const": "ok"
          },
          "data": {
            "$ref": "#/components/schemas/TrumpData"
          }
        },
        "required": [
          "code",
          "message",
          "data"
        ]
      }
    }
  }
}