> 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/readme.md).

# API 参考

Nexus Exchange 的程序化接口，包含每个端点、讲解这些端点的指南以及官方客户端。

交易者在 Nexus Exchange 上能做的一切，都可以通过程序完成。本部分为每个端点提供一个页面，另有讲解这些端点的手写指南，以及官方支持的客户端。

|            |                                                                                                                                                                                                           |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **从这里开始**  | [入门](/api-reference/zh-cn/guides/get-started.md) · [身份验证](/api-reference/zh-cn/guides/authentication.md) · [代理密钥](/api-reference/zh-cn/guides/agent-keys.md)                                              |
| **开发之前**   | [订单类型](/api-reference/zh-cn/guides/order-types.md) · [速率限制](/api-reference/zh-cn/guides/rate-limits.md) · [错误](/api-reference/zh-cn/guides/errors.md) · [已知缺口](/api-reference/zh-cn/guides/known-gaps.md) |
| **参考**     | 每个端点一个页面，在侧边栏中按领域分组                                                                                                                                                                                       |
| **Schema** | [Schema 参考（英文）](https://docs.nexus.xyz/api-reference/guides/schemas)                                                                                                                                      |

## 基础 URL

接口契约在文档级别声明了三个服务器，顺序如下：

| 服务器       | URL                                | 用途                                                                                            |
| --------- | ---------------------------------- | --------------------------------------------------------------------------------------------- |
| 公共测试网（默认） | `https://api.testnet.nexus.xyz/v1` | 测试资金。`/v1` 传输基础路径，用于**不带前缀**的路径。它排在列表第一位，因此是生成器默认选用的基础 URL。                                   |
| 主网        | `https://api.nexus.xyz/v1`         | **真实资金**。有意排在测试网之后，这样任何选取“第一个 `https` 服务器”的工具都不会落到真实资金目标上。目前尚无法解析。DNS 是一项单独的基础设施变更（ENG-8155）。 |
| 本地开发      | `http://localhost:9090`            | 在您自己机器上运行的索引器。                                                                                |

契约没有指定默认网络，因此请显式选择一个。上表中的“默认”仅表示测试网是 `servers[0]`，即您未作选择时生成器选用的基础 URL。旧版网关基础 URL `https://exchange.nexus.xyz/api/exchange` 已**停用**。它已从契约中移除，并返回 HTTP 410，其 JSON 响应体会指明替代地址。请将 SDK、CLI 和 MCP 服务器指向上面的公共测试网基础 URL，该地址会执行速率限制和分级。

### 带版本（`/api/v1`）的路径与不带前缀的路径

110个路径中有40个是不带前缀路径的 `/api/v1/…` 带版本同级路径。它们是相同的操作，只是通过带版本的挂载点访问。两种形式在公共测试网主机上都可用：

```
https://api.testnet.nexus.xyz/v1/tickers       → 200
https://api.testnet.nexus.xyz/api/v1/tickers   → 200
```

**优先在 `/v1` 基础 URL 上使用不带前缀的形式**。这是文档级 `servers` 条目声明的形式，也是官方客户端正在迁移到的布局。契约没有将任一形式标记为 `deprecated`。五个 `/api/v1/bridge/…` 路径在契约中暂时还没有不带前缀的写法，因此目前请以 `/api/v1` 形式调用它们。

**签名的是契约路径，而不是 URL 路径**。用于选择挂载点的传输前缀（公共测试网基础 URL 上的 `/v1`）会在请求到达验证签名的服务之前被去除，因此它不属于 HMAC 规范字符串。`/api/v1` 前缀属于契约路径，*需要*签名。调用 `https://api.testnet.nexus.xyz/api/v1/tickers` 意味着签名 `/api/v1/tickers`；调用 `https://api.testnet.nexus.xyz/v1/tickers` 意味着签名 `/tickers`。参见[身份验证](/api-reference/zh-cn/guides/authentication.md)。

{% hint style="info" %}
**`/api/v1` 路径带有 `servers` 覆盖，客户端应遵循它**。这40个路径都声明了路径级覆盖，指向公共测试网的**主机根地址** `https://api.testnet.nexus.xyz`，本地开发时则为 `http://localhost:9090`。完整的操作路径追加在其后，因此 `/api/v1/tickers` 解析为 `https://api.testnet.nexus.xyz/api/v1/tickers`。这就是生成的参考页面所显示的“Declared server”，遵循该覆盖的生成客户端可以访问到 API。

之所以有这个覆盖，是因为该基础 URL 与文档级的不同。文档的测试网条目带有 `/v1`，并期望不带前缀的路径（`https://api.testnet.nexus.xyz/v1/tickers`），而带前缀的路径需要主机根地址。手动拼接这两部分会得到 `https://api.testnet.nexus.xyz/v1/api/v1/…`，这不是契约为这些路径声明的 URL。契约注明公共测试网的 chart 也接受这种形式：chart 只去除外层的 `/v1`，请求仍然签名 `/api/v1/…`。
{% endhint %}

### 如何阅读本部分

**参考页面由契约生成**。每个页面只陈述 `openapi.json` 为该操作声明的内容，不多也不少：参数、请求体、响应、身份验证方案以及速率限制类别。CI 会重新渲染并比对这些页面，因此它们不会偏离契约。

**指南是手写的**。指南涵盖单个端点页面无法说明的内容：所有下单操作的订单类型要求矩阵、正负号约定、错误模型，以及契约未说明的事项清单。

**本部分不说明端点或 Schema 的数量**。上一次手工维护的计数出现了偏差。本部分的上一个版本发布的规范版本落后了十八个次要版本，操作和 Schema 的计数也同样过时。侧边栏由契约生成，契约在 `/openapi.json` 提供。两者都具有权威性，因此都不需要在正文中重复一个数字。

### OpenAPI 规范

该 API 采用契约优先的方式。机器可读的 Schema 包含每个路由、请求/响应体以及 CCXT 方法映射，发布在 [`nexus-xyz/nexus-exchange-api`](https://github.com/nexus-xyz/nexus-exchange-api)，并在 `/openapi.json` 实时提供。版本发布记录在 [GitHub Releases](https://github.com/nexus-xyz/nexus-exchange-api/releases)。下面的 SDK、CLI 和 MCP 服务器均由该规范的某个已发布版本生成或固定到该版本，因此与网关保持一致。

### SDK

| 语言         | 仓库                                                                    | 适用场景            |
| ---------- | --------------------------------------------------------------------- | --------------- |
| Rust       | [`nexus-exchange-rs`](https://github.com/nexus-xyz/nexus-exchange-rs) | 对延迟敏感的客户端和做市机器人 |
| TypeScript | [`nexus-exchange-ts`](https://github.com/nexus-xyz/nexus-exchange-ts) | Web、Node 和边缘应用  |
| Python     | [`nexus-exchange-py`](https://github.com/nexus-xyz/nexus-exchange-py) | 研究、回测和脚本        |

每个 SDK 都会处理请求签名（HMAC 或代理密钥）、分页以及 WebSocket 订阅生命周期，您无需自行重新实现。关于各 SDK 的签名开销，以及它能否跟上您的等级，请参见[各 SDK 的签名开销](/api-reference/zh-cn/guides/rate-limits.md#can-your-signer-keep-up)。版本支持和破坏性变更策略记录在各仓库的 README 中。

[资产组合与账户状态](/api-reference/zh-cn/guides/portfolio.md)统一介绍全部四种接口的账户和资产组合端点：合并的账户状态、可提现余额、手续费表、扩充的仓位风险字段，以及权益/盈亏/成交量时间序列。

无论您用什么构建，适用的都是同一套额度。请求按**每秒权重**计费，而不是按次数计数，读取、订单写入和 WebSocket 控制面分别使用三个相互独立的额度池。在编写客户端限速器之前，请先阅读[速率限制](/api-reference/zh-cn/guides/rate-limits.md)。按请求次数限速的客户端会在自身计数器看起来仍然正常时遭到拒绝。

### 命令行

[`nexus-exchange-cli`](https://github.com/nexus-xyz/nexus-exchange-cli) 封装了同一 API，用于交互式使用和 shell 脚本。它可以管理密钥、下单和撤单，以及查询账户状态，无需您编写代码。`nexus --version` 会报告其构建所依据的 API 规范和 SDK 版本。

### MCP 服务器

[`nexus-exchange-mcp`](https://github.com/nexus-xyz/nexus-exchange-mcp) 服务器将交易所以 [Model Context Protocol](https://modelcontextprotocol.io) 工具的形式开放，使 AI 助手或代理能够通过与人类客户端相同的已认证 API 进行交易和读取账户状态。它以 [`@nexus-xyz/exchange-mcp`](https://www.npmjs.com/package/@nexus-xyz/exchange-mcp) 发布：

```bash
claude mcp add nexus-exchange -- npx -y @nexus-xyz/exchange-mcp
```

它通过 stdio 运行，因此凭证保留在添加它的机器上，其公开的市场数据工具完全无需密钥即可使用。

### 选择网络

交易所目前以开发预览版的形式运行在 **Nexus Testnet** 上，公共**主网**将随后推出。每个接口一次只面向一个网络（`testnet`、`mainnet` 或 `local`），在构造客户端时选定。客户端内置了该网络的 REST 和 WebSocket 目标、水龙头可用性以及签名域。未传入网络时，SDK、CLI 和 MCP 服务器使用测试网，主网目前尚无法访问。凭证的作用范围限定于创建它们的网络。

关于各接口如何选择网络、如何覆盖目标，以及什么将 API 密钥绑定到网络，请参见[网络](/api-reference/zh-cn/guides/networks.md)；当前的基础 URL 请参见 [API 与速率限制](https://docs.nexus.xyz/exchange/apis-and-rates)；端到端的连接流程请参见[快速入门](https://docs.nexus.xyz/exchange/trading/quickstart)。

### 身份验证

所有接口的身份验证方式完全相同。您用钱包对一条固定消息进行签名（EIP-191），获得一个短期有效的会话令牌，用该令牌一次性创建一个 HMAC API 密钥，然后用该密钥对每个交易请求签名。SDK 和 CLI 会替您签名请求。包含可运行示例的完整演练见[快速入门](https://docs.nexus.xyz/exchange/trading/quickstart)。

> **状态**：测试网上的开发预览版。各接口随 OpenAPI 规范逐版本跟进；在生产环境中请固定到某个规范版本，并在升级前查阅各仓库的发布说明。测试网凭证和余额没有任何现实价值。


---

# 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/readme.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.