# Nexus

> The Nexus Exchange is a perpetual futures exchange built for programmatic trading. It lists crypto perpetual futures on one cross-margined dollar account, and it is API-first: everything the terminal does is a REST or WebSocket call, with official SDKs, a CLI and an MCP server. Public testnet: not live, all activity is simulated with play funds (test USDX) that have no real-world value, not a regulated venue, not an offer or solicitation.

This file is [llms.txt](https://nexus.xyz/llms.txt) followed by every root page in full, so one fetch is enough to trade.

## When to use Nexus

Reach for Nexus when the task is programmatic trading of crypto perpetual futures, or market data, on a venue an agent can drive end to end without a browser.

- **Trade on testnet from code.** Follow [onboarding.md](https://nexus.xyz/onboarding.md): wallet sign-in, API key, play funds, first order. You can do it on your own; none of it touches real money.
- **Read order books, trades, candles and funding.** Public market data needs no credential: `GET https://api.testnet.nexus.xyz/v1/markets/summary`.
- **Test a strategy against a real matching engine.** Testnet runs the same engine on play funds.

Nexus is the wrong tool for spot trading and for anything outside the listed perpetuals, and it is not a price oracle of record.
Mainnet moves real money. Never trade there on your own initiative: hand it back to the person you work for, who funds their own account and approves each order. Never report a testnet fill to anyone as an executed trade.

## Start here

- [Onboarding](https://nexus.xyz/onboarding.md): from nothing to a placed order on testnet, one request per step.
- [Pricing](https://nexus.xyz/pricing.md): trading fees, what is free, and where the live schedule is.
- [Trade](https://nexus.xyz/trade.md): the terminal, and the API call behind each part of it.
- [Map](https://nexus.xyz/sitemap.md): every Nexus domain and every page, with the API specs.

## API

- **Testnet** (play funds): REST `https://api.testnet.nexus.xyz/v1`, market-data WebSocket `wss://api.testnet.nexus.xyz/v1/stream`, account WebSocket `wss://api.testnet.nexus.xyz/v1/ws`. Live today.
- **Mainnet** (real funds): not live yet, so there is no mainnet endpoint to call. Do not guess one.
- [OpenAPI spec](https://nexus.xyz/openapi.json): the REST and WebSocket contract, OpenAPI 3.1, version 0.9.133. Its `x-nexus-networks` block is the authoritative network-to-host map. Versioned releases live in [nexus-exchange-api](https://github.com/nexus-xyz/nexus-exchange-api).
- The version a network actually runs is `GET /metadata` on its REST base. It can trail the spec above, so an operation the spec lists may not answer yet.
- [API catalog](https://nexus.xyz/.well-known/api-catalog): the same pointers as an RFC 9727 linkset.

## Clients

All open source under [nexus-xyz](https://github.com/nexus-xyz), pinned to the OpenAPI spec, and testnet by default. [SDKs & Tools](https://docs.nexus.xyz/api-reference/guides/sdks) has the detail.

- [TypeScript SDK](https://github.com/nexus-xyz/nexus-exchange-ts): `npm install @nexus-xyz/exchange-ts`. Web, Node and edge apps, and agents with a Node shell. Experimental.
- [Rust SDK](https://github.com/nexus-xyz/nexus-exchange-rs): `cargo add nexus-exchange`. Latency-sensitive clients and market making, REST and WebSocket. In production use by Nexus's own market makers. [API reference](https://docs.rs/nexus-exchange).
- [Python SDK](https://github.com/nexus-xyz/nexus-exchange-py): `pip install nexus-exchange`. Research, backtesting and scripting. Experimental, a subset of the surface.
- [Go SDK](https://github.com/nexus-xyz/nexus-exchange-go): `go get github.com/nexus-xyz/nexus-exchange-go@latest`. Services and trading infrastructure in Go. Experimental. [API reference](https://pkg.go.dev/github.com/nexus-xyz/nexus-exchange-go).
- [CLI](https://github.com/nexus-xyz/nexus-exchange-cli): `curl https://cli.nexus.xyz | sh`. People at a terminal and shell scripts; a thin layer over the Rust SDK. Released.
- [MCP server](https://github.com/nexus-xyz/nexus-exchange-mcp): `claude mcp add nexus-exchange -- npx -y @nexus-xyz/exchange-mcp`. Chat clients and agents that call tools; runs locally over stdio, so keys stay on your machine. Released; market-data tools need no key.
- [Agent skills](https://github.com/nexus-xyz/nexus-exchange-skills): `/plugin marketplace add nexus-xyz/nexus-exchange-skills`. Teaching an agent to trade, read portfolio risk and troubleshoot through the CLI or MCP server. Released.

## Docs

- [API reference](https://docs.nexus.xyz/api-reference): authentication, orders, market data, rate limits and errors.
- [Docs llms.txt](https://docs.nexus.xyz/llms.txt): the documentation site's own map for agents. Any docs page also answers as markdown at its URL plus `.md`.
- [Developer hub](https://nexus.xyz/developer): every interface on one page.
- [Status](https://status.nexus.xyz): live service status.
- [Releases](https://nexus.xyz/releases): shipped changes, newest first.

## Optional

- [About](https://nexus.xyz/about): the company behind the Exchange.
- [Support](https://nexus.xyz/support): how to get help.
- [Contact](https://nexus.xyz/contact): support and general enquiry addresses.
- [Brand](https://nexus.xyz/brand): logos and visual identity guidelines.
- [Terms of use](https://nexus.xyz/terms-of-use)
- [Privacy policy](https://nexus.xyz/privacy-policy)
- [Sitemap](https://nexus.xyz/sitemap.xml): every page, each with a markdown version at its path plus `.md`.

## Onboarding: trade on the Nexus testnet

> From nothing to a placed and cancelled order on the public testnet, one HTTP request per step. Play funds only, so an agent can run it without a human approving each step.

### Ground rules

- **Testnet only.** Every path below is relative to `https://api.testnet.nexus.xyz/v1`.
- Mainnet moves real money. Never trade there on your own initiative: hand it back to the person you work for, who funds their own account and approves each order. Never report a testnet fill to anyone as an executed trade.
- **Throwaway credentials.** Create a fresh wallet for the run. It only ever holds play funds. Never ask anyone for their own private key or API secret, and never print a secret.
- **Credentials never cross networks.** A key minted on testnet is refused everywhere else.

### Pick an interface

| You are | Use |
| --- | --- |
| An agent with a Node shell | the TypeScript SDK |
| An agent with any other shell | raw REST, below, or the Python, Go or Rust SDK |
| A chat client that calls tools | the MCP server, after minting a key below |
| A person at a terminal | the CLI |

Install lines are on [llms.txt](https://nexus.xyz/llms.txt) and [SDKs & Tools](https://docs.nexus.xyz/api-reference/guides/sdks).

### Steps

1. **Read market data, no auth.** `GET /markets/summary`, `GET /markets/{market}/ticker`, `GET /markets/{market}/orderbook`. Read the live listing rather than assuming one.
2. **Sign in.** `POST /auth/login` with `{"message":"Sign in to Nexus Exchange","signature":"<EIP-191 personal_sign of that exact message>"}`. Returns a session `token`, valid 24 hours, used only to manage keys.
3. **Mint an API key.** `POST /keys` with `Authorization: Bearer <token>` and `{"label":"my-agent"}`. Returns `key_id` and `secret`. The secret is shown once.
4. **Sign every private request** with `X-API-Key`, `X-Timestamp` (Unix milliseconds, within 30 seconds of server time) and `X-Signature = hex(HMAC-SHA256(secret, timestamp + "\n" + METHOD + "\n" + path + "\n" + query + "\n" + sha256_hex(body)))`. The HMAC key is the secret hex-decoded to bytes, `path` has no `/v1` prefix, `query` has no `?`, and an empty body hashes the empty string. Every `401` looks the same, so check the clock first.
5. **Get play funds.** `POST /faucet` credits a fixed amount of test USDX per wallet, with a cooldown. `POST /account/credit` tops up to 500 test USDX a day per API key. Both are testnet only. Check the balance with `GET /account`.
6. **Place an order.** `POST /orders` with `{"market_id":"ETH-USDX-PERP","side":"Buy","order_type":"Limit","price":"<price>","quantity":"0.01","time_in_force":"PostOnly"}`. Price it within the market's band around the mark from step 1, on its tick.
7. **Read and cancel it.** `GET /orders`, then `DELETE /orders/{id}?market_id=ETH-USDX-PERP`.
8. **Positions.** `GET /positions`. To close one, send the opposite side, the same size and `"reduce_only":true`.

### Limits that bite

- **Tick, lot and price band** are per market. Read them from `GET /markets` or [Trading rules](https://nexus.xyz/trading-rules) and do not round a price or size silently.
- **Rate limits** are weight per second, not requests per second. On a `429`, wait for the time the response gives; do not retry in a loop. See [Rate limits](https://docs.nexus.xyz/api-reference/guides/rate-limits).
- **Retries.** If placing an order errors, check `GET /orders` before retrying: it may have been accepted.
- **Send a User-Agent.** Some default library agents are refused at the edge.

### Long-running bots

Register a trade-only agent key with the wallet (`POST /agents/register`, EIP-712). It can trade but not withdraw, and needs no session token. The domain fields per network are in the spec's `x-nexus-networks`; see [Agent keys](https://docs.nexus.xyz/api-reference/guides/agent-keys).

### More

- [Get started](https://docs.nexus.xyz/api-reference/guides/get-started): the same flow with examples in cURL, Rust, Python, TypeScript and the CLI.
- [Authentication](https://docs.nexus.xyz/api-reference/guides/authentication) and [Errors](https://docs.nexus.xyz/api-reference/guides/errors).
- [Runnable examples](https://github.com/nexus-xyz/nexus-exchange-examples).
- [OpenAPI spec](https://nexus.xyz/openapi.json).

## Pricing

> What trading on the Nexus Exchange costs. Fees are charged on filled notional; makers earn a rebate and takers pay a fee.

### Trading fees, base tier

| Market | Maker | Taker |
| --- | --- | --- |
| `BTC-USDX-PERP` | 2 bps rebate | 5 bps |
| `ETH-USDX-PERP` | 2 bps rebate | 5 bps |
| `SOL-USDX-PERP` | 2 bps rebate | 5 bps |

1 bps is 0.01% of filled notional. A maker order adds liquidity (it rests on the book); a taker order removes it. Post-only orders are always makers.

These are the venue's published base tier. Two live sources are authoritative over this page:

- `GET https://api.testnet.nexus.xyz/v1/markets`: each market's `maker_rebate_bps` (negative means a rebate) and `taker_fee_bps`. No key needed.
- `GET /account/fees` (signed): the schedule in effect for your account, including any tier or discount.

Per-market detail: [Market specifications](https://docs.nexus.xyz/trading/trading/perpetuals/market-specifications) and [Trading rules](https://nexus.xyz/trading-rules).

### What costs nothing

- Public market data, over REST and WebSocket, with no key.
- Creating API keys and agent keys.
- The official SDKs, CLI and MCP server: all open source.
- Testnet play funds, from the faucet.

### Rate limits

Every key has a budget in weight per second, set by its tier. The tiers and their ceilings are in [Rate limits](https://docs.nexus.xyz/api-reference/guides/rate-limits); `GET /account/rate-limit` reports your own.

### Testnet

Public testnet: not live, all activity is simulated with play funds (test USDX) that have no real-world value, not a regulated venue, not an offer or solicitation. Fees on testnet are charged in test USDX.

## Trade

> The terminal at https://nexus.xyz/trade is the browser client of the Nexus Exchange: markets, chart, order book, recent trades, order entry, and positions, orders and fills. It is one client of the API, so an agent gets more from the API than from the page.

### The API call behind each part of the terminal

Paths are relative to `https://api.testnet.nexus.xyz/v1`.

| In the terminal | In the API |
| --- | --- |
| Market list and stats | `GET /markets/summary` |
| Price and mark | `GET /markets/{market}/ticker` |
| Order book | `GET /markets/{market}/orderbook` |
| Live updates | WebSocket `wss://api.testnet.nexus.xyz/v1/stream` |
| Connect wallet | `POST /auth/login`, then `POST /keys` or `POST /agents/register` |
| Order entry | `POST /orders` |
| Open orders, cancel | `GET /orders`, `DELETE /orders/{id}?market_id=...` |
| Positions | `GET /positions` |
| Balance and margin | `GET /account` |

Markets: [`BTC-USDX-PERP`](https://nexus.xyz/trade/BTC-USDX-PERP), [`ETH-USDX-PERP`](https://nexus.xyz/trade/ETH-USDX-PERP), [`SOL-USDX-PERP`](https://nexus.xyz/trade/SOL-USDX-PERP). Each has its own page in the terminal.

To trade from code, follow [onboarding.md](https://nexus.xyz/onboarding.md). Fees are on [pricing.md](https://nexus.xyz/pricing.md).

Public testnet: not live, all activity is simulated with play funds (test USDX) that have no real-world value, not a regulated venue, not an offer or solicitation.

## Map of Nexus

> Every Nexus domain, every page on nexus.xyz, and where the API specs live. nexus.xyz is the entry point; everything else is linked from here.

### Domains

| Domain | What it is | Start with |
| --- | --- | --- |
| nexus.xyz | The site and the trading terminal | [llms.txt](https://nexus.xyz/llms.txt), [openapi.json](https://nexus.xyz/openapi.json) |
| api.testnet.nexus.xyz | Exchange API, public testnet, play funds | `https://api.testnet.nexus.xyz/v1/metadata` |
| docs.nexus.xyz | Developer and trading docs | [docs llms.txt](https://docs.nexus.xyz/llms.txt) |
| status.nexus.xyz | Service status | [status](https://status.nexus.xyz) |
| cli.nexus.xyz | The CLI installer script | `curl https://cli.nexus.xyz \| sh` |
| blog.nexus.xyz | Company blog | [blog](https://blog.nexus.xyz) |
| github.com/nexus-xyz | The API contract and every official client | [nexus-exchange-api](https://github.com/nexus-xyz/nexus-exchange-api) |
| exchange.nexus.xyz | Retired host. Browser visits redirect to nexus.xyz/trade | Use api.testnet.nexus.xyz instead |

### API specs

- [OpenAPI spec](https://nexus.xyz/openapi.json): the REST and WebSocket contract, OpenAPI 3.1, version 0.9.133. Its `x-nexus-networks` block is the authoritative network-to-host map. Versioned releases live in [nexus-exchange-api](https://github.com/nexus-xyz/nexus-exchange-api).
- The version a network actually runs is `GET /metadata` on its REST base. It can trail the spec above, so an operation the spec lists may not answer yet.
- [API catalog](https://nexus.xyz/.well-known/api-catalog): the same pointers as an RFC 9727 linkset.
- **Testnet** (play funds): REST `https://api.testnet.nexus.xyz/v1`, market-data WebSocket `wss://api.testnet.nexus.xyz/v1/stream`, account WebSocket `wss://api.testnet.nexus.xyz/v1/ws`. Live today.
- **Mainnet** (real funds): not live yet, so there is no mainnet endpoint to call. Do not guess one.

### Files for agents on nexus.xyz

- [llms.txt](https://nexus.xyz/llms.txt) and [llms-full.txt](https://nexus.xyz/llms-full.txt)
- [onboarding.md](https://nexus.xyz/onboarding.md), [pricing.md](https://nexus.xyz/pricing.md), [trade.md](https://nexus.xyz/trade.md) and this file
- [openapi.json](https://nexus.xyz/openapi.json), [sitemap.xml](https://nexus.xyz/sitemap.xml), [robots.txt](https://nexus.xyz/robots.txt) and [api-catalog](https://nexus.xyz/.well-known/api-catalog)

### Pages on nexus.xyz

Each page also answers as markdown at its path plus `.md`, or to `Accept: text/markdown`.

- [/](https://nexus.xyz/): Home: what the Exchange is and who it is for.
- [/trade](https://nexus.xyz/trade): The trading terminal: markets, chart, order book, order entry and positions.
- [/developer](https://nexus.xyz/developer): Developer hub: every way to trade from code, with install lines.
- [/seasons](https://nexus.xyz/seasons): Trading seasons: points earned by trading, and each season's standings.
- [/data](https://nexus.xyz/data): Public data dashboard: volume and activity across the Exchange.
- [/trading-rules](https://nexus.xyz/trading-rules): Per-market trading rules: tick and lot size, order limits, margin, fees and funding, live from the venue.
- [/releases](https://nexus.xyz/releases): Shipped changes, newest first.
- [/brand](https://nexus.xyz/brand): Logos and visual identity guidelines.
- [/about](https://nexus.xyz/about): The company behind the Exchange, its current stage and how it sets priorities.
- [/contact](https://nexus.xyz/contact): Support and general enquiry addresses, and the registered address.
- [/support](https://nexus.xyz/support): How to get help with an account, access or trading.
- [/about/legal](https://nexus.xyz/about/legal): Every legal document in one place.
- [/terms-of-use](https://nexus.xyz/terms-of-use): Terms of use.
- [/privacy-policy](https://nexus.xyz/privacy-policy): Privacy policy.
- [/cookie-policy](https://nexus.xyz/cookie-policy): Cookie policy.
- [/data-processors](https://nexus.xyz/data-processors): The third parties that process data for Nexus.
- [/trade/BTC-USDX-PERP](https://nexus.xyz/trade/BTC-USDX-PERP): the BTC-USDX-PERP market in the terminal.
- [/trade/ETH-USDX-PERP](https://nexus.xyz/trade/ETH-USDX-PERP): the ETH-USDX-PERP market in the terminal.
- [/trade/SOL-USDX-PERP](https://nexus.xyz/trade/SOL-USDX-PERP): the SOL-USDX-PERP market in the terminal.