> 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/exchange/trading/quickstart.md).

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

```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"
  }'
# → { "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.** Keys inherit your account's rate-limit tier.

```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"}'
# → { "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.

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

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

```bash
# 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

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

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


---

# 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/exchange/trading/quickstart.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.