> 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/readme.md). # API Reference Everything a trader can do on the Nexus Exchange is available programmatically. This section is the complete interface: a page per endpoint, the hand-written guides that give them context, and the officially supported clients. | | | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Start here** | [Get Started](/api-reference/guides/get-started.md) · [Authentication](/api-reference/guides/authentication.md) · [Agent Keys](/api-reference/guides/agent-keys.md) | | **Before you build** | [Order Types](/api-reference/guides/order-types.md) · [Rate Limits](/api-reference/guides/rate-limits.md) · [Errors](/api-reference/guides/errors.md) · [Known Gaps](/api-reference/guides/known-gaps.md) | | **Reference** | One page per endpoint, grouped by surface in the sidebar | | **Schemas** | [Schema Reference](/api-reference/guides/schemas.md) | ## Base URLs The contract declares two servers at the document level: | Server | URL | Use | | ----------------- | ----------------------------------------- | ------------------------------------------------------------------------ | | Production | `https://exchange.nexus.xyz/api/exchange` | The gateway. This is the base for every path documented in this section. | | Local development | `http://localhost:9090` | A gateway running on your own machine. | Use the gateway base — `https://exchange.nexus.xyz/api/exchange`. It is the origin the SDKs, CLI, and MCP server resolve to by default, and the one that enforces rate limiting and tiering. It is also the only publicly routable base (see the warning below). ### Versioned (`/api/v1`) and unprefixed paths 33 of the 85 paths are `/api/v1/…` versioned siblings of the unprefixed paths — the same operations, reached through a versioned mount. Both forms work, and both live **under the gateway base**: ``` https://exchange.nexus.xyz/api/exchange/tickers → 200 https://exchange.nexus.xyz/api/exchange/api/v1/tickers → 200 ``` **Prefer the `/api/v1/…` form.** It is the canonical, versioned surface; the unprefixed paths are the *legacy root mounts* and are on a migration path toward retirement, after which routes are reachable only under `/api/v1`. The contract marks neither variant `deprecated`, so this guidance comes from the implementation rather than from the spec. **Sign the contract path, not the URL path.** The `/api/exchange` gateway mount is stripped before the request reaches the service that verifies your signature, so it is not part of the HMAC canonical string — but the `/api/v1` prefix is. Calling `…/api/exchange/api/v1/tickers` means signing `/api/v1/tickers`. See [Authentication](/api-reference/guides/authentication.md). {% hint style="warning" %} **Do not take the contract's `servers` override literally.** 29 of the 33 `/api/v1` paths declare a path-level override to `https://exchange.nexus.xyz` ("Production (direct service)"). That host is **not publicly routable for the API** — a request to `https://exchange.nexus.xyz/api/v1/tickers` returns the web app's 404 HTML page, not JSON. The override describes the service's own address behind the gateway, not a base that external integrators can call. Prepend the gateway base to every path in this section, including the `/api/v1` ones. A generated client that honours the override verbatim will not reach the API. {% endhint %} ### How to read this section **The Reference pages are generated from the contract.** Each one states exactly what `openapi.json` declares for that operation — parameters, request body, responses, authentication scheme, rate-limit class — and nothing it does not. They are re-rendered and diffed in CI, so they cannot drift from the contract they document. **The Guides are hand-written**, and they carry what a per-endpoint page structurally cannot: the order-type requirement matrix that spans every order-placing operation, the sign conventions, the error model, and the list of things the contract leaves unsaid. **Deliberately not stated here: how many endpoints or schemas there are.** A hand-maintained count is exactly what drifted last time — the previous version of this section published a spec version eighteen minor releases stale, alongside operation and schema counts to match. The sidebar is generated from the contract and the contract is served at `/openapi.json`; both are authoritative, and neither needs a number restated in prose. ### The OpenAPI specification The API is contract-first. The machine-readable schema — every route, request/response body, and CCXT method mapping — is published at [`nexus-xyz/nexus-exchange-api`](https://github.com/nexus-xyz/nexus-exchange-api) and served live at `/openapi.json`. Releases are tracked on [GitHub Releases](https://github.com/nexus-xyz/nexus-exchange-api/releases). The SDKs, CLI, and MCP server below are all generated from — or pinned to — a released version of this spec, so they stay in lockstep with the gateway. ### SDKs | Language | Repository | Use it for | | ---------- | --------------------------------------------------------------------- | ------------------------------------------------ | | Rust | [`nexus-exchange-rs`](https://github.com/nexus-xyz/nexus-exchange-rs) | Latency-sensitive clients and market-making bots | | TypeScript | [`nexus-exchange-ts`](https://github.com/nexus-xyz/nexus-exchange-ts) | Web, Node, and edge applications | | Python | [`nexus-exchange-py`](https://github.com/nexus-xyz/nexus-exchange-py) | Research, backtesting, and scripting | Each SDK handles request signing (HMAC), pagination, and the WebSocket subscription lifecycle so you don't reimplement them. Version support and breaking-change policy are documented in each repository's README. For the account and portfolio surface — consolidated account state, the withdrawable balance, the fee schedule, enriched position risk fields, and the equity/PnL/volume time-series — see [Portfolio & Account State](/api-reference/guides/portfolio.md), which covers all four interfaces together. Whatever you build with, the same budget applies: requests are charged by **weight per second** rather than counted, and reads, order writes, and the WebSocket control plane draw on three independent pools. See [Rate Limits](/api-reference/guides/rate-limits.md) before writing a client-side limiter — a client that paces by request count will be refused while its own counter still looks healthy. ### Command line The [`nexus-exchange-cli`](https://github.com/nexus-xyz/nexus-exchange-cli) wraps the same API for interactive use and shell scripting — manage keys, place and cancel orders, and query account state without writing code. `nexus --version` reports the API spec and SDK versions it is built against. ### MCP server The [`nexus-exchange-mcp`](https://github.com/nexus-xyz/nexus-exchange-mcp) server exposes the Exchange as [Model Context Protocol](https://modelcontextprotocol.io) tools, so an AI assistant or agent can trade and read account state through the same authenticated API a human client uses. It is published as [`@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 ``` It runs over stdio, so credentials stay on the machine that adds it, and its public market-data tools work with no key at all. ### Choosing a network The Exchange runs on **Nexus Testnet** today as a development preview, with a public **mainnet** to follow. Every interface targets one network at a time — `testnet`, `mainnet`, or `local` — selected when you construct the client, which bundles that network's REST and WebSocket targets, faucet availability, and signing domain together. Testnet is the default everywhere; mainnet is not reachable yet. Credentials are scoped to the network they were created on. See [Networks](/api-reference/guides/networks.md) for how each interface selects one, how to override the target, and what binds an API key to a network; [APIs & Rates](https://docs.nexus.xyz/exchange/apis-and-rates) for the current base URL; and the [Quickstart](https://docs.nexus.xyz/exchange/trading/quickstart) for the end-to-end connection flow. ### Authentication Authentication is identical across every interface. You sign a fixed message with your wallet (EIP-191) to obtain a short-lived session token, use that token once to mint an HMAC API key, then sign each trading request with that key. The SDKs and CLI perform the request signing for you. The full walkthrough, with runnable examples, is in the [Quickstart](https://docs.nexus.xyz/exchange/trading/quickstart). > **Status:** development preview on testnet. The interfaces track the OpenAPI spec release-by-release; pin to a spec version in production and consult each repository's release notes before upgrading. Testnet credentials and balances have no real-world value. --- # 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/readme.md?ask=&goal= ``` `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.