Orange Hitick Polymarket Up/Down API / Skill 文档

这份文档用于开发者手动接入，或让 Agent 按统一规则查询 Orange Hitick 提供的 Polymarket Up/Down 最新市场快照。

1. 服务信息

HTTP 接口：GET /api/v1/polymarket/up-down
鉴权方式：请求头 X-API-Token
返回包装：Orange Hitick 统一 ApiResponse
服务编码：polymarket_up_down
模型标识：PolymarketUpDown
计费说明：每次成功查询后计费
数据说明：返回后端当前保存的每个 symbol 最新快照；服务重启后内存数据会清空

平台统一返回结构：

{
  "code": 0,
  "message": "success",
  "data": {}
}

2. 鉴权

所有请求都必须带：

X-API-Token: your_token_value

3. 查询 API

GET /api/v1/polymarket/up-down

查询参数：

symbol：可选，Polymarket 标的代码，例如 WTI、BTC；大小写不敏感
传入 symbol 时返回该标的的最新快照
不传 symbol 时返回当前保存的全部标的，并按 symbol 排序

查询单个标的：

curl -sS 'https://api.hitick.top/api/v1/polymarket/up-down?symbol=WTI' \
  -H 'X-API-Token: your_token_value'

查询全部标的：

curl -sS 'https://api.hitick.top/api/v1/polymarket/up-down' \
  -H 'X-API-Token: your_token_value'

4. 返回结构

{
  "code": 0,
  "message": "success",
  "data": {
    "count": 1,
    "items": [
      {
        "queried_at": "2026-07-21T11:23:11.533922+08:00",
        "symbol": "WTI",
        "price": 82.43008,
        "up_mid_price": 0.485,
        "down_mid_price": 0.51
      }
    ]
  }
}

字段说明：

count：本次返回的快照数量
items：快照数组
queried_at：快照采集时间，以 Asia/Shanghai 时区和带 +08:00 偏移量的 ISO-8601 格式返回
symbol：Polymarket 标的代码
price：该场 Up/Down 市场的 price_to_beat 开盘基准价，不是查询时的标的最新行情价
up_mid_price：相对开盘基准价判断为 Up 的合约买卖中间价，计算方式为 (best_bid + best_ask) / 2
down_mid_price：相对开盘基准价判断为 Down 的合约买卖中间价，计算方式为 (best_bid + best_ask) / 2

5. Agent 接入规范

如果给 Agent 使用，建议按下面的最小规则封装。

5.1 工具名建议

orange_polymarket_up_down

5.2 输入结构建议

{
  "symbol": "WTI"
}

symbol 可选；不传时查询全部当前快照。

5.3 路由映射

传 symbol：GET /api/v1/polymarket/up-down?symbol={symbol}
不传 symbol：GET /api/v1/polymarket/up-down

5.4 Agent 调用建议

用户询问某个标的的 Polymarket 涨跌倾向时，传入对应 symbol
用户询问当前有哪些 Polymarket Up/Down 市场或希望整体比较时，不传 symbol
将 up_mid_price、down_mid_price 表述为“市场定价隐含约 X% 的 Up/Down 倾向”
概率换算属于市场定价近似值，需要说明会受到买卖价差、流动性和交易成本影响
查询标的自身最新行情时，另外调用行情数据接口，不要把 price 当作当前市价
涉及结算时刻或判定规则时，应另外获取对应市场规则后再解释
跨市场比较前，先确认标的映射、合约期限、观察时段和结算口径一致

6. 空结果与异常处理

未知 symbol 返回 count = 0 和空的 items，按“当前没有该标的快照”处理
不传 symbol 且当前没有任何快照时，同样返回空数组
code != 0 时直接向上层透传平台错误
快照只保存在当前服务进程内，服务重启后可能暂时没有数据

7. 解读示例

当接口返回：

{
  "symbol": "WTI",
  "price": 82.43008,
  "up_mid_price": 0.88,
  "down_mid_price": 0.115
}

建议表述为：

当前 Polymarket 合约定价隐含 WTI 相对本场开盘基准价向上的倾向约为 88%。这是受价差、流动性和交易成本影响的市场定价近似值；82.43008 是本场开盘基准价，不是当前实时行情价。

8. 使用限制

Polymarket 合约中间价不等于严格的统计概率
单个市场快照不应单独作为交易依据
回答具体结算问题前，应核对对应市场的期限和结算规则