# Nexus Exchange — Agent Quickstart > Verifiable perpetual-futures exchange. This file is written for a > code-execution AI agent. Everything below is a real HTTP call you can make > today with `curl` — no SDK required — and official clients exist for Rust, > Python, TypeScript, the shell, and MCP (see "Clients"). The > machine-readable contract is the OpenAPI 3.1 spec linked under "Discovery". ## Base URL - Production: `https://exchange.nexus.xyz/api/exchange` - Local dev: `http://localhost:9090` All paths below are relative to the base URL. The production gateway HMAC-signs requests on your behalf when you call it through the `/api/exchange/*` proxy; against the indexer directly (local dev) you sign requests yourself (see "Authentication"). ## Discovery The OpenAPI spec is part of the API contract and is served by the API itself, behind the `/api/exchange` proxy. The other discovery documents (this file and the `/.well-known/*` docs) are web/gateway content served at the web root — NOT behind the proxy. - OpenAPI 3.1 spec: `GET /openapi.json` (production: `https://exchange.nexus.xyz/api/exchange/openapi.json`) — the full machine-readable contract - This file: `GET https://exchange.nexus.xyz/llms.txt` - Discovery index: `GET https://exchange.nexus.xyz/.well-known/nexus-exchange` - MCP manifest: `GET https://exchange.nexus.xyz/.well-known/mcp` — hosted MCP server (see "MCP") - OAuth metadata: `GET https://exchange.nexus.xyz/.well-known/oauth-protected-resource` (SCAFFOLD — see "MCP") ## Clients Official clients, all spec-pinned to `nexus-xyz/nexus-exchange-api`: - Rust: `cargo add nexus-exchange` — https://github.com/nexus-xyz/nexus-exchange-rs (full REST + WebSocket; in production use) - Python: `pip install git+https://github.com/nexus-xyz/nexus-exchange-py` (experimental; PyPI publish pending) - TypeScript: `@nexus-xyz/exchange-ts` — https://github.com/nexus-xyz/nexus-exchange-ts (experimental; npm publish pending — build from source) - CLI: `curl https://cli.nexus.xyz | sh` (signed prebuilt binaries) — https://github.com/nexus-xyz/nexus-exchange-cli - MCP: see "MCP" below Auth in one line each: HMAC keys sign every request with `x-api-key` / `x-timestamp` / `x-signature` (scheme under "Authentication"); agent keys are trade-scoped — they sign trading requests only, while key management (`/keys`, `/agents`) needs the wallet's own HMAC key or session bearer. Testnet funding is the synthetic-credit faucet (`POST /account/credit`, step 2 below): up to 500 USDX per key per day. ## MCP A Model Context Protocol server exposes the exchange as agent-callable tools (market data with zero config; trading with HMAC credentials). The hosted server (LIVE) speaks Streamable HTTP: ```sh claude mcp add --transport http nexus https://mcp.exchange.nexus.xyz/mcp ``` - MCP endpoint: `https://mcp.exchange.nexus.xyz/mcp` (Streamable HTTP) - Manifest: `GET https://exchange.nexus.xyz/.well-known/mcp` Or run the same server locally over stdio: ```sh git clone https://github.com/nexus-xyz/nexus-exchange-mcp cd nexus-exchange-mcp && npm install && npm run build claude mcp add nexus-exchange -- node $PWD/dist/index.js ``` Auth (MVP): the hosted server takes your existing Exchange HMAC credential as `X-Nexus-Api-Key` / `X-Nexus-Api-Secret` request headers, captured once at session initialize. With no credential it still serves public market-data tools. OAuth is not yet enabled — the `/.well-known/oauth-protected-resource` document is a forward-looking SCAFFOLD (RFC 9728) for when the server moves to OAuth-minted scoped keys. ## The north-star flow: get key -> deposit -> buy BTC The flow is: (1) authenticate and get an API credential, (2) fund the account with USDX collateral, (3) place an order. Steps marked LIVE work against the deployed exchange today. Steps marked PARTIAL or NOT-BUILT are called out honestly below. ### 0. Read public market data (LIVE, no auth) No credential needed — public, IP-rate-limited reads: ```sh curl https://exchange.nexus.xyz/api/exchange/markets/summary curl https://exchange.nexus.xyz/api/exchange/markets/BTC-USDX-PERP/ticker curl https://exchange.nexus.xyz/api/exchange/markets/BTC-USDX-PERP/orderbook ``` ### 1. Get a credential (LIVE) Two credential types exist: - **Agent key** (`POST /agents/register`) — an Ethereum-derived keypair authorized by a one-time EIP-712 signature from your wallet. No session token required. This is the recommended path for an autonomous agent. - **HMAC API key** (`POST /keys`) — requires a session Bearer token first (`POST /auth/login` with an EIP-191 `personal_sign` signature). Sign in with an EVM wallet to get a 24h session token (used only for key management): ```sh curl -X POST https://exchange.nexus.xyz/api/exchange/auth/login \ -H 'content-type: application/json' \ -d '{"message":"Sign in to Nexus Exchange","signature":"0x"}' # -> { "token": "sess_..." } ``` Create an HMAC API key with that session token: ```sh curl -X POST https://exchange.nexus.xyz/api/exchange/keys \ -H 'authorization: Bearer sess_...' \ -H 'content-type: application/json' # -> { "key_id": "nx_...", "secret": "", "tier": "..." } ``` Register an agent key (EIP-712 signed by your wallet — no session token): ```sh curl -X POST https://exchange.nexus.xyz/api/exchange/agents/register \ -H 'content-type: application/json' \ -d '{"agent_address":"0x...","wallet_address":"0x...","signature":"0x","nonce":"...","expiry":...}' ``` See the `agents/register` entry in `/openapi.json` for the exact EIP-712 domain and typed-data fields. ### 2. Fund the account with USDX collateral There are two funding paths depending on environment. - **Synthetic credit (LIVE on demo/testnet)** — claim off-chain synthetic USDX up to a per-key daily allowance (default 500 USDX, resets midnight UTC). Authenticated with your API credential: ```sh curl -X POST https://exchange.nexus.xyz/api/exchange/account/credit \ -H 'x-api-key: nx_...' -H 'x-timestamp: ' -H 'x-signature: ' \ -H 'content-type: application/json' \ -d '{"amount":"500"}' ``` - **Real on-chain deposit (PARTIAL)** — `POST /deposits` records a USDX collateral deposit, but the canonical "watch this address, credit on confirmation" deposit-target flow (deposit-target derivation and deposit confirmation / crediting) is still being built. Until it lands, use synthetic credit on demo/testnet. ### 3. Place an order (LIVE) Submit a limit buy for BTC. The order surface accepts agent / HMAC / Bearer auth — any resolved credential works. The body shape is the `OrderRequest` schema in `/openapi.json`: ```sh curl -X POST https://exchange.nexus.xyz/api/exchange/orders \ -H 'x-api-key: nx_...' -H 'x-timestamp: ' -H 'x-signature: ' \ -H 'content-type: application/json' \ -d '{ "market_id": "BTC-USDX-PERP", "side": "Buy", "order_type": "Limit", "price": "50000", "quantity": "0.1", "time_in_force": "GTC" }' ``` Market order (no price): ```sh curl -X POST https://exchange.nexus.xyz/api/exchange/orders \ -H 'x-api-key: nx_...' -H 'x-timestamp: ' -H 'x-signature: ' \ -H 'content-type: application/json' \ -d '{"market_id":"BTC-USDX-PERP","side":"Buy","order_type":"Market","quantity":"0.1","time_in_force":"IOC"}' ``` Check the result: ```sh 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/fills -H 'x-api-key: ...' -H 'x-timestamp: ...' -H 'x-signature: ...' curl https://exchange.nexus.xyz/api/exchange/orders -H 'x-api-key: ...' -H 'x-timestamp: ...' -H 'x-signature: ...' ``` ## Authentication (HMAC signing) Send three headers on every authenticated request: - `X-API-Key`: your key ID (e.g. `nx_a1b2c3...`) - `X-Timestamp`: current time in unix milliseconds (must be within 30s of server time) - `X-Signature`: `hex(hmac_sha256(secret, canonical))` where ```text canonical = timestamp + "\n" + METHOD + "\n" + path + "\n" + query + "\n" + sha256_hex(body) ``` `query` is the raw query string without the leading `?` (empty string if none). `body` is the raw request body bytes (empty string for GET). Agent keys sign an equivalent canonical string with their secp256k1 key and send `x-agent` / `x-timestamp` / `x-nonce` / `x-signature`; see the `agents/register` entry in `/openapi.json`. ## Real-time data (WebSocket) - Public market stream: `GET /stream` (subscribe to `trades:*`, `book:*`, `stats`) - Per-account stream: mint a token via `POST /ws/token`, then connect to `GET /ws?token=...` ## Not built yet (honest scope) - **Canonical deposit-target flow** — derive a per-account deposit address, watch chain, credit on confirmation. Tracked separately; not yet built. Use `account/credit` synthetic USDX on demo/testnet in the meantime. This file and the discovery documents are part of the Exchange MVP Gate 2 ("Interfaces") work.