API Versioning

The Nexus Exchange API is versioned with the OpenAPI specification published at nexus-xyz/nexus-exchange-api. Each SDK release is pinned to a specific spec version, and the API declares a minimum supported version that it will accept. This page explains how to send your version, what happens when it falls below the minimum, and how deprecations are signalled.

Sending your version

Send the spec tag your client was built against in a request header, in addition to (not instead of) your User-Agent:

X-Nexus-Api-Version: v0.6.2

The value is the released spec tag (a leading v is optional — v0.6.2 and 0.6.2 are equivalent). The official SDKs are pinned to a spec version and send this header for you by default; you only need to set it manually if you build your own client.

The header is optional during the current pre-1.0 grace period — requests without it are accepted. This will tighten as the API approaches GA; send the header now so your integration is forward-compatible.

Minimum supported version

To avoid stranding integrations on breaking changes — while not carrying permanent backward-compatibility baggage before there is a large external client base — the API accepts requests only at or above a published minimum version.

Pre-1.0 support policy. Until the 1.0 GA release, the minimum supported version may advance aggressively as breaking changes ship. Breaking changes are a minor bump (0.X.0); non-breaking changes are a patch bump. The operational practice when the minimum advances is to first move versions below it into a deprecation window (see below) before retiring them, so an active integration gets a signalled window to upgrade. Treat the Deprecation / Sunset response headers as your authoritative upgrade signal rather than assuming a fixed grace period.

You can always read the current threshold programmatically — see Discovering the current version.

Below the minimum: 426 Upgrade Required

A request whose version is below the minimum is rejected with HTTP 426 Upgrade Required and a machine-readable JSON body:

{
  "code": "api_version_unsupported",
  "message": "Unsupported or missing API version. Fetch the current OpenAPI spec at spec_url, regenerate your client, and retry with the X-Nexus-Api-Version header.",
  "min_version": "0.6.0",
  "current_version": "0.6.2",
  "spec_url": "https://github.com/nexus-xyz/nexus-exchange-api/releases",
  "docs_url": "https://docs.nexus.xyz/exchange/apis-and-rates/api-versioning"
}

The response also carries an X-Nexus-Api-Min-Version header with the same floor, for clients that read headers without parsing the body.

Self-healing for agents. Because the body carries spec_url and both the minimum and current versions, an automated client can recover from version skew on its own: fetch the current spec, regenerate its client, and retry — no human in the loop. A version-skew error is a recoverable condition, not silent breakage.

Deprecation and sunset

A version that is still accepted but scheduled for retirement is served normally, with standard advisory headers on every response:

• Deprecation (RFC 9745) — signals that the version you sent is deprecated.
• Sunset (RFC 8594) — the date after which that version will be rejected with 426.
• Link: <…>; rel="deprecation" — points to this page.

Treat a Deprecation header as a prompt to upgrade before the Sunset date. Nothing about the request fails while it is in the deprecation window; only the advisory headers are added.

Header parsing details

A few specifics worth knowing if you build your own client rather than using an official SDK:

• Pre-release tags compare by release lineage. A pre-release such as 0.6.0-rc.1 is treated as 0.6.0 for the minimum check — everything from the first - or + is stripped. So a pre-release satisfies a floor equal to its release version.
• An unparseable version is treated as missing. During the grace period a malformed X-Nexus-Api-Version is accepted and logged, exactly like an absent header; once the header becomes required it is rejected the same way. Send a clean major.minor.patch tag (an optional leading v).
• CORS preflight and WebSocket handshakes are never gated. OPTIONS preflight and WebSocket upgrade handshakes are exempt — a browser cannot attach the header to either — so the gate never blocks them.
• Discovery routes are never gated. /metadata, /openapi.json, /llms.txt, and the /.well-known/* documents stay reachable at any version, so a stale client can always fetch what it needs to self-heal.

Discovering the current version

The current minimum and latest versions are published at an unauthenticated metadata endpoint, so clients and agents can read the threshold without scraping docs:

GET /metadata

{
  "api_version": {
    "header": "x-nexus-api-version",
    "min_supported": "0.6.0",
    "current": "0.6.2",
    "deprecated_below": null,
    "sunset": null,
    "spec_url": "https://github.com/nexus-xyz/nexus-exchange-api/releases",
    "docs_url": "https://docs.nexus.xyz/exchange/apis-and-rates/api-versioning",
    "policy": "pre-1.0: minimum-supported version may advance until GA; missing version header allowed during grace mode"
  }
}

/metadata is always reachable regardless of the version you send — otherwise an out-of-date client could never learn the value it needs to upgrade.

Recommended client pattern

1. Pin your client to a released spec version and send it in X-Nexus-Api-Version.
2. On a 426 api_version_unsupported, read spec_url from the body (or GET /metadata), regenerate against a version >= min_supported, and retry.
3. Watch for Deprecation / Sunset response headers and upgrade before the sunset date.