API 参考

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

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

从这里开始

入门 · SDK 与工具 · 身份验证 · 代理密钥

开发之前

订单类型 · 速率限制 · 错误 · 已知缺口

参考

每个端点一个页面，在侧边栏中按领域分组

Schema

Schema 参考（英文）

基础 URL

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

服务器

URL

用途

公共测试网（默认）

https://api.testnet.nexus.xyz/v1

测试资金。/v1 传输基础路径，用于不带前缀的路径。它排在列表第一位，因此是生成器默认选用的基础 URL。

主网

https://api.nexus.xyz/v1

真实资金。有意排在测试网之后，这样任何选取“第一个 https 服务器”的工具都不会落到真实资金目标上。目前尚无法解析。DNS 是一项单独的基础设施变更（ENG-8155）。

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

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

116个路径中有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/v1 路径带有 servers 覆盖，客户端应遵循它。这40个路径都声明了路径级覆盖，指向公共测试网的主机根地址 https://api.testnet.nexus.xyz。完整的操作路径追加在其后，因此 /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/…。

如何阅读本部分

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

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

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

OpenAPI 规范

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

SDK 与工具

Rust、TypeScript、Python 和 Go SDK、nexus CLI、一个 MCP 服务器以及智能体技能都调用此 API。SDK 与工具列出了每一项及其仓库和安装命令。

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

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

选择网络

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

关于各接口如何选择网络、如何覆盖目标，以及什么将 API 密钥绑定到网络，请参见网络；当前的基础 URL 请参见 API 与速率限制；端到端的连接流程请参见快速入门。

身份验证

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

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

下一页入门

最后更新于 2天前