# 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 最新快照；服务重启后内存数据会清空

平台统一返回结构：

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

## 2. 鉴权

所有请求都必须带：

```http
X-API-Token: your_token_value
```

## 3. 查询 API

```http
GET /api/v1/polymarket/up-down
```

查询参数：

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

查询单个标的：

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

查询全部标的：

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

## 4. 返回结构

```json
{
  "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 工具名建议

```text
orange_polymarket_up_down
```

### 5.2 输入结构建议

```json
{
  "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. 解读示例

当接口返回：

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

建议表述为：

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

## 8. 使用限制

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