xtraderClient/.cursor/skills/xtrader-api-docs/SKILL.md

name, description

name	description
xtrader-api-docs	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 规范（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）的数据来源就是 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

   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