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 for why the contract's own servers override is not usable directly.
• 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:

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; releases are tracked on GitHub 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.

cURL

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"
  }'

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.

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

cURL

curl -X POST 'https://exchange.nexus.xyz/api/exchange/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::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);

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

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://exchange.nexus.xyz/api/exchange/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::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());

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.Stable,
  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–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.

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.

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.

cURL

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"}'

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

Mainnet surface variant — step 4: Fund via bridge

On the mainnet real-funds surface (mainnet: 2026-05-20), step 4 is replaced by a bridge deposit. Funding differs fundamentally per surface: the testnet play surface has a synthetic-credit faucet; the mainnet real-funds surface will be bridge-only.

POST /bridge/deposit-addresses — HMAC API key required.

Real funds: there is no synthetic credit on mainnet. Get your per-account deposit address, bridge USDX from Ethereum Mainnet to it, and your exchange account is credited once the deposit confirms.

Notes

• POST /account/credit is testnet-only — it returns 403 on mainnet; the bridge is the sole funding path.
• Idempotent per (account, chain): repeated calls return the same address.
• GET /bridge/assets lists depositable assets per chain with minimum amounts, required confirmations, and fees — check it before sending.
• Track crediting with GET /bridge/deposits (or /bridge/deposits/{id}): status moves to credited once required confirmations are reached.
• On-chain transfers are irreversible — send only supported assets to this address, from a wallet you control.
• Round trip: fund here → trade (next steps) → withdrawals: GET /withdrawals lists your records; withdrawal initiation is not yet exposed through the public API.

cURL

# 1) Get (or create) your deposit address on Ethereum Mainnet
curl -X POST 'https://exchange.nexus.xyz/api/exchange/api/v1/bridge/deposit-addresses' \
  -H 'X-API-Key: nx_7f3a1b...' \
  -H 'X-Timestamp: UNIX_MS' \
  -H 'X-Signature: HMAC_HEX' \
  -H 'Content-Type: application/json' \
  -d '{"chain": "ethereum"}'

# 2) Send USDX to the returned address (from your own wallet), then track it:
curl 'https://exchange.nexus.xyz/api/exchange/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 white-glove client wrap 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

{
  "chain": "ethereum"
}

Response

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

cURL

# 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: ...'

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

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

cURL

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
  }'

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.

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.

cURL

# 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'

8. Monitor positions

GET /positions — HMAC API key required.

Check open positions, unrealized PnL, and account health.

cURL

# 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: ...'

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.

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 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 — 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 and the WebSocket pages in the Reference sidebar — token minting, channels, message envelopes, and reconnection