> 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/guides/get-started.md).

# Get Started

A seven-step walkthrough from a cold start to an open position on the Nexus Exchange: sign in with your wallet, mint an HMAC API key, sign requests, fund the account, browse markets, place an order, and monitor positions.

Every step is shown in five clients — cURL, Rust, Python, TypeScript, and the Exchange CLI. Pick a tab per step.

This page began as the **Getting Started** tab of the interactive API docs the Exchange app once served at `/api-docs`. That route no longer resolves — this page is now the guide.

## Before you start

* **You need an Ethereum wallet** to sign the login message. Nothing else is required to begin.
* **Base URL.** The API is served at the Exchange deployment's origin plus `/api/exchange` — the gateway. Examples below use `https://exchange.nexus.xyz/api/exchange`. Running locally, the base is `http://localhost:9090`. Substitute the base for the deployment you are actually calling. Paths are shown with the `/api/v1` prefix where a versioned route exists, since that is the canonical surface — so a full URL reads `https://exchange.nexus.xyz/api/exchange/api/v1/…`. See [Base URLs](/api-reference/readme.md#base-urls) for the other bases the contract declares, and for how the `servers` override on the `/api/v1` paths resolves.
* **Authentication.** Two schemes: a **session token** (Bearer) used only to create and manage API keys, and **HMAC-SHA256** API-key signing used for everything else, including all trading.
* **Two surfaces.** The Exchange app is deployed twice from one codebase: a **testnet** surface, which is live and funds accounts from a synthetic-credit faucet, and a **mainnet** real-funds surface, which will be funded by bridging USDX from Ethereum Mainnet. Mainnet is **2026-05-20**. Step 4 below differs between the two — both variants are documented.
* **Placeholders.** Values such as `0xSIGNATURE_HEX`, `nx_7f3a1b...`, `sess_abc123...`, and `0x<wallet-private-key>` are placeholders. Substitute your own; never commit a secret.

### Language coverage

cURL is the canonical, always-populated baseline. The four SDK/CLI clients do not yet cover every step. Where a client has no example for a step, the tab says so and the cURL example above it is the one to follow — the interactive docs behave the same way, falling back to cURL with a note.

### Machine-readable entry points

Everything an agent needs in order to start without reading this page:

* `llms.txt` — <https://exchange.nexus.xyz/llms.txt>
* `openapi.json` — the OpenAPI contract, at `https://exchange.nexus.xyz/api/exchange/openapi.json`
* `/metadata` — the Exchange app's machine-readable metadata route
* **MCP server** — published to npm, so adding it is one line. It runs locally over stdio, which means your API key stays on your machine:

```bash
claude mcp add nexus-exchange -- npx -y @nexus-xyz/exchange-mcp
```

Its public market-data and demo tools need no credentials, so the command is useful before you have a key. A hosted MCP endpoint is planned; its DNS is not live yet, so there is no remote URL to add today.

The OpenAPI spec and changelog are versioned at [nexus-xyz/nexus-exchange-api](https://github.com/nexus-xyz/nexus-exchange-api); releases are tracked on [GitHub Releases](https://github.com/nexus-xyz/nexus-exchange-api/releases).

***

## Authentication

Steps 1–3 get you from a wallet to a signed request.

## 1. Sign in

`POST /auth/login` — no authentication required.

Authenticate with an EIP-191 personal signature. The message to sign is always the fixed string “Sign in to Nexus Exchange” — your wallet address is recovered from the signature.

**Notes**

* Session token expires in 24 hours.
* You only need the session to create and manage API keys — not for trading.

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST 'https://exchange.nexus.xyz/api/exchange/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Sign in to Nexus Exchange",
    "signature": "0xSIGNATURE_HEX"
  }'
```

{% endtab %}

{% tab title="Rust" %}

```rust
use nexus_exchange::{Client, Config, EthSigner, Network};

// EIP-191 personal_sign of the fixed login message. The signer
// holds your key only to sign — nothing is written to disk.
let signer = EthSigner::from_hex("0x<wallet-private-key>")?;
let client = Client::new(Config::new(Network::Stable));

let session = client.sign_in(&signer).await?;
println!("signed in as {}", session.address);
// session.token is a SecretString — hand it to
// Config::session_token to authenticate the /keys endpoints.
```

{% endtab %}

{% tab title="Python" %}

```python
from nexus_exchange import Client, EthSigner

signer = EthSigner.from_hex("0x<wallet-private-key>")

with Client() as client:
    session = client.sign_in(signer)  # EIP-191 personal_sign
    print(session.address, session.token)
```

{% endtab %}

{% tab title="TypeScript" %}
Not available in TypeScript yet — use the cURL example.
{% endtab %}

{% tab title="CLI" %}

```bash
export NEXUS_PRIVATE_KEY=0x<your-evm-key>
nexus auth login   # signs EIP-191, stores the session token (mode 0600)
```

{% endtab %}
{% endtabs %}

**Request body**

```json
{
  "message": "Sign in to Nexus Exchange",
  "signature": "0xSIGNATURE_HEX"
}
```

**Response**

```json
{
  "token": "sess_abc123...",
  "address": "0xYOUR_WALLET_ADDRESS"
}
```

## 2. Create API key

`POST /keys` — **Session token required.**

Use the session token to create an HMAC key pair. The secret is shown once — save it immediately.

**Notes**

* You cannot retrieve the secret after this response.
* Keys inherit your account’s tier; per-tier rate limits are reported in the `X-RateLimit-*` response headers.

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST 'https://exchange.nexus.xyz/api/exchange/keys' \
  -H 'Authorization: Bearer sess_abc123...' \
  -H 'Content-Type: application/json' \
  -d '{"label": "my-bot"}'
```

{% endtab %}

{% tab title="Rust" %}

```rust
use nexus_exchange::{Client, Config, Network};

// /keys endpoints authenticate with the session token from step 1.
let client =
    Client::new(Config::new(Network::Stable).session_token("sess_..."));

let key = client.create_api_key().await?;
// key.secret is returned once — persist it immediately.
println!("key_id: {}", key.key_id);
```

{% endtab %}

{% tab title="Python" %}
Not available in Python yet — use the cURL example.
{% endtab %}

{% tab title="TypeScript" %}
Not available in TypeScript yet — use the cURL example.
{% endtab %}

{% tab title="CLI" %}

```bash
nexus keys create   # secret is shown ONCE — store it now
```

{% endtab %}
{% endtabs %}

**Request body**

```json
{
  "label": "my-bot"
}
```

**Response**

```json
{
  "key_id": "nx_7f3a1b...",
  "secret": "e4d2c8f1...long_hex..."
}
```

## 3. Sign requests

`GET /markets` — **HMAC API key required.**

Every authenticated request needs three headers. Build a canonical string, HMAC-SHA256 it with your secret, and attach the result.

**Required headers**

| Header        | Required | Description                             |
| ------------- | -------- | --------------------------------------- |
| `X-API-Key`   | yes      | Your key ID (`nx_...`)                  |
| `X-Timestamp` | yes      | Current time in ms since epoch          |
| `X-Signature` | yes      | HMAC-SHA256 hex of the canonical string |

**Notes**

* Canonical format: `timestamp\nMETHOD\npath\nquery\nsha256(body)`
* `path` is the path **as written in the contract** — include the `/api/v1` prefix when the route has one, but **not** the `/api/exchange` gateway mount, which is stripped before your signature is verified. Calling `…/api/exchange/markets` means signing `/markets`; calling `…/api/exchange/api/v1/tickers` means signing `/api/v1/tickers`.
* Timestamp must be within ±30 seconds of server time (milliseconds since epoch).
* For GET requests with no body, hash the empty string.

{% tabs %}
{% tab title="cURL" %}

```bash
# Build the HMAC signature
TIMESTAMP=$(python3 -c 'import time; print(int(time.time()*1000))')
BODY_HASH=$(echo -n "" | shasum -a 256 | cut -d' ' -f1)
CANONICAL="$TIMESTAMP\nGET\n/markets\n\n$BODY_HASH"
SIGNATURE=$(echo -ne "$CANONICAL" | \
  openssl dgst -sha256 -mac HMAC -macopt "hexkey:$NEXUS_API_SECRET" -hex | awk '{print $NF}')

curl 'https://exchange.nexus.xyz/api/exchange/markets' \
  -H "X-API-Key: nx_7f3a1b..." \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE"
```

{% endtab %}

{% tab title="Rust" %}

```rust
use nexus_exchange::{Client, Config, Network};

// The SDK builds the canonical string and HMAC-signs every request.
let client = Client::new(Config::new(Network::Stable).api_key(
    std::env::var("NEXUS_API_KEY")?,
    std::env::var("NEXUS_API_SECRET")?,
));

let markets = client.fetch_markets().await?;
println!("{} markets", markets.len());
```

{% endtab %}

{% tab title="Python" %}

```python
import os
from nexus_exchange import Client

# The SDK builds the canonical string and HMAC-signs every request.
client = Client(
    api_key=os.environ["NEXUS_API_KEY"],
    api_secret=os.environ["NEXUS_API_SECRET"],
)

print(len(client.fetch_markets()), "markets")
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
import { Client, Network } from "@nexus-xyz/exchange-ts";

// The SDK builds the canonical string and HMAC-signs every request.
const client = new Client({
  network: Network.Stable,
  apiKey: process.env.NEXUS_API_KEY,
  apiSecret: process.env.NEXUS_API_SECRET,
});

console.log((await client.fetchMarketSummaries()).length, "markets");
```

{% endtab %}

{% tab title="CLI" %}

```bash
nexus setup            # interactive; stores credentials (mode 0600)
# ...or per shell:
export NEXUS_API_KEY=nx_...
export NEXUS_API_SECRET=...
nexus balance          # every request is HMAC-signed for you
```

{% endtab %}
{% endtabs %}

**Response**

```json
[
  { "id": "BTC-USDX-PERP", "base": "BTC", "quote": "USDX", "status": "active" },
  { "id": "ETH-USDX-PERP", "base": "ETH", "quote": "USDX", "status": "active" }
]
```

{% hint style="info" %}
In the interactive docs this step has a live "Try it" button against `GET /markets`.
{% endhint %}

***

## Trading

Steps 4–7 fund the account and put a position on.

## 4. Fund account

`POST /account/credit` — **HMAC API key required.** Testnet surface.

Credit synthetic USDX to start trading. Each API key can claim up to 500 USDX per day — omit `"amount"` to claim the full remaining daily allowance.

{% hint style="warning" %}
The credit faucet is a **testnet** affordance. On the mainnet real-funds surface this endpoint returns `403` and funding is bridge-only — see the mainnet variant below.
{% endhint %}

**Notes**

* Amounts are decimal strings, like all monetary values in the API.
* Returns 429 once the daily allowance is used up; it resets the next UTC day.

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST 'https://exchange.nexus.xyz/api/exchange/api/v1/account/credit' \
  -H 'X-API-Key: nx_7f3a1b...' \
  -H 'X-Timestamp: UNIX_MS' \
  -H 'X-Signature: HMAC_HEX' \
  -H 'Content-Type: application/json' \
  -d '{"amount": "500"}'
```

{% endtab %}

{% tab title="Rust" %}

```rust
use nexus_exchange::types::Decimal;

// `client` is the HMAC-credentialed client from step 3.
// Pass None to claim the full remaining daily allowance.
let credit = client
    .claim_credit(Some("500".parse::<Decimal>()?))
    .await?;
println!("credited {} (today: {})", credit.amount, credit.credited_today);
```

{% endtab %}

{% tab title="Python" %}

```python
# `client` is the HMAC-credentialed client from step 3.
credit = client.claim_credit("500")  # omit the amount for the daily max
print(credit.amount, credit.credited_today)
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
// `client` is the HMAC-credentialed client from step 3.
const credit = await client.claimCredit({ amount: "500" }); // {} = daily max
console.log(credit.amount, credit.credited_today);
```

{% endtab %}

{% tab title="CLI" %}

```bash
nexus account credit --amount 500   # omit --amount for the daily max
```

{% endtab %}
{% endtabs %}

**Request body**

```json
{
  "amount": "500"
}
```

**Response**

```json
{
  "amount": "500",
  "credited_today": "500",
  "daily_limit": "500"
}
```

### Mainnet surface variant — step 4: Fund with real collateral

On the mainnet real-funds surface (mainnet: **2026-05-20**), step 4 is replaced by a real deposit. Funding differs fundamentally per surface: the testnet play surface has a synthetic-credit faucet, and the mainnet real-funds surface has none. You do not have to branch on that yourself — one endpoint answers "how does this deployment accept collateral", and the answer carries the mode.

[`GET /account/deposit-target`](/api-reference/account/fetch-deposit-target.md) — **HMAC API key required.**

Real funds: there is no synthetic credit on mainnet. Ask the venue where to send collateral, send it, then poll until your balance reflects it.

**Do not hardcode the funding method.** The response is a discriminated union on `mode`, and which mode you get is a property of the deployment rather than of your request — there is no parameter that selects one. A deployment with a real deposit contract configured answers `onchain`; every other deployment answers `testnet-faucet` and points at its synthetic-credit endpoints. Branch on `mode`. The same client code then funds itself on either surface, which is the whole point of the endpoint.

**Notes**

* Discovery only. `GET /account/deposit-target` moves no funds and creates no deposit; acting on the returned instruction is a separate, explicit step.
* In `onchain` mode, `onchain.address` is the deposit-contract address and `onchain.chain` is the chain it lives on. Both are deployment configuration — read them, do not hardcode them.
* **`403 EARLY_ACCESS_REQUIRED` means your account cannot be funded here yet.** Where a deployment restricts funding to early-access participants, an account that is not enrolled is refused, and the refusal is **permanent until it is enrolled — do not retry.** The gate deliberately mirrors `POST /account/credit` and `POST /faucet`, so an account that cannot be funded is not told how to fund.
* An address is never fabricated to fill the `onchain` shape. A deployment configured for on-chain deposits whose address is malformed returns `503 DEPOSIT_TARGET_MISCONFIGURED` rather than publishing it, because depositing to a bad address burns the funds. That is an operator misconfiguration, not a transient fault — retrying does not clear it.
* `min_amount` is **advisory, not enforced**. It is the floor that makes a first trade viable; nothing rejects a smaller on-chain deposit.
* `confirm` is identical in both modes and is the portable primitive: poll `GET /account` until `balance` reflects the funds before trading.
* `POST /account/credit` is a **testnet-only** faucet: the credited USDX is synthetic. The contract's own guidance is not to build a funding flow that assumes the operation exists on every network — mainnet has no synthetic credit at all.
* [`GET /api/v1/bridge/assets`](/api-reference/bridge/get-bridge-assets.md) lists the supported chains and, per chain, the depositable assets with their decimals, minimum amount and required confirmations.
* Track a cross-chain deposit with [`GET /api/v1/bridge/deposits`](/api-reference/bridge/list-bridge-deposits.md), or a single one by its `{tx_hash}:{log_index}` id via [`GET /api/v1/bridge/deposits/{id}`](/api-reference/bridge/get-bridge-deposit.md). That read model is written by the watcher; the endpoints only read it.
* On-chain transfers are irreversible — send only the asset the instruction names, from a wallet you control.
* Round trip: fund here → trade (next steps) → withdraw. `GET /withdrawals` lists your records and [`POST /withdrawals`](/api-reference/account/create-withdrawal.md) initiates one — note it is authenticated by an EIP-712 `WithdrawIntent` signed with the wallet's own key, **not** by an API key, so it does not reuse the HMAC credentials above. A bridge withdrawal is a separate operation, [`POST /api/v1/bridge/withdrawals`](/api-reference/bridge/create-bridge-withdrawal.md).

{% tabs %}
{% tab title="cURL" %}

```bash
# 1) Ask the venue how this deployment accepts collateral.
#    Branch on .mode — "onchain" or "testnet-faucet". Do not assume either shape.
curl 'https://exchange.nexus.xyz/api/exchange/account/deposit-target' \
  -H 'X-API-Key: nx_7f3a1b...' \
  -H 'X-Timestamp: UNIX_MS' \
  -H 'X-Signature: HMAC_HEX'

# onchain mode answers with the deposit contract to send to:
#   { "mode": "onchain", "account": "0x742d...", "asset": "USDX", "min_amount": "10",
#     "onchain": { "chain": "nexus-mainnet", "asset": "USDX",
#                  "address": "0x1f98...", "min_amount": "10" },
#     "confirm": { "method": "GET", "path": "/account", "poll_field": "balance" } }

# 2) Send the named asset to onchain.address on onchain.chain from your own wallet.

# 3) Confirm with the instruction's own confirm block — poll until balance moves.
curl 'https://exchange.nexus.xyz/api/exchange/account' \
  -H 'X-API-Key: ...' -H 'X-Timestamp: ...' -H 'X-Signature: ...'

# Optional: the cross-chain deposit record, once the watcher has seen it.
curl 'https://exchange.nexus.xyz/api/exchange/api/v1/bridge/deposits' \
  -H 'X-API-Key: ...' -H 'X-Timestamp: ...' -H 'X-Signature: ...'
```

{% endtab %}

{% tab title="Rust" %}
Not available in Rust yet — use the cURL example. The white-glove client wrap for the bridge step is still in progress.
{% endtab %}

{% tab title="Python" %}
Not available in Python yet — use the cURL example.
{% endtab %}

{% tab title="TypeScript" %}
Not available in TypeScript yet — use the cURL example.
{% endtab %}

{% tab title="CLI" %}
Not available in the CLI yet — use the cURL example.
{% endtab %}
{% endtabs %}

**Request body**

```json
{
  "chain": "ethereum"
}
```

**Response**

```json
{
  "address": "0xDEPOSIT_ADDRESS",
  "chain": "ethereum",
  "accepts": ["USDC", "USDX"],
  "account_id": "0xYOUR_WALLET_ADDRESS",
  "created_at": 1779225381000
}
```

## 5. Browse markets

`GET /markets/{market_id}/ticker` — **HMAC API key required.**

List available perpetual futures markets and check current prices.

{% tabs %}
{% tab title="cURL" %}

```bash
# List markets (4 trading on testnet today; 32 configured)
curl 'https://exchange.nexus.xyz/api/exchange/markets' \
  -H 'X-API-Key: ...' -H 'X-Timestamp: ...' -H 'X-Signature: ...'

# Get a single ticker
curl 'https://exchange.nexus.xyz/api/exchange/api/v1/markets/BTC-USDX-PERP/ticker' \
  -H 'X-API-Key: ...' -H 'X-Timestamp: ...' -H 'X-Signature: ...'
```

{% endtab %}

{% tab title="Rust" %}

```rust
let markets = client.fetch_markets().await?;
println!("{} markets", markets.len());

let ticker = client.fetch_ticker("BTC-USDX-PERP").await?;
println!(
    "{}: last={:?} mark={:?}",
    ticker.symbol, ticker.last, ticker.mark_price
);
```

{% endtab %}

{% tab title="Python" %}

```python
for market in client.fetch_markets():
    print(market.market_id)

ticker = client.fetch_ticker("BTC-USDX-PERP")
print(ticker.last, ticker.mark_price)
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
for (const market of await client.fetchMarketSummaries()) {
  console.log(market.market_id);
}

const ticker = await client.fetchTicker("BTC-USDX-PERP");
console.log(ticker.last, ticker.markPrice);
```

{% endtab %}

{% tab title="CLI" %}

```bash
nexus markets                 # tradable markets and their rules
nexus ticker BTC-USDX-PERP    # ticker for one market
```

{% endtab %}
{% endtabs %}

**Response**

```json
{
  "symbol": "BTC-USDX-PERP",
  "last": 84250.5,
  "bid": 84249.0,
  "ask": 84252.0,
  "volume": 1523.4,
  "change": 2.1
}
```

{% hint style="info" %}
The source comment for this step reads `# List markets (all 32)`. That is the configured-market count, not the live one — the testnet is currently trading **4** markets, so the comment above has been corrected. See [Exchange Testnet](https://docs.nexus.xyz/exchange/exchange-testnet) for the current set.

On the mainnet surface the market-set copy differs: mainnet launches with 3 markets — `BTC-USDX-PERP`, `ETH-USDX-PERP`, `SOL-USDX-PERP` — expanding to 32+. The cURL comment there reads `# List markets (3 at internal launch: BTC, ETH, SOL — expanding to 32+)`.

In the interactive docs this step has a live "Try it" button against `GET /markets/BTC-USDX-PERP/ticker`.
{% endhint %}

### Price and size precision

Round before you submit. Every market declares three quantisation rules, and an order that misses them is rejected rather than rounded for you.

| Field on `GET /markets` | Rule                                             |
| ----------------------- | ------------------------------------------------ |
| `tick_size`             | The limit price must be an exact multiple of it. |
| `lot_size`              | The order size must be an exact multiple of it.  |
| `min_order_size`        | The order size must be at least this.            |

For `BTC-USDX-PERP` those are `0.5`, `0.001` and `0.001`. So a price of `83000.25` is invalid — it is not a multiple of `0.5` — and so is a size of `0.0005`, which is below both the lot and the minimum. `83000.00` and `0.001` are valid.

Read the values per market rather than hardcoding them: they differ by market (`ETH-USDX-PERP` is `0.10` and `0.01`, `SOL-USDX-PERP` is `0.01` and `0.1`) and they are listing-time configuration. [Market Specifications](https://docs.nexus.xyz/exchange/trading/perpetuals/market-specifications) publishes the current table for every listed market.

**Round toward the safe side.** Round a buy price *down* and a sell price *up* to the tick, and floor sizes to the lot grid: rounding a size up can push the order past the margin your equity supports and turn a precision problem into a rejected order for a different reason.

## 6. Place an order

`POST /orders` — **HMAC API key required.**

Submit a limit or market order. The response confirms acceptance.

**Notes**

* Use `"type": "market"` to fill immediately at best available price.
* Batch multiple orders in a single `POST /orders/batch` call — processed sequentially, results preserve request order.

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST 'https://exchange.nexus.xyz/api/exchange/api/v1/orders' \
  -H 'X-API-Key: nx_7f3a1b...' \
  -H 'X-Timestamp: UNIX_MS' \
  -H 'X-Signature: HMAC_HEX' \
  -H 'Content-Type: application/json' \
  -d '{
    "market_id": "BTC-USDX-PERP",
    "side": "buy",
    "type": "limit",
    "size": 0.01,
    "price": 83000.00
  }'
```

{% endtab %}

{% tab title="Rust" %}

```rust
use nexus_exchange::types::{OrderRequest, Side, TimeInForce};

let order = OrderRequest::limit(
    "BTC-USDX-PERP",
    Side::Buy,
    "83000".parse()?,
    "0.01".parse()?,
    TimeInForce::Gtc,
);
let placed = client.create_order(&order).await?;
println!("placed {} — {}", placed.order.id, placed.order.status);
```

{% endtab %}

{% tab title="Python" %}

```python
from decimal import Decimal
from nexus_exchange import OrderRequest

order = OrderRequest.limit(
    "BTC-USDX-PERP", "Buy", Decimal("83000"), Decimal("0.01")
)
placed = client.create_order(order)
print(placed.order.id, placed.order.status)
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
const { order } = await client.placeOrder({
  market_id: "BTC-USDX-PERP",
  side: "Buy",
  order_type: "Limit",
  price: "83000",
  quantity: "0.01",
  time_in_force: "GTC",
});
console.log(order.id, order.status);
```

{% endtab %}

{% tab title="CLI" %}

```bash
# Prompts for confirmation; pass --yes to skip
nexus order place --market BTC-USDX-PERP --side buy --type limit \
  --price 83000 --quantity 0.01 --tif GTC
```

{% endtab %}
{% endtabs %}

**Request body**

```json
{
  "market_id": "BTC-USDX-PERP",
  "side": "buy",
  "type": "limit",
  "size": 0.01,
  "price": 83000.0
}
```

**Response**

```json
{
  "id": "ord_f82a...",
  "status": "open",
  "filled": 0.0,
  "market_id": "BTC-USDX-PERP",
  "side": "buy",
  "type": "limit",
  "size": 0.01,
  "price": 83000.0
}
```

## 7. Cancel or amend

`DELETE /orders/{order_id}` · `DELETE /orders` · `PATCH /orders/{order_id}` — **HMAC API key required.**

Three separate operations, and the distinction matters:

| Operation                   | Effect                                                                        |
| --------------------------- | ----------------------------------------------------------------------------- |
| `DELETE /orders/{order_id}` | Cancels one resting order.                                                    |
| `DELETE /orders`            | Cancels every resting order, or every order on one market with `?market_id=`. |
| `PATCH /orders/{order_id}`  | **Atomic cancel-replace**: changes price and/or size in one call.             |

**Notes**

* **An amend returns a replacement with a fresh id.** The `200` body is the new order; the id you amended no longer exists. Track the id you get back, not the one you sent.
* At least one of `price` or `size` must be supplied on an amend.
* The amend's pre-trade margin check **excludes the reservation still held by the order being replaced**, so it is sized on the margin the replacement actually adds: repricing at the same size needs no additional margin, and shrinking frees margin rather than requiring more.
* Liquidation orders are not amendable.
* A `409` on an amend means the order changed underneath you — it filled or was cancelled between your read and your write.
* **Cancels draw on a separate rate-limit budget from submissions.** Exhausting your order budget never blocks a cancel; a `429` with `bucket: cancel` is the only refusal that means your cancel channel itself is saturated. See [Rate limits](/api-reference/guides/rate-limits.md).

{% tabs %}
{% tab title="cURL" %}

```bash
# Amend a resting order's price — note the response carries a NEW order id
curl -X PATCH 'https://exchange.nexus.xyz/api/exchange/api/v1/orders/ORDER_ID?market_id=BTC-USDX-PERP' \
  -H 'X-API-Key: nx_7f3a1b...' \
  -H 'X-Timestamp: UNIX_MS' \
  -H 'X-Signature: HMAC_HEX' \
  -H 'Content-Type: application/json' \
  -d '{"price": 82500.00}'

# Cancel everything on one market
curl -X DELETE 'https://exchange.nexus.xyz/api/exchange/api/v1/orders?market_id=BTC-USDX-PERP' \
  -H 'X-API-Key: nx_7f3a1b...' -H 'X-Timestamp: UNIX_MS' -H 'X-Signature: HMAC_HEX'
```

{% endtab %}
{% endtabs %}

## 8. Monitor positions

`GET /positions` — **HMAC API key required.**

Check open positions, unrealized PnL, and account health.

{% tabs %}
{% tab title="cURL" %}

```bash
# Open positions
curl 'https://exchange.nexus.xyz/api/exchange/api/v1/positions' \
  -H 'X-API-Key: ...' -H 'X-Timestamp: ...' -H 'X-Signature: ...'

# Account summary
curl 'https://exchange.nexus.xyz/api/exchange/api/v1/account' \
  -H 'X-API-Key: ...' -H 'X-Timestamp: ...' -H 'X-Signature: ...'
```

{% endtab %}

{% tab title="Rust" %}

```rust
let account = client.fetch_balance().await?;
println!("equity {}", account.equity);

for p in client.fetch_positions().await? {
    println!(
        "{} {} size {} | uPnL {}",
        p.market_id, p.side, p.size, p.unrealized_pnl
    );
}
```

{% endtab %}

{% tab title="Python" %}

```python
account = client.fetch_balance()
print(account.equity)

for p in client.fetch_positions():
    print(p.market_id, p.side, p.size, p.unrealized_pnl)
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
const account = await client.getAccount();
console.log(account.equity);

for (const p of await client.getPositions()) {
  console.log(p.market_id, p.side, p.size, p.unrealized_pnl);
}
```

{% endtab %}

{% tab title="CLI" %}

```bash
nexus positions   # open positions with PnL
nexus balance     # balance, collateral, equity, margin
```

{% endtab %}
{% endtabs %}

**Response**

```json
{
  "balance": 10000.0,
  "equity": 10012.5,
  "margin_used": 83.0,
  "margin_ratio": 0.008,
  "positions": 1
}
```

{% hint style="info" %}
In the interactive docs this step has a live "Try it" button against `GET /account`.
{% endhint %}

***

## WebSockets

Polling is fine to get started; a live book or a fill feed should use the stream.

`GET /stream` mints a connection token, and the WebSocket carries channel subscriptions from there. The full model — token minting and lifetime, the channel list, message envelopes, sequence numbers and reconnection — is on [`GET /stream`](/api-reference/websocket/connect-stream.md) and the WebSocket pages in the Reference sidebar.

Two things worth knowing before you build against it:

* **Cancel-on-disconnect is opt-in, per account, and off by default.** Set it with `PUT /account/cancel-on-disconnect`; read it with the `GET`. It is a dead-man's switch: when your last authenticated connection drops and does not reconnect inside the grace window, your resting orders are cancelled. Without it, a dropped connection leaves your orders working.
* **Check `active`, not just `enabled`.** `enabled` is your own opt-in; `active` additionally requires the exchange-side feature switch, so `active` is what tells you cancel-on-disconnect will actually fire. An account can read back `enabled: true` and still not be protected.
* **The stream is not the authority for position state.** Reconcile against `GET /positions` and `GET /account` after any reconnect rather than replaying from where you left off.

## Clients

The snippets above use these packages:

| Client     | Package / crate          |
| ---------- | ------------------------ |
| Rust       | `nexus_exchange`         |
| Python     | `nexus_exchange`         |
| TypeScript | `@nexus-xyz/exchange-ts` |
| CLI        | the `nexus` command      |

The CLI and the language SDKs are distributed outside the Exchange monorepo. The guided walkthrough does not state their repositories, so install instructions are not reproduced here.

## Next steps

* [Overview](/api-reference/readme.md) — what the Exchange API covers and how it is organised
* [Authentication](/api-reference/guides/authentication.md) — session tokens, HMAC canonicalisation, and API-key management in full
* [Order Types](/api-reference/guides/order-types.md) — the requirement matrix for all eight order types, and the Trading pages in the Reference sidebar
* [`GET /stream`](/api-reference/websocket/connect-stream.md) and the WebSocket pages in the Reference sidebar — token minting, channels, message envelopes, and reconnection


---

# 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/guides/get-started.md?ask=<question>&goal=<endgoal>
```

`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.