API Reference
The Nexus Exchange API, with a page per endpoint, guides, and the official clients.
Everything a trader can do on the Nexus Exchange is available through this API.
Start here
Before you build
Reference
One page per endpoint, grouped by area in the sidebar
Schemas
Base URLs
The contract declares two public servers at the document level:
Testnet
https://api.testnet.nexus.xyz/v1
Play funds. Listed first, so code generators default to it.
Mainnet
https://api.nexus.xyz/v1
Real funds. Not reachable yet: the host has no DNS record (ENG-8155).
Pick a network explicitly; the contract does not name a default. The old gateway base, https://exchange.nexus.xyz/api/exchange, is retired and no longer in the contract. Point SDKs, the CLI, and the MCP server at the testnet base above.
/api/v1 paths
40 of the 121 paths are /api/v1/… versions of the unprefixed paths. They are the same operations, and both forms work on testnet:
https://api.testnet.nexus.xyz/v1/tickers → 200
https://api.testnet.nexus.xyz/api/v1/tickers → 200Prefer the unprefixed form on the /v1 base. It is what the official clients are moving to.
The /api/v1 paths sit on the host root, not on /v1. All 40 of them declare a path-level override to https://api.testnet.nexus.xyz, so /api/v1/tickers resolves to https://api.testnet.nexus.xyz/api/v1/tickers. Do not join the /v1 base and an /api/v1 path: https://api.testnet.nexus.xyz/v1/api/v1/… is not a URL the contract declares, even though testnet accepts it.
Sign the contract path, not the URL path. The /v1 prefix is stripped before the signature is checked, so it is not part of the HMAC canonical string. The /api/v1 prefix is. Calling https://api.testnet.nexus.xyz/v1/tickers means signing /tickers, and calling https://api.testnet.nexus.xyz/api/v1/tickers means signing /api/v1/tickers. See Authentication.
How this section is built
The endpoint pages are generated from the OpenAPI contract, and CI fails if they drift from it. The guides are written by hand and cover what one endpoint page cannot: order-type rules across every order-placing endpoint, sign conventions, the error model, and what the contract leaves unsaid.
The contract is served at /openapi.json and published at nexus-xyz/nexus-exchange-api, with releases on GitHub Releases. The SDKs, CLI, and MCP server are each generated from, or pinned to, a released version of it.
Clients
Rust, TypeScript, Python and Go SDKs, the nexus CLI, an MCP server and agent skills all call this API. SDKs & Tools lists each one with its repository and install line. A Postman collection generated from the contract signs HMAC requests for you; import it with the testnet or mainnet environment. Portfolio & Account State covers the account endpoints across all of them.
Requests are charged by weight per second, not by count, against three separate pools: reads, order writes, and the WebSocket control plane. Read Rate Limits before writing a client-side limiter.
Networks
The Exchange runs on testnet today as a development preview. Mainnet follows. Each client targets one network, chosen when you construct it, and defaults to testnet. API keys only work on the network that created them. See Networks, APIs & Rates, and the Quickstart.
Authentication
Sign a fixed message with your wallet (EIP-191) to get a short-lived session token. Use the token once to create an HMAC API key, then sign each trading request with that key. The SDKs and CLI sign for you. The Quickstart walks through it.
Status: development preview on testnet. The clients track the OpenAPI spec release by release. Pin a spec version in production and read the release notes before upgrading. Testnet credentials and balances have no real-world value.
Last updated