Get Started

An eight-step walkthrough from a cold start to an open position on the Nexus Exchange. You sign in with your wallet, mint an HMAC API key, sign requests, fund the account, browse markets, place an order, cancel or amend it, and monitor positions.

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

Before you start

• You need an Ethereum wallet to sign the login message. Nothing else is required to begin. No wallet yet? Get a wallet and a signature walks through it from a terminal or from MetaMask.
• Base URL. Examples below use the public testnet host. Unprefixed paths go under the /v1 transport base, https://api.testnet.nexus.xyz/v1, and /api/v1 paths go on the host root, so a full URL reads https://api.testnet.nexus.xyz/api/v1/…. Substitute the base for the deployment you are calling. Paths are shown with the /api/v1 prefix where a versioned route exists. The unprefixed form on the /v1 base reaches the same operation and is the one the official clients are moving to. See 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 deployments. The Exchange app is deployed twice from one codebase. The testnet deployment is live and funds accounts from a synthetic-credit faucet. The mainnet real-funds deployment will be funded by bridging USDX from Ethereum Mainnet. It is not live yet: its host, api.nexus.xyz, does not resolve. Step 4 below differs between the two, and 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 baseline, and every step has a cURL example. 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 you follow the cURL example instead. The interactive docs did the same, falling back to cURL with a note.

Machine-readable entry points

An agent can start from these without reading this page:

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

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, and releases are tracked on GitHub Releases.

---

Authentication

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

Get a wallet and a signature

Step 1 needs two things: a wallet, and that wallet's signature over the fixed message Sign in to Nexus Exchange. If you already have both, skip to section 1 (Sign in) below. Otherwise pick one path. Testnet runs on play funds, so a fresh wallet made just for this is the safest choice.

From a terminal, with Foundry's cast

1. Install Foundry, which ships cast:

   curl -L https://foundry.paradigm.xyz | bash
   foundryup

2. Create a wallet. cast prints an address and a private key. Keep the key secret, and use a throwaway key here: the export lands in your shell history, and --private-key in the next step is visible to other local users in ps.

   cast wallet new
   export NEXUS_PRIVATE_KEY=0x<private-key-from-the-output>

   Reusing a wallet that holds real funds? Store it encrypted with cast wallet import nexus --interactive and sign with --account nexus instead of --private-key.
3. Sign the login message. cast wallet sign produces an EIP-191 personal_sign signature by default, which is what the API expects. The message must match exactly, with no trailing newline or extra spaces.

   SIGNATURE=$(cast wallet sign --private-key "$NEXUS_PRIVATE_KEY" "Sign in to Nexus Exchange")

4. Send it to the API and keep the session token (jq reads the JSON reply):

   TOKEN=$(curl -s -X POST 'https://api.testnet.nexus.xyz/v1/auth/login' \
     -H 'Content-Type: application/json' \
     -d "{\"message\": \"Sign in to Nexus Exchange\", \"signature\": \"$SIGNATURE\"}" \
     | jq -r .token)

5. Create an API key with that token. The secret in the reply is shown once, so save it now.

   curl -X POST 'https://api.testnet.nexus.xyz/v1/keys' \
     -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"label": "my first key"}'

Using the Exchange CLI instead of curl? Steps 1 and 2 are all you need. With NEXUS_PRIVATE_KEY exported, nexus auth login signs the message for you, and nexus keys create mints the key.

From MetaMask

The quickest path skips curl entirely: open nexus.xyz/api-keys, connect MetaMask, and create a key there. MetaMask signs once, and the page shows the key's private key one time. That page makes an agent key, which signs requests differently from the HMAC key below; see Agents.

To get the login signature yourself and follow steps 1 to 3 with curl:

1. Install MetaMask and create a wallet, or use one you already have.
2. Open any web page in the same browser, open the developer console, and run:

   const [address] = await ethereum.request({ method: 'eth_requestAccounts' });
   await ethereum.request({
     method: 'personal_sign',
     params: ['Sign in to Nexus Exchange', address],
   });

3. Approve the signature request in MetaMask. The console prints a 0x... signature (132 characters).
4. Export it as SIGNATURE, then run steps 4 and 5 of the terminal path above (login, then create a key).

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". The server recovers your wallet address from the signature.

Notes

• Session token expires in 24 hours.
• You only need the session to create and manage API keys, not to trade.

cURL

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

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::Testnet));

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.

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)

TypeScript

Not available in TypeScript yet. Use the cURL example.

CLI

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

Request body

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

Response

{
  "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, so save it immediately.

Notes

• You cannot retrieve the secret after this response.
• Keys inherit your account's tier. The X-RateLimit-* response headers report the per-tier rate limits.

cURL

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

Rust

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

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

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

Python

Not available in Python yet. Use the cURL example.

TypeScript

Not available in TypeScript yet. Use the cURL example.

CLI

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

Request body

{
  "label": "my-bot"
}

Response

{
  "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 /v1 transport prefix, which is stripped before your signature is verified. Calling …/v1/markets means signing /markets; calling …/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.

cURL

# 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://api.testnet.nexus.xyz/v1/markets' \
  -H "X-API-Key: nx_7f3a1b..." \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE"

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::Testnet).api_key(
    std::env::var("NEXUS_API_KEY")?,
    std::env::var("NEXUS_API_SECRET")?,
));

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

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")

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.Testnet,
  apiKey: process.env.NEXUS_API_KEY,
  apiSecret: process.env.NEXUS_API_SECRET,
});

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

CLI

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

Response

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

In the interactive docs this step has a live "Try it" button against GET /markets.

---

Trading

Steps 4–8 fund the account, put a position on, and monitor it.

4. Fund account

POST /account/credit. HMAC API key required. Testnet only.

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.

The credit faucet exists only on testnet. On the mainnet real-funds deployment this endpoint returns 403 and funding is bridge-only. See the mainnet variant below.

Notes

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

cURL

curl -X POST 'https://api.testnet.nexus.xyz/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"}'

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);

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)

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);

CLI

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

Request body

{
  "amount": "500"
}

Response

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

Step 4 on mainnet: fund with real collateral

On the mainnet real-funds deployment (planned, not live yet), a real deposit replaces step 4. The testnet play deployment has a synthetic-credit faucet, and the mainnet real-funds deployment 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. HMAC API key required.

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. The mode you get is a property of the deployment, not of your request, and no parameter 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, and the same client code funds itself on either deployment.

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, so read them and 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, it refuses an account that is not enrolled, and the refusal is permanent until the account is enrolled. Do not retry. The gate mirrors POST /account/credit and POST /faucet on purpose, so an account that cannot be funded is not told how to fund.
• The endpoint never fabricates an address 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, and 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, so it works on either deployment. Poll GET /account until balance reflects the funds before trading.
• POST /account/credit is a testnet-only faucet, and 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 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, or a single one by its {tx_hash}:{log_index} id via GET /api/v1/bridge/deposits/{id}. The watcher writes that read model, and the endpoints only read it.
• On-chain transfers are irreversible. Send only the asset the instruction names, from a wallet you control.
• The round trip is: fund here, trade (next steps), then withdraw. GET /withdrawals lists your records and POST /withdrawals initiates one. 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.

cURL

# 1) Ask the venue how this deployment accepts collateral.
#    Branch on .mode — "onchain" or "testnet-faucet". Do not assume either shape.
curl 'https://api.testnet.nexus.xyz/v1/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": "ethereum-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://api.testnet.nexus.xyz/v1/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://api.testnet.nexus.xyz/api/v1/bridge/deposits' \
  -H 'X-API-Key: ...' -H 'X-Timestamp: ...' -H 'X-Signature: ...'

Rust

Not available in Rust yet. Use the cURL example. The high-level client wrapper for the bridge step is still in progress.

Python

Not available in Python yet. Use the cURL example.

TypeScript

Not available in TypeScript yet. Use the cURL example.

CLI

Not available in the CLI yet. Use the cURL example.

Request body

None. GET /account/deposit-target takes no parameters and no body.

Response (onchain mode, the contract's example for DepositTarget)

{
  "mode": "onchain",
  "account": "0x742d35cc6634c0532925a3b844bc9e7595f0beb0",
  "asset": "USDX",
  "min_amount": "10",
  "onchain": {
    "chain": "ethereum-mainnet",
    "asset": "USDX",
    "address": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984",
    "token_address": "0xf92b58d2225a73b45ded3bc2290ac1a2077c1cf2",
    "min_amount": "10",
    "instructions": "Approve USDX spend for the deposit contract, then call depositTo(token, amount, beneficiary) with token set to `onchain.token_address`, amount in USDX base units, and beneficiary set to `account`. Only USDX is accepted; other tokens are rejected on-chain. Funds credit to the exchange account within 30s of on-chain confirmation."
  },
  "confirm": {
    "method": "GET",
    "path": "/account",
    "poll_field": "balance",
    "note": "Poll until balance reflects the deposit (SPEC target: within 30s of on-chain confirmation)."
  }
}

5. Browse markets

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

List available perpetual futures markets and check current prices.

cURL

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

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

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
);

Python

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

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

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);

CLI

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

Response

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

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 for the current set.

On the mainnet deployment the market set 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.

Price and size precision

Round before you submit. Every market declares three quantisation rules, and the venue rejects an order that misses them rather than rounding it 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, because 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 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 the order is then rejected 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 the best available price.
• Batch multiple orders in a single POST /orders/batch call. The venue processes them in sequence, and the results keep the request order.

cURL

curl -X POST 'https://api.testnet.nexus.xyz/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
  }'

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);

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)

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);

CLI

# 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

Request body

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

Response

{
  "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.

These are three separate operations:

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 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 after you read it. 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.

cURL

# Amend a resting order's price — note the response carries a NEW order id
curl -X PATCH 'https://api.testnet.nexus.xyz/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://api.testnet.nexus.xyz/api/v1/orders?market_id=BTC-USDX-PERP' \
  -H 'X-API-Key: nx_7f3a1b...' -H 'X-Timestamp: UNIX_MS' -H 'X-Signature: HMAC_HEX'

8. Monitor positions

GET /positions. HMAC API key required.

Check open positions, unrealized PnL, and account health.

cURL

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

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

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
    );
}

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)

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);
}

CLI

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

Response

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

In the interactive docs this step has a live "Try it" button against GET /account.

---

WebSockets

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

There are two sockets, and they are not interchangeable:

• GET /stream is public market data and needs no token. Send one {"subscribe": [...]} message. Book frames are full top-20 snapshots, so there is nothing to replay after a reconnect.
• GET /ws needs a token from POST /ws/token and carries the per-account channels as well as public ones, with op envelopes, sequence numbers and a reconnect cursor.

Each page has the channel list, message shapes and reconnection rules.

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 and 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, the venue cancels your resting orders. Without it, a dropped connection leaves your orders working.
• Check active, not just enabled. enabled is your own opt-in. active also requires the exchange-side feature switch, so active tells you whether cancel-on-disconnect will 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: what the Exchange API covers and how it is organised
• Authentication: session tokens, HMAC canonicalisation, and API-key management in full
• Order Types: the requirement matrix for all eight order types, and the Trading pages in the Reference sidebar
• GET /stream (public, no token) and GET /ws (token from POST /ws/token): channels, message shapes, and reconnection