Skip to main content
Every change to the API’s shape since 2 October 2026 is listed here, newest first. Subscribe with the RSS button above. SDK releases are in the SDK changelog.

​
Versions

The API lives at /api/v1. Its version is the date of the latest entry below, for example 2026-11-09. Every response sends it in the ravn-version header and meta.version, and the OpenAPI spec carries it as info.version.

​
What can change in v1

Within /v1 the API only grows. Expect:
  • New endpoints, new optional request fields and new response fields. Ignore fields you don’t know.
  • New error codes. Show the message of a code you don’t know.
  • New status values. Treat one you don’t know like expired (see /status).
  • New chains, venues and tokens, listed on Supported chains & venues.
Within /v1 we don’t remove or rename a field or endpoint, change a field’s type or meaning, make a request field required, or send an executionType you haven’t opted into (AUTHORIZE needs authorizeSteps). Every change to the API’s shape is checked against these rules before it ships.

​
Deprecations

When something has to go, we:
  1. Post it here at least 90 days before it stops working, with that date.
  2. Mark it deprecated in the OpenAPI spec and the SDK, so your editor strikes it through.
  3. Send the Deprecation and Sunset headers on every call that uses it.
A security fix can move faster. One did: keys issued before public and secret keys existed (21 October 2026) keep full rights only until 1 December 2026, announced on 21 October (see that entry).

​
/v2

A /v2 comes only for a change that can’t be made by adding. /v1 keeps working for at least 12 months after /v2 ships.

​
Changes

​
  • ravn-version and meta.version name the API’s version: the date of its latest change. They said 2024-01 before.
  • The OpenAPI spec describes the streamed prices of /quote (PriceDTO) and the answer of /recover (RecoverDTO).
  • A streamed /quote sends preview lines: an early price from RAVN’s own multi-step route, before its settled.
​
  • A pair RAVN doesn’t swap answers 400 INVALID_REQUEST with the reason, not 500 INTERNAL.
​
  • /v1 accepts the x-ravn-sdk header from browsers: the SDK names its version in it.
​
  • venue.logoUrl: each venue’s logo, on quotes, alternatives, streamed prices, hops and /health.
​
  • transaction.gasLimit, and gasLimit on the swap’s entry in calls: send the EVM transaction with it. See /execute.
​
​
  • Public and secret keys: POST /keys/secret, and 403 FORBIDDEN for a public key where the secret key is needed. A key from before keeps full rights until 1 December 2026.
  • expectedOutputAmount on the quote and each alternative, slippage.expectedShortfallBps, and pickable on alternatives.
  • approval.spender names the contract the approval’s calldata approves.
​
  • "stream": true on /quote: each venue’s price as it lands.
  • quoteToken is usually a short id.
  • /execute prices a quote again up to 10 minutes past expiresAt, and answers 410 QUOTE_EXPIRED when it no longer meets the minimum shown.
​
  • excludeVenues and onlyVenues cover every step of a multi-step route.
​
  • Executions come ready to sign: calls and batch on EVM, deposit.psbt for Bitcoin, and deposit.transaction for a Solana deposit that carries your fee.
​
  • swapId on every execution, the Idempotency-Key header on /execute, and webhooks for every final swap.
  • timeoutMs on /quote: how long the race waits for venues.
  • approval comes only when the wallet needs a new allowance, and carries reset when the token needs its allowance set to 0 first.
  • sandbox: true on the execution of a sandbox quote.
  • Rate-limit headers and 503 UNAVAILABLE.
​
  • onlyVenues on /quote: race only the venues you list.
​
  • fee on an execution: your fee, when the route collects it beside the swap or the deposit. See Collecting your fee.
  • A missing address at /execute answers 400 INVALID_REQUEST naming the field, not 502 BUILD_FAILED.
​
  • broadcastViaRavn on /quote and POST /submit-transaction: more Solana routes, sent through RAVN.
  • allowNoMinimum on /quote: let routes with no minimum race beside your slippageBps.
  • A refundAddress given at /execute answers 400 INVALID_REQUEST where the venue would drop it.
​
  • Every alternative carries its own expiresAt, and expiresAt is always a real time.
  • txHash on /status: the transaction that proves your fee.
  • /submit-signature answers a venue’s refusal with 422 ORDER_REJECTED and its rate limit with 503 VENUE_RATE_LIMITED, not 500.
​
  • /execute answers 502 BUILD_FAILED when the venue can’t build the swap, and 503 VENUE_RATE_LIMITED when it is rate-limiting RAVN, not 500.
​
  • slippage.noMinimum: the route holds no guaranteed minimum. Alternatives carry slippage too.