> 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 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**       | [Get Started](/api-reference/guides/get-started.md) · [SDKs & Tools](/api-reference/guides/sdks.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 area in the sidebar                                                                                                                                                               |
| **Schemas**          | [Schema Reference](/api-reference/guides/schemas.md)                                                                                                                                                                |

## Base URLs

The contract declares two public servers at the document level:

| Server  | URL                                | Use                                                         |
| ------- | ---------------------------------- | ----------------------------------------------------------- |
| 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 live yet.                               |

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.

### Legacy `/api/v1` aliases

The `/api/v1/…` paths are legacy aliases of the unprefixed paths. They are the same operations and are not part of the published contract, so this documentation shows only the `/v1` form. New code should use it.

They sit on the host root, not under `/v1`.

**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. Calling `https://api.testnet.nexus.xyz/v1/tickers` means signing `/tickers`. If you are still calling a legacy alias such as `https://api.testnet.nexus.xyz/api/v1/tickers`, that prefix is part of the path the service sees, so you sign `/api/v1/tickers`. See [Authentication](/api-reference/guides/authentication.md).

## 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`](https://github.com/nexus-xyz/nexus-exchange-api), with releases on [GitHub Releases](https://github.com/nexus-xyz/nexus-exchange-api/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](/api-reference/guides/sdks.md) lists each one with its repository and install line. A [Postman collection](https://github.com/nexus-xyz/nexus/tree/main/product/docs/gitbook/api-reference/postman/nexus-exchange.postman_collection.json) generated from the contract signs HMAC requests for you; import it with the [testnet](https://github.com/nexus-xyz/nexus/tree/main/product/docs/gitbook/api-reference/postman/testnet.postman_environment.json) or [mainnet](https://github.com/nexus-xyz/nexus/tree/main/product/docs/gitbook/api-reference/postman/mainnet.postman_environment.json) environment. [Portfolio & Account State](/api-reference/guides/portfolio.md) 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](/api-reference/guides/rate-limits.md) 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](/api-reference/guides/networks.md), [APIs & Rates](https://docs.nexus.xyz/exchange/apis-and-rates), and the [Quickstart](https://docs.nexus.xyz/exchange/trading/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](https://docs.nexus.xyz/exchange/trading/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.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.nexus.xyz/api-reference/readme.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.