---
name: xtrader-api-docs
description: Interprets the XTrader API from the Swagger 2.0 spec at https://api.xtrader.vip/swagger/doc.json and helps implement endpoints, TypeScript types, and request helpers. Use when implementing or understanding XTrader API endpoints, adding new API calls, or when the user refers to the API docs or Swagger.
---

# XTrader API 接口文档解读

规范来源：[OpenAPI 规范](https://api.xtrader.vip/swagger/doc.json)（Swagger 2.0）。Swagger UI：<https://api.xtrader.vip/swagger/index.html>。

---

## ⚠️ 强制执行：接口接入三步流程

**接入任意 XTrader 接口时，必须严格按以下顺序执行。收到「对接 XXX 接口」请求后，立即按此流程执行，不得跳过、不得调换、不得合并。**

### 强制动作序列（必须依次执行）

1. **收到对接请求** → 立即用 `mcp_web_fetch` 或 `curl` 获取 `https://api.xtrader.vip/swagger/doc.json`
2. **检查接口是否存在** → 若 `paths["<path>"]` 或 `paths["<path>"]["<method>"]` **不存在**，则：
   - ❌ **禁止**自行猜测或虚构数据结构并自动对接
   - ✅ **必须**在对话中明确告知用户「该接口在 doc.json 中不存在」
   - ✅ **必须**向用户询问：
     - 是否仍要对接？若对接，请提供**请求参数**与**响应数据结构**（或示例 JSON）
     - 用户可选择**不对接**，则流程终止
   - 仅在用户明确提供数据结构或确认对接后，才可进入第二步
3. **第一步**（接口存在时）→ 解析 `paths["<path>"]["<method>"]` 与 `definitions`，**在对话中输出**：
   - 请求参数表（Query/Body/鉴权）
   - 响应参数表（200 schema）
   - data 的 `$ref` 对应 definitions 的**完整字段表**
   - 输出后**明确标注「第一步完成」**
4. **第二步** → 在 `src/api/` 中根据第一步表格（或用户提供的数据结构）定义 TypeScript 类型，**不得在第一步完成前执行**
5. **第三步** → 实现请求函数并集成到页面，**不得在第二步完成前执行**

### 禁止行为

- ❌ 在对话中输出第一步结果**之前**写任何 `src/api/` 或 `src/views/` 业务代码
- ❌ 跳过第一步直接定义类型或实现请求
- ❌ 合并步骤（如边输出边写代码）
- ❌ **接口文档不存在时**：自行猜测数据结构并自动对接；必须向用户询问后再决定是否对接

### 接口文档不存在时的处理流程

当 `paths["<path>"]` 在 doc.json 中**不存在**时：

1. **立即停止**：不写任何对接代码，不猜测数据结构
2. **明确告知**：在对话中说明「该接口在 Swagger doc.json 中不存在」
3. **向用户询问**：
   - 是否仍要对接？若对接，请提供请求参数与响应数据结构（或示例 JSON）
   - 用户可选择**不对接**，则流程终止
4. **仅在用户明确提供**后，才继续执行第二步、第三步

### 第一步输出模板（必须包含）

```
## 第一步：GET/POST <path> 请求与响应参数

### 1. 请求参数
| 类型 | 名称 | 类型 | 必填 | 说明 |
| ... |

### 2. 响应参数（200）
根结构：{ code, data, msg }

### 3. definitions["xxx"] 完整字段
| 字段 | 类型 | 说明 |
| ... |

第一步完成。
```

## 规范地址与格式

- **规范 URL**：`https://api.xtrader.vip/swagger/doc.json`
- **格式**：Swagger 2.0；接口在 `paths` 下，类型在 `definitions` 下，引用为 `#/definitions/xxx`（如 `response.Response`、`system.SysUser`）。
- **使用方式**：用 `mcp_web_fetch` 或项目内请求获取 doc.json；解析 `paths` 与 `definitions` 编写 TS 类型与请求。鉴权：请求头 `x-token`（见 `securityDefinitions.ApiKeyAuth`）。

## Swagger UI 与 doc.json 的对应关系（如何定位 Example Value / Model）

Swagger UI 页面（如 [PmEvent findPmEvent](https://api.xtrader.vip/swagger/index.html#/PmEvent/get_PmEvent_findPmEvent)）的数据来源就是 **doc.json**。页面上的「Parameters」「Responses」里的 **Example Value** 和 **Model** 都对应 doc.json 里的同一套 schema。

### 对应关系一览

| Swagger UI 上看到的 | 在 doc.json 中的位置 |
|---------------------|----------------------|
| 某个接口（如「用id查询Event Management」） | `paths["/PmEvent/findPmEvent"].get`（或对应 path + method） |
| Parameters → Body / Query | `paths["/PmEvent/findPmEvent"].get.parameters`，或 body 的 `schema`（常为 `$ref`） |
| **Responses → 200 → Model** | `paths["/PmEvent/findPmEvent"].get.responses["200"].schema`，且需把其中的 `$ref` 解析到 `definitions` |
| **Responses → 200 → Example Value** | 由同一 `responses["200"].schema` 生成（或 schema 里的 `example`）；结构同 Model |
| Model 里展开的 `data`、`user` 等对象 | `definitions` 里对应的 schema，如 `definitions["polymarket.PmEvent"]`、`definitions["system.SysUser"]` |

### 如何快速定位「响应」的 Model / 数据结构

1. **确定 path 和 method**  
   例如 findPmEvent：path = `/PmEvent/findPmEvent`，method = `get`。

2. **取 200 的 schema**  
   ```text
   doc.json → paths["/PmEvent/findPmEvent"].get.responses["200"].schema
   ```  
   这就是页面上 200 的 **Model** 的完整定义（可能含 `allOf`、`$ref`）。

3. **解析 allOf + $ref**  
   - 若 schema 为 `allOf: [ { $ref: "#/definitions/response.Response" }, { type: "object", properties: { data: { $ref: "..." }, msg } } ]`，则合并后得到根结构：`code`、`data`、`msg`。  
   - 对 `data` 的 `$ref`（如 `#/definitions/polymarket.PmEvent`），到 **definitions** 里找：  
     `definitions["polymarket.PmEvent"]`（或 `definitions["response.LoginResponse"]` 等）。  
   - definitions 的 key 在 JSON 里是字符串，如 `"polymarket.PmEvent"`（带引号），对应 Swagger 里 `#/definitions/polymarket.PmEvent`。

4. **Example Value**  
   与 Model 共用同一份 `responses["200"].schema`；Example Value 是 Swagger UI 按该 schema 生成的示例，或 schema 内 `example` 字段。所以**看响应结构时以 Model 为准**，在 doc.json 里就是上述 `responses["200"].schema` 及其引用的 `definitions`。

## 接口集成规范（必须按顺序执行）

接入任意 XTrader 接口时，**必须**按以下顺序执行，不得跳过或调换。**第一步的输出必须在对话中可见，才能进入第二步。**

### 第一步：列出请求参数与响应参数

**在写任何代码之前**，先用 `mcp_web_fetch` 或 curl 获取 `https://api.xtrader.vip/swagger/doc.json`，然后整理并**在对话中输出**：

1. **请求参数**
   - **Query**：`paths["<path>"]["<method>"].parameters` 中 `in: "query"` 的项（name、type、required、description）。
   - **Body**：若存在 `in: "body"`，写出其 `schema` 对应的 `$ref` 或内联结构（来自 `definitions`）。
   - **鉴权**：该接口是否带 `security: [ { ApiKeyAuth: [] } ]`，若是则需在请求头加 `x-token`。

2. **响应参数**
   - 取 `paths["<path>"]["<method>"].responses["200"].schema`。
   - 若有 `allOf`，合并得到根结构（通常为 `code`、`data`、`msg`）。
   - 对 `data` 及其他嵌套对象的 `$ref`，到 `definitions` 中查完整结构并**列出所有字段**（名称、类型、说明）。

**输出形式**：表格或结构化列表，便于第二步写类型。**未完成第一步输出前，禁止进入第二步。**

### 第二步：根据响应数据创建 Model 类

- 在 `src/api/` 下相应模块（如 `event.ts`、`market.ts`）中，**根据第一步整理出的响应结构**定义 TypeScript 类型/接口：
  - 根响应：如 `XxxResponse { code: number; data: XxxData; msg: string }`。
  - `data` 及嵌套对象：对应 doc.json 的 `definitions`，写出完整 Model（如 `PmEvent`、`PmMarket`），避免只写 `any` 或过度使用 `[key: string]: unknown`（仅在确有扩展字段时使用）。
- 命名与项目一致：`PageResult<T>`、`XxxResponse`、`XxxParams` 等；与 `event.ts` 风格保持一致。

### 第三步：将接口集成到页面

- 在对应 API 模块中实现请求函数：使用 `get`/`post`（`src/api/request.ts`），路径、query/body 与第一步一致，返回类型使用第二步定义的 Response 类型。
- 在页面（Vue 组件）中：调用该请求函数，将返回的 `data` 绑定到组件的状态或 UI；处理 loading、错误与空数据；若为鉴权接口，确保调用时传入带 `x-token` 的 config（或使用已注入 token 的 request 封装）。

---

## 解读规范并落地的步骤

1. **Base URL**：规范中 `host` + `basePath`（可为空）；本项目已用 `src/api/request.ts` 的 `BASE_URL`（默认 `https://api.xtrader.vip`），实现时用相对 path 即可。

2. **路径与方法**：遍历 `paths`，每个 path + method 对应一个接口；path 以 `/` 开头。需鉴权接口在请求中加 `config.headers['x-token']`。

3. **请求参数**：Query 对应 `parameters` 中 `in: 'query'`；Body 对应 `in: 'body'` 的 `schema`（常为 `$ref` 到 `definitions`）。Swagger 2.0 中 body 参数名为 `data` 时，实际请求体即该 schema 的 JSON。

4. **响应类型**：看 `responses['200'].schema`；若为 `allOf`，合并 `response.Response` 与扩展中的 `data`、`msg` 等。`$ref` 到 `#/definitions/XXX` 时，在 `definitions` 中查对应结构并转为 TS 接口。统一响应包装为 `{ code, data, msg }`。

5. **与项目风格一致**：新接口放在 `src/api/` 下；导出请求/响应类型及调用 `get`/`post` 的函数；类型命名与 `event.ts` 一致（如 `PageResult<T>`、`XxxResponse`）。

## 已知接口（来自 doc.json）

### 钱包登录 `POST /base/walletLogin`

- **请求体**（`definitions.request.WalletLogin`）：`{ message: string, nonce: string, signature: string, walletAddress: string }`。
- **响应 200**：`{ code, data, msg }`；`data` 为 `response.LoginResponse`。
- **response.LoginResponse**：`{ expiresAt: number, token: string, user: system.SysUser }`。
- **system.SysUser**（`data.user`）：含 **ID**（integer，主键）、userName、nickName、headerImg、uuid、authorityId、authority、createdAt、updatedAt、email、phone、enable、walletAddress 等。**返回结果中包含用户 id，对应字段为 `user.ID`**（JSON 中可能为 `ID` 或 `id`，与后端序列化一致即可）。
- **项目映射**：`src/views/Login.vue` 调该接口；`src/stores/user.ts` 的 `UserInfo` 建议包含 `id?: number | string` 并与 `data.user.ID` 对应。

### 公开事件列表 `GET /PmEvent/getPmEventPublic`

- **Query**：page、pageSize、keyword、createdAtRange（array）、tokenid（可选，来自 market.clobTokenIds 的值，可传单个或数组）。
- **响应 200**：`data` 为 `response.PageResult`（list、page、pageSize、total）；list 项为 `polymarket.PmEvent`，内含 markets、series、tags 等，markets[].outcomePrices 为价格数组，首项对应 Yes 概率；markets[].clobTokenIds 与 outcomes/outcomePrices 顺序一致。

### 订单类型与交易方向（用于交易接口，`src/api/constants.ts`）

- **OrderType**：GTC=0（一直有效直到取消）、GTD=1（指定时间内有效）、FOK=2（全部成交或取消）、FAK=3（立即成交剩余取消）、Market=4（市价单）。
- **Side**：Buy=1、Sell=2。

### 通用响应与鉴权

- **response.Response**：`{ code: number, data: any, msg: string }`。
- **response.PageResult**：`{ list, page, pageSize, total }`。
- 需鉴权接口在文档中带 `security: [ { ApiKeyAuth: [] } ]`，请求时加 header `x-token`。

## 简要检查清单

- [ ] **接口存在性**：若 doc.json 中无该 path，已向用户询问数据结构，未擅自猜测对接  
- [ ] **按规范顺序**：已先列出请求参数与响应参数，再建 Model，最后集成到页面  
- [ ] 规范 URL 使用 `https://api.xtrader.vip/swagger/doc.json`，或本地缓存与之一致  
- [ ] 请求 path、method、query/body 与 `paths` 一致  
- [ ] 响应类型（Model）覆盖 `code`/`data`/`msg` 及 `definitions` 中业务字段  
- [ ] 鉴权接口使用 `x-token` header  
- [ ] 新代码风格与 `src/api/request.ts`、`src/api/event.ts` 一致  

## 参考

- 规范：<https://api.xtrader.vip/swagger/doc.json>  
- Swagger UI：<https://api.xtrader.vip/swagger/index.html>  
- 项目请求封装：`src/api/request.ts`  
- 现有接口与类型：`src/api/event.ts`