> 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/apis-and-rates/apis-and-rates/api-versioning.md).

# API versioning

How the API is versioned, which version a client is served, and how a deprecation is signalled.

The Nexus Exchange API is versioned with the OpenAPI specification published at [`nexus-xyz/nexus-exchange-api`](https://github.com/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, so `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**, and requests without it are accepted. This will tighten as the API approaches GA, so send the header now to keep your integration forward-compatible.

## Minimum supported version

The API accepts requests only at or above a published minimum version. This avoids stranding integrations on breaking changes without carrying permanent backward-compatibility baggage before there is a large external client base.

**Pre-1.0 support policy.** Until the 1.0 GA release, the minimum supported version may advance aggressively as breaking changes ship. 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.

**How the number moves, and why its shape is not a compatibility signal.** The contract is pre-1.0, so read `0.MAJOR.MINOR`: normally a breaking change advances the second component and resets the third (`0.9.41` → `0.10.0`), and a non-breaking one advances the third (`0.9.41` → `0.9.42`).

There is one exception, and it is the reason you must not infer compatibility from the shape of the bump. While the contract in this repository already leads the latest published tag on its second component, a breaking change advances the **third** component as well. Opening a second unpublished `0.MAJOR` line would strand the one already in flight. A third-component bump therefore means "this is the next contract", not "this is safe to adopt without reading". `0.9.41`, which renamed six `GET /orders/history` response fields and re-cased `side`, is one such release.

Read the release's own notes and the `Deprecation` / `Sunset` headers to decide whether a version is safe for your integration. The version number alone cannot tell you.

You can always read the current threshold programmatically. See [Discovering the current version](#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:

```json
{
  "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. It can fetch the current spec, regenerate its client, and retry with 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](https://www.rfc-editor.org/rfc/rfc9745)) signals that the version you sent is deprecated.
* **`Sunset`** ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) gives 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

If you build your own client rather than using an official SDK, note these details:

* **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, 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, because 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
```

```json
{
  "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.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.nexus.xyz/apis-and-rates/apis-and-rates/api-versioning.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.