> 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 The programmatic interface to the Nexus Exchange — every endpoint, the guides around them, and the official clients. 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 four servers at the document level, in this order: | Server | URL | Use | | ------------------------ | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Legacy gateway (default) | `https://exchange.nexus.xyz/api/exchange` | Serves **testnet**. First in the list, so it stays the base a generator picks by default. Transitional: it is removed in a deliberate breaking release once the per-network hosts are live. | | Public testnet | `https://api.testnet.nexus.xyz/v1` | Play funds. The `/v1` transport base, for the **unprefixed** paths. | | Mainnet | `https://api.nexus.xyz/v1` | **Real funds.** Listed after testnet on purpose, so nothing reaching for "the first `https` server" lands on the real-funds target. Not resolvable yet — DNS is a separate infra change (ENG-8155). | | Local development | `http://localhost:9090` | An indexer running on your own machine. | There is no implicit default network: select one explicitly. The legacy gateway base is the origin the SDKs, CLI, and MCP server resolve to today, and the one that enforces rate limiting and tiering. ### Versioned (`/api/v1`) and unprefixed paths 39 of the 105 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="info" %} **The `/api/v1` paths carry a `servers` override, and it is meant to be honoured.** All 39 of them declare a path-level override to the public testnet **host root** — `https://api.testnet.nexus.xyz`, or `http://localhost:9090` for local development. The full operation path appends to it, so `/api/v1/tickers` resolves to `https://api.testnet.nexus.xyz/api/v1/tickers`. That is the "Declared server" the generated Reference pages show, and a generated client that honours it reaches the API. The override exists *because* that base differs from the document one: the document's testnet entry carries `/v1` and expects an unprefixed path (`https://api.testnet.nexus.xyz/v1/tickers`), while the prefixed paths need the host root. Combining the two halves by hand is what goes wrong. `https://exchange.nexus.xyz/api/v1/…` is not a valid combination either — under that host the prefixed paths live below the `/api/exchange` mount, not at the root. {% 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.