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
Before you build
Reference
One page per endpoint, grouped by surface in the sidebar
Schemas
Base URLs
The contract declares two servers at the document level:
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 → 200Prefer 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.
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.
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 and served live at /openapi.json. Releases are tracked on GitHub 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
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, 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 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 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 server exposes the Exchange as Model Context Protocol 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:
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 for how each interface selects one, how to override the target, and what binds an API key to a network; APIs & Rates for the current base URL; and the 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.
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.
Last updated