Nexus Exchange MCP Server

[!WARNING] This repository is archived and no longer maintained. The Nexus Exchange API it was built for is being shut down, and no further releases will be published.

An MCP server that exposes the Nexus Exchange API as tools an AI agent (Claude Desktop / Claude Code) can call to read market data and place trades.

It talks to the real, public exchange gateway. Market-data and demo tools work with zero configuration; account and trading tools use HMAC API credentials read from environment variables.

What works today

Every tool sends the spec's bare path (/orders) to one REST base: the spec's /v1 base on the public testnet host (https://api.testnet.nexus.xyz/v1), and the origin on a bare indexer such as local. The bridge tools are the one exception while the pinned spec lacks their bare twins. See "REST base and paths" below.

get_deposit_target is wired into the agent flow but returns a clear not_yet_available message rather than faking a result. The bridge deposit-address tools (create_bridge_deposit_address / list_bridge_deposit_addresses) were meant to supersede it, but they are deprecated: no server implements /api/v1/bridge/deposit-addresses (its design was cancelled with ENG-11460), so every call fails.

Tool names

Each tool is named snake_case of the spec operationId it calls, with the direct-indexer V1 suffix dropped (fetchOrderBookV1 → fetch_order_book), so the name an agent picks matches the operation and the other SDKs (R2.25, ENG-17742). scripts/check_spec_drift.py enforces it.

The previous names (list_markets, get_ticker, place_order, …) stay registered for one minor release as deprecated aliases: each forwards to the same handler, and its description starts with `Deprecated: use <new name>. The full map is DEPRECATED_ALIASES in [src/tools/index.ts`](./src/tools/index.ts). Two changes are not plain renames:

• list_markets keeps returning the markets summary

(GET /markets/summary), so it aliases fetch_markets_summary. The static specs (GET /markets, formerly list_market_specs) are fetch_markets.

• cancel_order now cancels one order only. The account-wide cancel it used to

do with cancel_all: true is cancel_all_orders, which requires confirm: true.

REST base and paths

Per EDR-006 (ENG-17186, ENG-18323) every request is the spec's bare path under one REST base: sent as /v1/orders on the public testnet host, signed as /orders.

• One base. https://api.testnet.nexus.xyz/v1 on testnet, and the bare

origin (http://localhost:9090) on an indexer that serves at its root, like local. The /v1 is the published prefix the edge strips before the indexer sees the request, so copy the base whole rather than trimming it to the hostname: the bare host routes nothing and answers 404. A NEXUS_EXCHANGE_API_URL that still ends in /api/exchange is accepted and normalized, so it cannot double up. Which host that is comes from the network axis, and a named network keeps its own gateway path when NEXUS_EXCHANGE_API_URL only redirects the host.

• HMAC signs the bare path (/orders). The base's own prefix is not signed

over, so the signed path and the wire path differ by that prefix; see Authentication.

• The bridge is the one exception. The pinned spec (v0.8.1) declares the

bridge operations only under /api/v1/bridge/*, so those tools still send /v1/api/v1/bridge/... and sign /api/v1/bridge/..., which routes and verifies. They move to bare paths once a published spec carries the bare twins (ENG-18318 added them upstream).

• `cancel_order` requires `market_id`. cancel_all_orders takes an

optional market_id to scope a mass-cancel to one market.

API-surface coverage

71 registered tools (plus 48 deprecated aliases, see Tool names) covering 66 spec operations of Exchange API spec v0.8.1. Those are two different numbers and neither substitutes for the other: an alias calls the same operation as its canonical tool, and two tools call none. The operation count is the figure comparable with the rs / py / cli SDK manifests; the tool count is MCP's own axis and must never be reported as a coverage figure. docs/coverage-unit.md records that decision and how it is enforced.

66 of the 68 distinct operations, or 66 of the 101 the spec literally documents — the spec lists most operations twice, once on the legacy gateway route and once on its /api/v1 alias, and each aliased pair is one tool.

The operation list is not hand-counted: endpoints.txt is generated from the per-tool ops declarations in src/tools/index.ts and verified against the pinned spec on every PR by scripts/check_spec_drift.py (see Spec drift).

The pin bump (ENG-6038) was pin-only — it advanced .api-version v0.6.2 → v0.7.1 without mapping the surface those releases had added. ENG-6136 then exposed those additions as tools, and ENG-6461 advanced the pin to v0.7.2 together with the portfolio-parity surface it added. ENG-9342 then advanced it to v0.7.3, pin-only again; the three routes that release added are mapped here (ENG-9202, below), leaving only the field-level half of ENG-9636. ENG-10482 then advanced the pin to v0.8.1, which added and removed no route: both tags document the same 101 operations, and all 92 documented 2xx bodies stay application/json. That is why neither pin bump moved the counts by itself — not that the two releases were empty. v0.8.x did change schemas on routes this server already maps, and the additions it does not expose are listed after the list below. Below, the spec version each addition shipped in is noted:

• Portfolio parity (v0.7.2) — fetch_portfolio_history

(GET /account/portfolio-history: equity + PnL + volume series over a day/week/month/all window), fetch_account_state (GET /account/state: summary + open positions from one coherent read), and fetch_trading_fees (GET /account/fees: effective maker/taker bps, tier, rolling 30d volume, discounts). The same release enriched the Position schema — notional_value, margin_used, roe, max_leverage, and leverage, each nullable with a <field>_error companion, plus the always-present funding_paid (no _error companion: its "0" is a real zero, not unknown) — and added withdrawable to the portfolio summary; those are response-shape additions on already-mapped routes, so they change no route count — the tools that return them (fetch_balance, fetch_positions, fetch_account_state, fetch_account_summary) call them out in their descriptions instead.

• Account cancel-on-disconnect (v0.7.1) — fetch_cancel_on_disconnect /

set_cancel_on_disconnect (GET / PUT /account/cancel-on-disconnect).

• `/api/v1/bridge` Phase A (v0.7.1) — fetch_bridge_assets (public catalog),

create_bridge_deposit_address, list_bridge_deposit_addresses, fetch_bridge_deposits, and fetch_bridge_deposit (five operations).

• Registered withdrawal wallets (v0.7.3, ENG-8902) —

create_bridge_wallet_challenge, register_bridge_wallet, and list_bridge_wallets (POST /api/v1/bridge/wallets/challenge, POST / GET /api/v1/bridge/wallets). Unlike a schema-only addition these are /api/v1-native with no legacy alias, so they raised the denominator: the v0.7.2 → v0.7.3 pin bump (ENG-9342) moved it from 65 distinct operations to 68 while coverage stayed at 63. Mapping them here closes that gap. Registration is two-step and stateless — the challenge returns a message bound to the account and the address, and register_bridge_wallet echoes it back with the wallet's EIP-191 signature over it. The challenge is not a nonce: until it expires the same signature can be resubmitted, which is a no-op because it only re-registers the same address for the same account. The account holds one wallet in this cut and it cannot be replaced — a different address is refused with 409 wallet_already_registered — so register_bridge_wallet is funds-guarded and additionally requires confirm: true.

• Conditional order types (v0.7.0) — create_order / create_orders /

preview_order now map all six conditional order_types in addition to limit / market: stop-loss (stop_limit / stop_market), take-profit (take_profit_limit / take_profit_market), and trailing (trailing_stop / trailing_limit), via the trigger_price, trailing_offset_bps, and limit_offset_bps fields. These are a schema addition on the already-mapped order endpoint, so they change no route count — which is why the pin bump's operation-count metric never surfaced the gap.

Every operation this server can map is now mapped (ENG-9202). The 2 remaining are unmapped by design — the WebSocket upgrade endpoints GET /ws and GET /stream: a request/response MCP tool cannot hold a streaming socket open, so the server instead mints the auth token (create_ws_token / create_ws_token_legacy) the caller uses to connect to them directly. That is a decision, not a backlog item, and it is recorded as such in NON_SPEC_TARGETS' neighbouring note in scripts/check_spec_drift.py; the checker keeps printing them so the exclusion stays visible rather than becoming invisible once it is deliberate.

The v0.7.2 cursor query parameter (ENG-5506) is now exposed on the five paginated list tools — see "Pagination" below. It adds no route, so the operation count above is unaffected.

Two optional request fields are documented but not exposed, and neither affects the operation count. v0.7.3 documents max_slippage_bps on create_order, create_orders, and preview_order (ENG-7550) — note the engine has always accepted and enforced it (the fill VWAP is bounded against the mid captured at submission, and the remainder cancels when the cap would be crossed); v0.7.3 puts it on the public contract rather than introducing it, so this is exposure work, not a new capability. It adds no route, so ENG-9202 did not cover it; it remains the field-level half of ENG-9636.

v0.8.0 documents the optional stp field on those same three order tools — the public exposure ENG-5022 asked for. It is opt-in self-trade prevention, one of CancelNewest, CancelOldest or DecrementAndCancel, where omitted or null means self-matching is allowed: that is the default and the industry-standard behaviour, so a caller who never sets it is unaffected. The engine has always accepted it, so this too is exposure work rather than a new capability. The same release added two read-only companions on Order that this server does not surface either — stp echoes back the mode an order was placed with, and cancellation_reason reports why a terminal order was cancelled (null, a bare string, or a single-key object such as {"Stp": "CancelOldest"}). None of the three adds a route. ENG-9636 is scoped to the v0.7.3 surface and does not cover them; the v0.8.x surface needs its own follow-up.

One already-mapped route did change its response body: v0.8.1 repointed both funding-samples operations from FundingSample to a new FundingPremiumSample carrying only timestamp and premium_index. FundingSample is otherwise unchanged and still serves GET /markets/{market_id}/funding, so this is a schema repoint rather than a property removal — but the effect on the funding-samples body is that funding_rate, mark_price and oracle_price are gone from it. fetch_funding_samples describes the series and never named those keys, and nothing in this repo reads them, so no tool description drifted.

Reconciling the liveness surface: v0.7.0 removed the standalone /health and /ready routes from the public contract (only /status remains), so the former get_health / get_readiness tools — which called routes the pinned spec no longer documents — were dropped in favour of the surviving fetch_status (/status).

Pagination

Five list tools are cursor-paginated (spec v0.7.2, ENG-5506):

Each returns an envelope, not a bare array:

{ "items": [ … ], "next_cursor": "opaque-token" }

The agent drives the loop: call once with no cursor, then call again with cursor: <previous next_cursor>, and stop when `next_cursor` is null. Server state rides in the X-Next-Cursor response header, which the server sends only while more results exist — its absence is the documented end-of-results signal, not an error. An empty items array with a non-null next_cursor is _not_ the end either: a sparse page still has pages behind it.

limit bounds one page, not the total, and is validated against that endpoint's own maximum (table above) before the request, so an out-of-schema value is never signed or forwarded. The maxima are not interchangeable — in particular fetch_portfolio_history's limit cap of 366 is that endpoint's alone and it takes no cursor at all.

If the upstream ever returns the _same_ cursor it was given, paging cannot advance. Handing that token back would put an agent in an unbounded tool-call loop, so the tool forces next_cursor to null and adds a pagination_error saying the results are incomplete — a stop, but explicitly not "end of history".

These parameters were in the spec ahead of the indexer, which may not yet emit X-Next-Cursor (ENG-5506). That degrades safely: with no header every response is next_cursor: null, i.e. exactly the pre-pagination single-page behaviour.

Authorization tiers

• Public — no credentials.
• HMAC (key): account reads, trading, agent/funding actions. Uses

NEXUS_EXCHANGE_API_KEY / NEXUS_EXCHANGE_API_SECRET, or the key create_api_key just made (see Stored credentials). The testnet host verifies it as your own key; see Authentication.

• Wallet signature: login (EIP-191), register_agent and

revoke_agent (EIP-712), and register_bridge_wallet (EIP-191) carry a wallet signature. revoke_agent accepts nothing else: no HMAC key, session or agent key. Pass one made in the wallet as signature, or, on a play-funds target only, omit it and the stdio server signs with its own wallet (see Local wallet). The server never holds a key for real or undeclared funds, and the hosted server never holds one at all.

• Session token — the *_api_key tools authenticate with a Bearer session

token from login. The stdio server keeps it for the session and saves it, so nothing needs copying into the environment (see Stored credentials); NEXUS_EXCHANGE_SESSION_TOKEN still works.

• Admin (opt-in) — fetch_tiers / set_tier / delete_tier use the

operator admin secret and mutate other accounts' fee tiers. They are not registered unless NEXUS_EXCHANGE_ENABLE_ADMIN_TOOLS=1 is set (and NEXUS_EXCHANGE_ADMIN_SECRET provided). Never enable these on an untrusted agent surface.

Destructive tools (revoke_agent, delete_api_key, delete_tier, and cancel_all_orders) require an explicit confirm: true flag so a stray call can't do damage by accident.

Quick start

The server is published to npm as @nexus-xyz/exchange-mcp, so it runs with no clone and no build step. Register it with Claude Code in one line:

claude mcp add nexus -- npx -y @nexus-xyz/exchange-mcp

Or launch the stdio server directly (npx fetches the package on first run):

npx -y @nexus-xyz/exchange-mcp

It waits on stdio for an MCP client and is meant to be launched by that client (see Claude Desktop config below) rather than run by hand. Market-data and demo tools work with zero configuration; see Environment variables to enable account/trading tools.

Prefer to run from a checkout — for development, or to use the smoke check? See Development.

Full circle on testnet

With nothing configured, an agent on the stdio server can go from no account to a closed position on testnet (play funds) through tools alone. Each step is one tool call:

Nothing is copied into the environment and the server is not restarted (see Stored credentials). create_wallet refuses when this network already has a wallet; confirm: true replaces it and the old key is lost. claim_faucet has a per-wallet cooldown and cap, and claim_credit is the per-key daily allowance.

examples/full-circle.mjs runs these steps against a throwaway config directory, so your own Nexus config is left alone.

Environment variables

Copy .env.example and set as needed. Only trading/account tools need credentials — never commit real secrets.

Stored credentials

The stdio server shares its credential file with the Nexus CLI (nexus), so a key made in one works in the other. The file is $XDG_CONFIG_HOME/nexus/config.json, or ~/.config/nexus/config.json when XDG_CONFIG_HOME is unset (macOS included), with one section per network under networks.<network>, as in the CLI's per-network credentials:

{
  "networks": {
    "testnet": {
      "api_key": "nx_...",
      "api_secret": "...",
      "session_token": "..."
    }
  }
}

• login keeps its session token for the rest of the session and saves it to

the active network's section, as nexus auth login does.

• create_api_key does the same with the new key id and secret. Once the

secret is saved, the result shows "secret": "[REDACTED]" and saved_to names the file. If the save fails, the result carries the secret in full and a save_error.

• At startup the server reads the active network's section. Environment

variables win field by field, matching the CLI's order (flags > env > file). A file that is not valid JSON stops the server at startup, as it stops the CLI, rather than being read as empty and overwritten.

So an agent goes from login to create_api_key to a trade in one session, with nothing copied into the environment and no restart, and the key still works after one.

The file is written 0600 in a 0700 directory, through a temp file and a rename. Each write holds .config.json.xlock across its read, merge and rename, the lock nexus also takes (concurrent writers), so a nexus command and the server never overwrite each other's change. The lock is created exclusively (O_CREAT|O_EXCL), holds pid=<pid> created_ms=<unix ms>, and is deleted when the write ends; a writer that finds it retries for up to 15 s and deletes it once its mtime is over 10 s old. A nexus older than the lock does not take it, so the server still re-reads after each write and reports a field such a write erased as unsaved (the secret comes back in full). One network's credentials never go into another's section: a bare NEXUS_EXCHANGE_API_URL, and a custom stage whose label spells a network name, have no section, so what login and create_api_key return is kept for the session only and the secret comes back in full. The hosted HTTP server never reads or writes this file.

Local wallet

On a play-funds target (testnet, local, or a custom stage declared NEXUS_EXCHANGE_FUNDS=play), the stdio server can hold a wallet key of its own, so an agent can make an account with nothing signed elsewhere: create_wallet, then login with no signature, then create_api_key.

• create_wallet generates a secp256k1 key and saves it as private_key in

the active network's section of the file above, then uses it for the rest of the session. It returns the address and saved_to, never the key. If a wallet already exists it refuses unless confirm: true, which overwrites the old key and keeps it nowhere.

• To use a key you already have, set NEXUS_EXCHANGE_PRIVATE_KEY. It wins over

the file, and create_wallet will not replace it.

• With a wallet held, login, register_agent, revoke_agent and

register_bridge_wallet sign for themselves when signature is omitted. An explicit signature is still accepted everywhere. login signs only its fixed message, register_bridge_wallet only for the held wallet's own address, and register_agent and revoke_agent only on testnet and local (their signatures are bound to the server's network name, which a custom stage does not declare).

• On mainnet, and on a custom stage whose funds are real or unknown,

create_wallet and self-signing refuse before any request, and a key in the environment or the file is not even loaded. No tool ever returns the key.

• The nexus CLI shares the file. A CLI release without

nexus-exchange-cli#95 drops private_key the next time it writes the file (for example on nexus auth login), so update the CLI before using both.

Agent safety modes

Two switches limit what an agent can do, for trying an agent out or giving it market access without trading rights (ENG-20366). Each one is an env var or a flag in the stdio server's args. The hosted HTTP server reads only the env var.

{ "command": "npx", "args": ["-y", "@nexus-xyz/exchange-mcp", "--paper"] }

Read-only keeps a tool only when its readOnlyHint annotation is true, so the set is exactly what tools/list labels as read-only. Every tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint); one that calls anything but a GET has to declare them or the server refuses to start. preview_order and the two WebSocket-token tools are POSTs that count as read-only: they change no account state.

Paper mode fetches the market's public order book when an order is placed and walks it. A market order takes levels until it fills or the book runs out. A limit order fills only the levels its price crosses, and what is left rests in an in-memory paper book for the life of the process (IOC cancels it, FOK fills all or nothing, PostOnly is rejected if it would cross). Every response says "simulated": true. It is deliberately simple. It does not simulate margin or balance checks, fees, funding, liquidation or positions, and a resting paper order never fills later, even when the market trades through it. Only limit and market orders are simulated. Nothing in paper mode places, amends or cancels a real order.

Networks

The target is chosen on a network axis — whose money is behind it — not a release channel. NEXUS_EXCHANGE_NETWORK takes testnet, mainnet, local or custom; the map for the three named networks lives in one place, src/networks.ts, copied from the spec's x-nexus-networks extension.

Nothing changes if you set nothing. The default resolves to exactly the host this server has always used.

`mainnet` deliberately does not work yet. Its host api.nexus.xyz has no DNS (ENG-8155) and the pinned spec maps no operation onto its /v1 base, so any URL built for it would be a guess — on the one network where a guess moves real money. It fails with an explanation instead. To target it once it is live, set NEXUS_EXCHANGE_API_URL explicitly alongside NEXUS_EXCHANGE_NETWORK=mainnet — the network declares the funds, so the URL is only redirecting its host and stays the sanctioned way to reach real funds before the durable host exists.

Three rules this implements, all from the spec extension:

• Hosts are never interpolated from the network name. Mainnet is off-pattern

on purpose — api.nexus.xyz, not api.mainnet.nexus.xyz — so api.{network}.nexus.xyz would resolve for every environment that can be tested and fail only on real funds. Every host is a named literal.

• An unrecognized network is treated as real funds. A typo is an error, never

a fallback to play money. local is likewise never a fallback for a public host that fails to resolve — succeeding quietly against localhost would hide a misconfigured client.

• Credentials never cross networks. Session tokens, HMAC keys and agent

registrations are minted per network and are invalid on any other. Switching network means switching credentials; never carry a signature or a nonce across.

A custom stage

A deployment that is not one of the three networks — a private stage, a sandbox, an indexer on your own machine — is a custom target: it carries the same descriptor a named network does (label, host, funds, faucet, gateway shape), and this package ships no hostname for any of them. You supply it.

NEXUS_EXCHANGE_NETWORK=custom
NEXUS_EXCHANGE_API_URL=https://exchange.example.com   # the stage's origin
NEXUS_EXCHANGE_NETWORK_LABEL=dev                      # a name for it
NEXUS_EXCHANGE_FUNDS=play                             # real | play | unknown
NEXUS_EXCHANGE_FAUCET=1                               # only if it has one
NEXUS_EXCHANGE_GATEWAY_PATH=/                         # bare indexer; omit for /api/exchange

Four rules, and they are the same four in every Nexus client:

• `custom` carries the whole bundle, not just a URL. A URL alone is what

makes a client report play-funds guardrails while pointed at a real-funds host.

• Funds are caller-declared, tri-state, and have no default. real, play,

or unknown. A staging deployment of mainnet is real-funds-shaped, so defaulting to play would make every guardrail lie in the direction that costs money, and defaulting to real would make a dev stage unusable.

• A faucet is separate from funds, and absent until declared. "Not real

money" does not imply "has a faucet".

• The label is restricted to `[A-Za-z0-9._-]` (max 64). Across the clients it

is the key stored credentials are namespaced under, so a label that can name a path (../other, one/two) or normalize onto another label is refused.

custom is client-side only. It is not a value the API accepts and it does not appear in the spec's x-nexus-networks.

Undeclared funds refuse the tools that cannot be undone

NEXUS_EXCHANGE_API_URL on its own is the deprecated legacy shortcut. It still works — no bundle required, legacy /api/exchange suffix still normalized — and it resolves to a custom target whose funds are undeclared. It also has no deployment shape to read, so it assumes the public-gateway one and the notice below says so; every request is composed under that gateway path, which is the one thing about this form that is not byte-identical to what it used to resolve to. A bare URL pointed at an indexer that serves at its root wants NEXUS_EXCHANGE_NETWORK=local alongside it, or the full bundle. That is not the same as play funds, so these tools refuse rather than proceed on an assumption:

Everything else is unaffected: every read, preview_order, and — deliberately — cancel_order. Blocking a cancel would trap a caller holding open risk, which is the opposite of a guardrail.

To lift the refusal, say what the target is: select a named network with NEXUS_EXCHANGE_NETWORK, or describe the stage with the bundle above. Declaring real is a legitimate answer and unlocks the irreversible tools — the guard asks that somebody know, not that the money be play.

Because the bare form cannot answer that question, a server started on it prints one notice on stderr naming the declared form, then runs exactly as before (a single line, wrapped here):

nexus-exchange-mcp: NOTICE: NEXUS_EXCHANGE_API_URL on its own is deprecated and
still works. On its own it also assumes the PUBLIC-GATEWAY shape, so every
route resolves under /api/exchange; for an indexer that serves at its root, add
NEXUS_EXCHANGE_NETWORK=local, or describe the deployment with the full custom
bundle …

Nothing is removed, and nothing is written to stdout — that is the JSON-RPC channel on the stdio surface, and a stray line there would corrupt the protocol.

Release channels are a URL, not a network

beta / staging are deployments of testnet, not a third pool of money, so they are no longer enum values. Describe them as a custom stage instead:

NEXUS_EXCHANGE_NETWORK=custom
NEXUS_EXCHANGE_API_URL=https://staging.example.com   # the deployment's origin
NEXUS_EXCHANGE_NETWORK_LABEL=staging
NEXUS_EXCHANGE_FUNDS=play                            # a testnet deployment holds play funds

The URL overrides the network map and is validated either way (http(s) only, no embedded user:password@, no query or fragment, since the base is concatenated with a request path). Plaintext http to a non-loopback host warns on stderr: HMAC over http exposes the key id and signature in transit — a private stage on plain http is exactly what that warning is for.

Setting the URL alone still works and is the deprecated shortcut: it leaves the funds undeclared, which is why it is a custom target with no bundle rather than a mechanism of its own, and why the tools that cannot be undone refuse on it. Both are documented in A custom stage.

WebSocket targets

create_ws_token and create_ws_token_legacy now return ws_endpoint alongside the token, so a caller is no longer handed a 60-second credential with no address to spend it at. For a named network the endpoints are the spec's published ws_url for that network (x-nexus-networks, copied into src/networks.ts), which is the spec's REST base with the scheme swapped:

wss://api.testnet.nexus.xyz/v1/ws      # authenticated, connect with ?token=…
wss://api.testnet.nexus.xyz/v1/stream  # public market data

The /v1 prefix is required: the bare host routes no WebSocket path and answers 404 (ENG-17132). Mainnet has the same shape on api.nexus.xyz, which does not resolve yet (no DNS, ENG-15183). With an explicit NEXUS_EXCHANGE_API_URL (or a custom stage) the endpoints derive from that gateway base instead, since /ws, /stream, /ws/token and /ws-tokens carry no per-path servers override in the spec. On local there is no prefix at all — ws://localhost:9090/ws — because the indexer serves those routes at its root.

API version

<!-- api-version-sync:start -->

Currently targets Exchange API spec `v0.8.1`.

<!-- api-version-sync:end -->

The pinned version lives in .api-version; the spec itself is published by nexus-xyz/nexus-exchange-api. This repo does not vendor a copy — the checks below fetch the pinned release. The line above is bot-managed; everything around it is human-owned.

Three separate things watch the pin, and they answer different questions:

spec-autobump (daily cron, repository_dispatch from the api repo, or manual dispatch) classifies the pin advance with oasdiff and opens a PR touching only .api-version and the managed line above, labelled spec-autobump or breaking · needs-SDK-update. It never merges: allow_auto_merge is disabled on this repo, so the workflow probes the setting and says so in the PR body rather than calling gh pr merge --auto and reporting success over a no-op. It supersedes the old poll-only api-version-sync workflow, which had no classification step.

#### Spec drift

spec-drift is the verification half, and it runs on every PR — including the autobump's own, where the pin _is_ the change. It enforces three invariants:

1. every operation in endpoints.txt exists in the pinned spec;
2. endpoints.txt matches the per-tool ops declarations byte-for-byte (it is a

generated artifact, not a hand-maintained list);

1. each tool's declared ops match the operations its handler actually requests.

All three key an operation on METHOD /path (placeholder names normalized), never on operationId. Ids are not stable across releases: v0.8.0 swapped createWsToken and createWsTokenLegacy between POST /ws/token and POST /ws-tokens — changing no route, and nothing this server calls, but a guard keyed on ids would have broken on it anyway.

npm run spec:drift        # verify against the pinned spec
npm run spec:drift:write  # regenerate endpoints.txt after adding operations
npm run spec:drift:test   # self-test: prove the checker goes red when defeated

Adding a tool without declaring what it calls is a type error, so the mapping cannot be skipped. See docs/coverage-unit.md.

Every upstream request also sends this pin as an X-Nexus-Api-Version: <tag> header (e.g. X-Nexus-Api-Version: v0.8.1), alongside a normalized User-Agent: nexus-exchange-mcp/<version>, so the exchange edge can attribute and segment usage by client and by the contract version this server targets. The header value is the server's own compiled-against tag — it is baked in at build time (a test keeps it equal to .api-version), so it is never taken from caller input.

Authentication

Agent keys (recommended for AI agents)

An agent key is a secp256k1 key a wallet authorizes to trade for it (POST /agents/register). It can place, amend and cancel orders and read the account, but it cannot withdraw, transfer, or manage agents. That makes it the credential to hand an AI agent: if the model, its transcript or its host leaks the key, nobody can move funds out with it.

Set NEXUS_EXCHANGE_AGENT_PRIVATE_KEY (or send X-Nexus-Agent-Private-Key to the hosted server). Every account and trade tool then signs with the agentAuth scheme the SDKs use, and the agent key wins over an HMAC pair when both are set:

keccak256(<METHOD>\n<path>\n<query>\n<sha256hex(body)>\n<timestamp_ms>\n<nonce>)

signed with the agent key (recoverable secp256k1, no EIP-191 prefix) and sent as x-signature alongside x-agent, x-timestamp and x-nonce. The path is the same bare path the HMAC scheme signs.

To get one, generate a key (any 32 random bytes, e.g. openssl rand -hex 32) and register its address with your wallet: nexus agents register in the Nexus CLI, or the register_agent tool here. The server requires each agent's nonce to rise on every write, so this server sends one agent-signed write at a time; run one server per agent key.

HMAC API keys

Signed requests use the same canonical HMAC-SHA256 scheme the indexer verifies (backend/services/indexer/src/auth.rs):

<timestamp>\n<METHOD>\n<path>\n<query>\n<sha256hex(body)>

signed with the hex-decoded secret and sent as x-signature alongside x-api-key and x-timestamp.

The signed path is the spec's bare path (e.g. /orders), and for the bridge tools /api/v1/bridge/.... The base's own prefix is not signed over. On a bare indexer (NEXUS_EXCHANGE_NETWORK=local) the two coincide, so the client signs exactly what it sends. On the public testnet host they differ: the wire path is /v1/orders while the signature covers /orders, and the route strips /v1 before the indexer checks (apps-prod-testnet.yaml: "transport prefixes are stripped before auth"). If signed calls 401 on a prefixed host and the same key works against a bare indexer, that stripping is the thing to check.

The testnet host verifies the caller's own HMAC. A bad signature is answered 401 UNAUTHORIZED, and a valid key acts as the account that minted it: its own balance, faucet credit, orders and positions. So trading as yourself needs no special gateway, and an agent can make its own account there with tools alone (see Full circle on testnet). local (the http://localhost:9090 from the exchange docker-compose) verifies client HMAC the same way.

The one exception is the retired legacy gateway at exchange.nexus.xyz/api/exchange, which no network targets since ENG-8869 (it now answers 500). It proxied authenticated requests and signed them with the site's own frontend key, so per-caller HMAC was not honored and calls resolved to the site account. A custom stage still behind such a proxy behaves the same way.

Claude Desktop config

Add this to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "nexus-exchange": {
      "command": "npx",
      "args": ["-y", "@nexus-xyz/exchange-mcp"],
      "env": {
        "NEXUS_EXCHANGE_NETWORK": "testnet"
      }
    }
  }
}

Running from a local checkout instead? Use "command": "node" with "args": ["/ABSOLUTE/PATH/TO/nexus-exchange-mcp/dist/index.js"] (after npm run build).

testnet is the default, so the env block above is optional — it is spelled out because naming the network is what declares the funds. To reach a deployment this package ships no host for, use the custom bundle rather than NEXUS_EXCHANGE_API_URL alone:

"env": {
  "NEXUS_EXCHANGE_NETWORK": "custom",
  "NEXUS_EXCHANGE_API_URL": "https://exchange.example.com",
  "NEXUS_EXCHANGE_NETWORK_LABEL": "dev",
  "NEXUS_EXCHANGE_FUNDS": "play"
}

To enable trading, add NEXUS_EXCHANGE_API_KEY / NEXUS_EXCHANGE_API_SECRET to the env block, or on testnet let the agent make its own key (see Full circle on testnet).

Demo script

1. Add the config above, restart Claude Desktop, and confirm nexus-exchange

appears in the tools list.

1. Ask: "Show me the BTC market on Nexus" — Claude calls fetch_markets_summary /

fetch_ticker and reports the live BTC-USDX-PERP price.

1. Ask: "What's in the demo account and its open positions?" — Claude calls

get_demo_account and get_demo_positions against the live exchange.

Hosted HTTP server (remote MCP)

The stdio server above runs locally and holds your API key on your machine. The hosted Streamable HTTP server is the remote front door: it lets a trader add Nexus as a remote MCP server without running any key-holding software locally.

# from the published package (no clone):
npx -p @nexus-xyz/exchange-mcp nexus-exchange-mcp-http

# or from a checkout:
npm run build
npm run start:http   # listens on :8080, MCP endpoint at /mcp, probe at /healthz

Behind a TLS-terminating ingress this is the public endpoint https://mcp.exchange.nexus.xyz/mcp. A client adds it with:

claude mcp add --transport http nexus https://mcp.exchange.nexus.xyz/mcp

It exposes the same tool surface as the stdio server — both transports register the identical ToolDef[] from src/tools/ via createServerForClient in src/server.ts, so the tools never drift. The transport is the SDK's StreamableHTTPServerTransport in stateful mode (one MCP session per mcp-session-id), which also serves the SSE fallback stream for server→client messages. Hosted traffic keeps the same nexus-exchange-mcp/<version> User-Agent as the stdio CLI but appends a (http) comment (nexus-exchange-mcp/<version> (http)) so usage attributes to the hosted MCP in the dashboard while still segmenting under one product and version.

Authentication (MVP — no OAuth yet)

OAuth 2.1 is out of scope for this MVP (tracked under the hardening work, ENG-3598, and scoped-key minting, ENG-3486). Until that lands, the hosted server takes the caller's existing Exchange HMAC credential as request headers, captured once at session initialize and reused for the session:

>

``text X-Nexus-Api-Key: <hmac key id> X-Nexus-Api-Secret: <hmac secret, hex> ``

>

or, recommended, a trade-only agent key that cannot withdraw:

>

``text X-Nexus-Agent-Private-Key: <agent private key, hex> ``

>

These are deliberately not named x-api-key / x-signature (the upstream gateway's own headers) to avoid confusion. With no credential headers a session still serves public market-data tools, and every authenticated tool refuses with an error naming the two headers.

>

The hosted server never uses server-env credentials (ENG-4359). NEXUS_EXCHANGE_API_KEY, NEXUS_EXCHANGE_API_SECRET, NEXUS_EXCHANGE_AGENT_PRIVATE_KEY, NEXUS_EXCHANGE_SESSION_TOKEN, NEXUS_EXCHANGE_ADMIN_SECRET and NEXUS_EXCHANGE_PRIVATE_KEY are ignored in HTTP mode, and so is the stored-credentials file, so a caller that sends no headers can never trade as the server's account. Admin tools are never exposed over HTTP. The stdio server still reads them from the environment as before, then from that file.

>

Header passthrough is the simplest defensible MVP, but the long-term answer is OAu