Quickstart

This walks you from zero to a live order on testnet. You need an Ethereum wallet to sign the login message. All requests go to the testnet gateway:

https://exchange.nexus.xyz/api/exchange

Monetary values are decimal strings throughout the API.

1. Sign in

Authenticate with an EIP-191 personal signature over the fixed string Sign in to Nexus Exchange. Your address is recovered from the signature. The session token is only used to manage API keys — not to trade — and expires in 24 hours.

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"
  }'
# → { "token": "sess_abc123...", "address": "0xYOUR_WALLET_ADDRESS" }

2. Create an API key

Use the session token to mint an HMAC key pair. The secret is shown once — save it immediately. A key is limited both by its own ceiling, recorded when it is created, and by your account's rate-limit tier; whichever binds first applies. GET /account/rate-limit reports the effective figure and costs nothing to poll — see Rate Limits.

The key is bound to the network of the host you create it against — the base URL below is testnet, so this is a testnet key and will not authenticate anywhere else. See Networks for what that means in practice.

curl -X POST 'https://exchange.nexus.xyz/api/exchange/keys' \
  -H 'Authorization: Bearer sess_abc123...' \
  -H 'Content-Type: application/json' \
  -d '{"label": "my-bot"}'
# → { "key_id": "nx_7f3a1b...", "secret": "e4d2c8f1...long_hex..." }

3. Sign requests

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

Header	Value
X-API-Key	your key_id (nx_...)
X-Timestamp	current time in ms since epoch (must be within ±30s of server time)
X-Signature	HMAC-SHA256 hex of the canonical string

Canonical string format (note the literal newlines):

timestamp\nMETHOD\npath\nquery\nsha256(body)

For a GET with no body, hash the empty string.

TIMESTAMP=$(date +%s%3N)
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 -hmac "YOUR_SECRET" | cut -d' ' -f2)

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

4. Fund your account

Credit synthetic USDX from the faucet. Each API key can claim up to 500 USDX per day; omit amount to claim the full remaining daily allowance. Returns 429 once the allowance is used up; it resets the next UTC day.

curl -X POST 'https://exchange.nexus.xyz/api/exchange/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"}'
# → { "amount": "500", "credited_today": "500", "daily_limit": "500" }

5. Browse markets

# All live markets
curl 'https://exchange.nexus.xyz/api/exchange/markets' -H 'X-API-Key: ...' -H 'X-Timestamp: ...' -H 'X-Signature: ...'

# A single ticker
curl 'https://exchange.nexus.xyz/api/exchange/markets/BTC-USDX-PERP/ticker' -H 'X-API-Key: ...' -H 'X-Timestamp: ...' -H 'X-Signature: ...'
# → { "symbol": "BTC-USDX-PERP", "last": "84250.5", "bid": "84249.0", "ask": "84252.0", "volume": "1523.4", "change": "2.1" }

6. Place an order

curl -X POST 'https://exchange.nexus.xyz/api/exchange/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",
    "order_type": "Limit",
    "price": "83000.00",
    "quantity": "0.01",
    "time_in_force": "GTC"
  }'
# → { "id": "ord_f82a...", "status": "open", "filled": "0.0", ... }

Use "order_type": "Market" to fill immediately at the best available price. time_in_force accepts GTC, IOC, or FOK; add "reduce_only": true to only reduce an existing position. Batch multiple orders in one POST /orders/batch call — they are processed sequentially and results preserve request order.

7. Monitor positions

curl 'https://exchange.nexus.xyz/api/exchange/positions' -H 'X-API-Key: ...' -H 'X-Timestamp: ...' -H 'X-Signature: ...'
curl 'https://exchange.nexus.xyz/api/exchange/account'   -H 'X-API-Key: ...' -H 'X-Timestamp: ...' -H 'X-Signature: ...'
# → { "balance": "500.0", "equity": "512.5", "margin_used": "83.0", "margin_ratio": "0.008", "positions": 1 }

Next: the full REST API Reference and WebSocket API Reference.