> For the complete documentation index, see [llms.txt](https://docs.nexus.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexus.xyz/api-reference/zh-cn/guides/known-gaps.md).

# 已知缺口

API 契约中的缺口与不一致之处，只做标注，不做填补。

**本页列出契约没有说明的内容**。参考部分的端点页面由 `openapi.json` 生成，只描述契约所声明的内容，不多不少。凡是契约未作说明、含义模糊或自相矛盾之处，本页都如实记录，而不是用看似合理的文字去填补缺口。

如果您要对接的某个操作，其行为是靠推断而非阅读契约得来的，请先阅读本页。

每一条都归在它所属的 API 部分之下。这里的内容均不构成路线图承诺，只是对契约现状的观察。

**基线已对照规范 `0.9.90` 核实，并且每次规范版本升级时，下面每一条都会重新检查**，检查脚本为 `.github/scripts/known_gaps_check.py`。每一条都在 `known-gaps-assertions.json` 中针对契约注册了一个谓词。当某个谓词不再成立时，说明该缺口已被填补，CI 会一直失败，直到该条目被删除。针对文字描述而非结构作出断言的条目会标注为人工核实，并注明上次核对时所依据的规范版本，同一道检查也要求该版本保持同步。

过时的缺口列表比没有缺口列表更糟。在 `0.9.27` 到 `0.9.63` 之间，本列表就曾过时：有八条是错的，其中三条描述的缺口契约早已补上。正因如此，检查现在改为机械执行，而不再只是承诺会重新阅读。

## 交易

* **批量上限**。`POST /orders/batch` 没有声明批量的最大长度，契约也没有说明一个批量请求在速率限制中如何计权（按一个请求计，还是按每个元素计）。
* **`reduce_only`。** 声明为布尔值，没有任何描述。它与条件单和跟踪单类型的相互作用未作说明。
* **`PreviewResponse` 字段语义。** 这八个字段都有类型，但在契约中没有任何描述。
* **触发方向**。对于止损和止盈两类订单，“不利”和“有利”没有按 `side` 给出正式定义。
* **有效期 × 条件单类型**。契约没有说明六种条件单类型分别可以使用哪些 `time_in_force` 值（例如 `StopMarket` 上能否使用 `PostOnly`）。
* **可修改性**。除了“强平订单不可修改”之外，契约没有说明条件单或跟踪单能否修改，也没有说明修改时能否更改 `time_in_force`。
* **`stop_price` 的移除。** 已标记为弃用，但没有说明将在哪个版本或哪一天移除。

## 仓位

* **`leverage` 目前始终为 `null`。** 契约说明它“当前始终为 `null`”，并附带 `leverage_error: "margin_state_not_mirrored"`，但没有给出何时填充该字段的目标。客户端无法从这些端点读取单个仓位的杠杆。
* **已平仓仓位不支持按市场筛选**。`GET /positions/closed` 只接受 `limit` 和 `cursor`，因此无法把查询限定在单个市场。它既不接受 `market_id`，也不接受 `symbol`。响应字段在 `0.9.74` 中改名为 `symbol`，而该参数在两个名称下都从未存在过。
* **保留窗口未说明**。`funding_paid` 被描述为“受索引器所保留的资金费历史限制”，但没有给出保留期限。这些端点上的游标分页已不再属于本缺口：`GET /positions/closed` 在 `limit` 上说明了200条记录的保留窗口。
* **已平仓仓位缺少 `429`。** `GET /positions/closed` 及其 `/api/v1` 对应版本只声明了 `200` 和 `401`。尽管同一速率限制层同样适用，契约却省略了另一个仓位操作所声明的 `429` 响应。
* **仅支持全仓**。`initialMargin` 的定义是“基于引擎的全仓保证金模型”，契约还指出索引器不会镜像逐仓或自定义保证金分配。因此，这里读不到逐仓仓位的真实分配。
* **没有未平仓仓位的数量或总数**。`GET /positions` 的响应是一个裸数组，既没有外层封装，也没有分页，因此单个响应最多可以包含多少个仓位，没有文档说明的上限。

## 账户

* **`direction` 没有枚举值。** `POST /account/margin` 完全没有声明请求结构。它的示例显示 `"direction": "add"`，摘要和 `400` 描述暗示也支持减少保证金，但契约从未说明减少时应使用什么值，也没有说明字段类型，或将任何字段标为必填。
* **两个操作没有声明请求结构**。`POST /account/deposit` 和 `POST /account/margin` 只有请求示例，因此根据契约生成的客户端在这两个操作上得到的都是无类型的请求体。它们的响应是有类型的（`DepositResponse`、`AdjustMarginResponse`），未声明的是请求一侧。
* **两条重叠的充值路径**。`POST /account/deposit` 和 `POST /deposits` 都用于充值抵押品，都返回 `DepositResponse`，而契约没有说明应优先使用哪一个，也没有说明两者在运行上有何区别。由于响应相同，无法根据返回的结构区分两者。
* **状态词汇不一致**。`Withdrawal.status` 为 `pending` / `settled` / `failed`，而 `FundsEntry.status` 为 `pending` / `submitted` / `confirmed` / `failed`。同一个生命周期有两套名称，阶段数量也不同，因此两者之间不存在完整的映射。`submitted` 在 `Withdrawal` 上没有对应值，`settled` 在 `FundsEntry` 上也没有对应值。
* **速率限制等级的大小写不一致**。`RateLimitStatus.tier` 的文档写法是小写（`pro`、`marketmaker`、`unlimited`）。`429` 响应体示例返回 `"tier": "Pro"`。管理端的等级管理操作使用 `MarketMaker` 和 `Pro`。契约没有说明哪种大小写是规范写法。
* **`429` 的覆盖不均衡。** 有几个受同一速率限制层约束的操作只声明了 `200` 和 `401`：两个权益历史操作、两个订单历史操作、两个断线撤单（cancel-on-disconnect）的 GET 和 PUT、`GET /withdrawals`、`GET /deposits`、`POST /deposits`、`GET /orders/{order_id}`，以及两个速率限制状态操作。
* **保留窗口是记录条数，而不是时长**。现在每个操作都说明了其保留窗口的容量（1,000条成交、500条订单历史记录、200个已平仓仓位、720个权益数据点、10,000笔交易）。但没有任何操作说明这能追溯到多久以前，所以客户端无法判断一次遍历覆盖的是一周还是一年。`volume_30d` 少计的问题已不再属于本缺口：`volume_30d_estimated` 说明了适用哪种保证。
* **有两处 `limit` 的最大值低于文字描述。** `GET /withdrawals` 和 `GET /deposits` 都把 `limit` 上限设为100，默认值也是100，因此该参数只能缩小页面。由于这两个操作都不接受 `cursor`，无法翻页获取100条之后的记录。
* **`EquityPoint.equity` 是 JSON 数字。** 该标签下其他所有金额字段都是无损的十进制字符串。契约本身也指出了它与 `PortfolioPoint.equity` 的不一致，并要求客户端按十进制数值进行比较，但线路上传输的仍是浮点表示。
* **`early_access_allowed` 表示的是有或无，而不是真或假。** 契约说它“仅在抢先体验闸门启用时”出现，但没有说明由什么控制该闸门，也没有说明该字段缺失对调用方意味着什么。
* **没有按账户划分的等级或折扣计划**。`AccountFees.tier` 始终为 `base`，`discounts` 始终为空，`FeeDiscount` 没有定义任何属性。当前保留的成交缓冲区内各市场的实际费率在 `markets` 中提供。某个市场不在其中，并不能说明该账户的历史交易情况。调用方仍须把 `schedule` 当作开放字符串处理，并区分 `per_market`、`reference` 以及取值为零的 `unknown` 哨兵值。
* **`Position.leverage` 目前始终为 `null`**，所有内嵌仓位的响应（`AccountSummary`、`AccountState`）都是如此，并附带 `leverage_error: "margin_state_not_mirrored"`。参见 [`GET /positions`](https://docs.nexus.xyz/api-reference/positions/fetch-positions)。

## 管理

* **等级名称没有枚举**。没有结构定义，没有 `enum`，也没有列表。这里只有 `MarketMaker` 以示例形式出现，而 `pro` / `marketmaker` / `unlimited` 只出现在 `RateLimitStatus` 描述的文字中。运营方无法从契约中得知有效取值的集合。
* **整个契约中的大小写不一致**。这些操作使用 `MarketMaker` 和 `Pro`。`RateLimitStatus.tier` 的文档写法是小写（`pro`、`marketmaker`、`unlimited`）。共用的 `429` 响应体示例返回 `"tier": "Pro"`。契约没有说明哪种大小写是规范写法，也没有说明比较时是否区分大小写。
* **没有请求结构，且有一个响应也没有结构**。三个操作都没有声明请求结构，因此根据契约生成的客户端得到的请求体全部是无类型的。`GET` 和 `PUT /admin/tiers` 声明了 `200` 响应结构，而 `DELETE /admin/tiers/{address}` 没有。
* **删除时返回 `404 Address not in allowlist`，但别处都没有白名单。** 当地址“不在白名单中”时，`DELETE /admin/tiers/{address}` 返回 `404`，而 `PUT /admin/tiers` 没有说明任何白名单前提条件，`GET /admin/tiers` 则把其结果描述为“覆盖设置”。覆盖设置存储与白名单之间的关系未作说明。
* **没有声明 `401`，也没有声明速率限制。** 这些操作只声明了 `200`、`403`，以及（删除操作上的）`404`。对于格式错误的 `Authorization` 请求头，没有区别于密钥错误的文档化行为；也没有速率限制响应，所以 bearer secret 没有声明的限流。
* **接口上没有审计记录**。契约中没有任何内容能显示是谁在何时设置了某个等级。`GET /admin/tiers` 只返回当前状态。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nexus.xyz/api-reference/zh-cn/guides/known-gaps.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.