# Changelog

This page is for integrators upgrading the SDK: what changed in each version, in the categories Added, Changed,
Deprecated, Fixed and Security.

## 0.18.1 (12 November 2026)

**Changed (command line).** Buying BTC in `npx maxy` picks the coin, then its chain, then the amount from a short list
($10 to $100 with a test key, $25 to $1,000 live), each with what it gets by a live quote, or "Another amount" to type
one. With a test key the screens say the order moves on a sandbox timer (about 20 seconds) instead of "under a second".

## 0.18.0 (12 November 2026)

**Changed (no version in the paths).** Every route answers at the base URL with no version after it:
`https://whhxyutitykcsdpvdgcd.supabase.co/functions/v1/maxy-api/price`, `…/maxy-api/orders/{id}`. The SDK, the Python
client, the OpenAPI file and every page of these docs use that base. The routes, fields and answers are the same, and
existing integrations keep working unchanged. `GET /` no longer has a `version` field.

**Added.** `npx maxy sandbox key` prints a new test key and nothing else, so `export MAXY_API_KEY=$(npx maxy sandbox key)`
gets you started in one command.

**Changed (install).** `npm install https://maxy.co/sdk/maxy-labs-sdk-latest.tgz viem` and
`pip install https://maxy.co/sdk/maxy-latest.tar.gz` always install the newest release; `SHA256SUMS` beside them lists
every file's SHA-256.

## 0.17.0 (12 November 2026)

**Changed (package name and licence).** The SDK is `@maxy-labs/sdk` (it was `@maxy/sdk`): every import moves from `@maxy/sdk…` to `@maxy-labs/sdk…`
with nothing else changed. Both packages install from maxy.co, not a public registry: `npm install https://maxy.co/sdk/maxy-labs-sdk-0.17.0.tgz viem` and
`pip install https://maxy.co/sdk/maxy-0.17.0-py3-none-any.whl` (SHA-256 in https://maxy.co/sdk/SHA256SUMS). Both are MIT licensed.

**Added (stream tickets).** A browser's `EventSource` cannot send a header, and every route takes a key, so
`POST /orders/{id}/stream-ticket` and `POST /prices/stream-ticket` answer a ticket for one stream: one order, or one
pair at any amount, for 10 minutes. `GET /orders/{id}/events/stream?ticket=…` and `GET /prices/stream?ticket=…` take
it in place of the key. The ticket is signed, so nothing is stored, and it carries the key's id, never the key. Another
order or pair, a changed ticket or an expired one answers `401 invalid_ticket`. A publishable key may ask, from its
origins. `orders.watch` and `prices.stream` in a browser fetch a ticket first; on a server they keep the header.

**Security.** A whole secret key in a query string answers `400` on every route: it would land in logs and history.

**Fixed.** `POST /sandbox/keys` takes no body (`curl -X POST …/sandbox/keys` works as is), and `GET /` names that
command as `try`.

## 0.16.0 (10 November 2026)

**Changed (bridge legs).** Every EVM to EVM leg is the solver's route picker's route: of Mayan, deBridge, Across and
LI.FI, the one that pays out most after every fee, with a transaction that pays the user's own address. It replaces the
SDK's own LI.FI quote on `cross-evm` and on the second leg of a BTC sale into a coin no settler holds
(`bridgeBtcToEvmPayout`, `GET /orders/{id}/bridge`). The number shown is the solver's and the transaction signed is
the one it hands out. Before sending, the SDK checks that transaction itself by the rules of
the provider that carries it: that provider's contract, the user's address as receiver, the coin and amount asked for,
the quoted minimum where the calldata states one, no Mayan limit order, no deBridge taker or call on arrival, no Across
exclusive relayer, native value of the amount plus at most the provider's own fee, and a token approval for exactly the
amount to that contract. Another provider, or calldata that does not decode, is `verification_failed` and nothing is
sent. `checkCrossEvmQuote` returns what it proved.

**Changed (expiry and status).** A route's transaction carries its own expiry. A `cross-evm` quote lasts no longer than
it, and an order from a stale one is `quote_expired`: get a new quote, nothing was sent (HTTP: `409` with
`details.freshQuote`). A pair with no route is `unsupported_route` (it was `bad_response`). `swap.getStatus` and
`crossEvmStatus` ask the solver (`bridge_status`) with the provider and the source transaction hash; `REFUNDED` reads
as `refunded`, `FAILED` as `failed`, and a leg the solver cannot place stays `pending`. For a leg LI.FI carried, LI.FI's
status API answers when the solver cannot. The order cap on `cross-evm` is valued at the solver's live price.

**Added.** `quote.details.provider` and `via` on `cross-evm`; `provider`, `expiresAt` and `status` on the route's quote
(`quote.details.lifi`) and `provider` and `expiresAt` on the HTTP order and on `GET /orders/{id}/bridge`; `provider`,
`status` and `baselineBalance` in a `cross-evm` order's `response`; optional `provider`, `toAddress`, `toToken`,
`amountOutMin` and `baselineBalance` on `crossEvmStatus`.

**Migration (bridge legs).** Nothing is renamed. `slippage` is accepted and no longer used: the route's own minimum is
the floor. Handle `quote_expired` from `createOrder` on `cross-evm` by quoting again. A stored `cross-evm` order from
0.15.0 is still followed (as LI.FI's). A two-leg `btc-evm` quote names `symbol` and `decimals` for native coins, the
settler chains' tokens, and USDC and USDT on Ethereum, Optimism and Polygon; for any other coin they are null.

**Changed.** Every flow runs the app's own code. Signed BTC buys are priced by the app's `pricing.priceWithBuyCost`, the
bot's `(value + network fee) / (1 - margin)` that its commit gate requires; `fillCostUsd` and the margin come from one
`get_live_rate` read, or none when `prices` gives both (new `prices.buyMarginBps`). Quotes take their split from the
market maker's own answer, as the app does: `displayAmount` (gross), `networkFee`, `receiveAmount` (net). A SOL to BTC
quote now shows the market maker's real Bitcoin fee (it showed the EVM buys' fee), and BTC to SOL and BTC to EVM quotes
gain `networkFee`. BTC to SOL (`btc-sol`) is the app's flow: the market maker builds and pays for every Solana
transaction, the wallet signs three times (open, Bitcoin payment, stage + lock) and needs no SOL, the market maker sends
the BTC once it is locked, proves and settles. `settleBtcToSol` signs nothing: it reads the settlement signature.
`BtcToSolState` is `{ offer, paid, sats, assetAmount }`. HTTP: the `btc-sol` stages are `fill`, `pay`, `lock`,
`submit`, `cancel` and `state`; `POST /orders` answers the open to sign directly (no authorization message). A
Taproot (`bc1p`) address may pay.

**Changed (keys).** Every HTTP API route takes a valid key (owner, 7 November 2026): chains, tokens, pairs, price,
prices/stream, quotes/batch, status, the order reads (refund, deposit, claim, bridge, events/stream, cancel), limits,
addresses/validate and explorer answer `401 auth_required` without one. Only `/`, `/openapi.json`, `/health`,
the status page (`/system/*`), `POST /sandbox/keys`, docs feedback, security reports and hosted checkout's
`/checkout/verify` answer without a key. A publishable key works for the reads from its own origins.

**Migration.** Send `x-maxy-key` on every call (a test key: `POST /sandbox/keys`). HTTP integrations of `btc-sol` follow the new stages (`steps` and `next` in each answer say what to do);
`take`, `prepare`, `broadcast`, `proof`, `settle` and `send` are gone. SDK code that stored `BtcToSolState` from 0.15.0
finishes those orders with the market maker, which settles them on its own.

## 0.15.0 (5 November 2026)

**Added.** Self-serve test keys (`POST /sandbox/keys`), a status page at maxy.co/status, hosted checkout (`GET /checkout/verify`, `signCheckoutUrl`), `@maxy/widget`, `@maxy/cli`, `@maxy/api`, Python models (`Maxy(models=True)`). Routes: `/account`, `/usage`, `/keys`, `/limits/requests`, `/statements` (JSON, CSV, PDF), `/explorer/{query}`, `/feedback`, `/security-reports`, `/system/*`. `failureReason` on an order that ended badly. `details.freshQuote` on a 409 `quote_expired`. `Idempotency-Key` is now stored for a day: a repeat answers the first answer, with `Idempotent-Replayed: true`, and a different body answers 409 `idempotency_conflict`. Errors `checkout_signature_invalid`, `checkout_expired`, `idempotency_conflict`.

**Changed.** An order is done when the user's funds arrive. A Solana buy (`sol-btc`) now reads `completed` when the BTC is sent (`PAID`), the same as an EVM buy; it read `in_progress` until `SETTLED`. A buy whose BTC is out reads `completed` even if its settlement fails or runs late: `rawStatus` still shows it, for operations. Coin to coin reads `completed` when the coins reach the destination chain. A publishable key may now place the user's own signed order (`POST /orders`, `/orders/submit`, `/orders/{id}/signature`, `/orders/{id}/steps`, `/orders/{id}/cancel`); it gets the scope `place`. Packages: `@maxy-labs/sdk`, `@maxy/react`, `maxy`.

**Migration.** Code that waited for `rawStatus: SETTLED` on a Solana buy should wait for `state: completed`, and code that counted `in_progress` after `PAID` will see `completed` sooner. No field changed its name.

## Versioning

The SDK follows semantic versioning. A breaking change to anything covered below raises the major version (the minor
version while the SDK is below 1.0).

| Covered | Not covered |
| --- | --- |
| Public exports of `@maxy-labs/sdk` and its subpaths (`/core`, `/evm`, `/solana`, `/bitcoin`, `/server`, `/testing`, `/swap`, `/borrow`, `/mint`, `/orders`, `/btc`), their parameters and return types | `serverCode` values, which are the servers' own codes |
| `MaxyError.code` values and their meaning | The shape of `MaxyError.details` beyond the fields read by `retryAfterSecondsOf`, `unlocksAtOf` and `preparedPostOf` |
| Configuration options of `createMaxyClient` | `MaxyError.message` text |
| | Exports marked advanced in the reference (the low-level context, `poke`) |

## 0.14.0 (4 November 2026)

### Added

- **`@maxy-labs/sdk/core`**: one typed method per HTTP API route over `fetch` alone, 17 kB gzipped: `prices`, `pairs`, `quotes`, `orders`, `status`, `addresses`, `limits`, `health`, `key`, `webhooks`, `sandboxControls`, with `units`. Retries with backoff and `Retry-After`, a bucket from the rate-limit headers, shared reads in flight, `AbortSignal`, `meta.requestId`, Maxy's clock for `quotes.msUntilExpiry`, `onRequest`, `onResponse`, `onRetry`, and a `logger` that redacts keys, signatures and typed data. Types are generated from the OpenAPI document.
- **Flow helpers**: `buyBtcWithEvm`, `buyBtcWithSolana` and `sellBtc`, with the same progress events and a resume path, built on `createSwapMachine`.
- **Subpaths** `/evm`, `/solana`, `/bitcoin`, `/server` (Node and edge only: it does not bundle for a browser) and `/testing` (`createMockFetch`, `errorFixture`, `SandboxSimulator`, `mswHandlers`). Source maps.
- **`@maxy/react`**: `usePairs`, `usePrice`, `useQuote`, `useBuyBtc`, `useBuyBtcWithSolana`, `useSellBtc`, `useOrder`.
- **`maxy` for Python**: `Maxy` and `AsyncMaxy`, with `webhooks.verify` matching TypeScript byte for byte.
- **`maxy` command**: `doctor`, `pairs`, `order get|list|watch|events`, `webhooks` (`add`, `rm`, `test`, `replay`, and `listen --forward-to` with no tunnel), `sandbox advance|scenarios`.
- **HTTP API, additive.** Publishable keys (`mxk_pk_live_`, `mxk_pk_test_`) bound to origins; `POST /quotes/batch`; `GET /prices/stream` and `GET /orders/{id}/events/stream`; `quote.signing`, one shape on every route; `POST /orders/{id}/signature`; `POST /orders/{id}/cancel`; `GET /orders/{id}/events`; `refundAt`; `expiresAtIso`; `externalId` and `externalCustomerId` on orders; `limit`, `cursor`, `state`, `wallet` and `externalId` on `GET /orders`; CAIP-19 ids in and out; `GET /pairs` with route, settler, smallest order and confirmations; `/health` with the solver, Bitcoin and each verifier, and `degraded`; `routes` in `/limits`; `POST /webhooks/{id}/events/{eventId}/replay` and `?signed=1`; `POST /sandbox/orders/{id}/advance`, `?simulate=`, scenario `underpaid`. A caller's `x-request-id` is kept. Price reads count apart at ten times the limit, and the same question within 3 seconds is one read.

### Changed

- **`borrow.quote` above what a vault can lend now** answers `canBorrow: false` with the amounts and no figure for the ceiling, and `createRequest` refuses it with `insufficient_liquidity`.
- **USDC on BNB Chain** answers `unsupported_route` on `GET /price`, as `GET /pairs` and a firm quote already say: that settler does not take USDC as a bond.
- **`GET /orders` answers a page of up to 100**, with `nextCursor`. `format=csv` still takes up to 1,000.
- **Every error's `docs`** links its own row: `…/sdk-errors#quote_expired`. `retryable` is always present.
- **A secret key in a browser page throws at construction**; `dangerouslyAllowBrowser: true` overrides it.
- **Every failure is a `MaxyError` subclass.** `instanceof MaxyError`, `isMaxyError` and `code` work as before; `error.name` is the subclass.

## 0.13.5 (3 November 2026)

### Added

- **The sandbox.** A test key (`mxk_test_…`) runs the same HTTP API, SDK and CLI with nothing real behind them: `"sandbox": true` on every answer, real prices, signed webhooks, orders that walk `pending` → `in_progress` → `completed` on a timer, and a `scenario` to force every outcome, the refund screen included. A partner changes only the key. See [sandbox](integrate/sandbox.md).
- **`client.sandbox`** and **`isSandboxKey(key)`** say whether a client runs in the sandbox; **`SANDBOX_SCENARIOS`** lists the scenarios; `swap.quote`, `swap.createOrder` and `swap.execute` take `scenario`, which a live key ignores.
- **`sandbox_refused`** (`MaxyError.code`): a test key asked for something with no sandbox form (loans, mints, sign-in, a low-level order builder). Nothing happened.
- **`maxy` shows `[SANDBOX]`** in the banner, the prompt and every run with a test key.

### Changed

- A live key behaves exactly as before.

## 0.13.4 (3 November 2026)

### Changed

- **`swap.getSellTemplate` no longer returns its sizing field.** A size the solver cannot fill is still refused with `insufficient_liquidity` and no figure.

## 0.13.3 (3 November 2026)

### Fixed

- **`maxy price` shows the BTC network fee.** It reads before the fee, as the swap page does, but has no review step, so it now also shows the fee and what arrives. That is the same `receiveAmount` the SDK and the API return.

## 0.13.2 (2 November 2026)

### Fixed

- **Your key's order size cap covers EVM to EVM.** The quote still shows the amounts, with `issues.orderCap` and no steps; `createOrder` and `POST /orders` refuse with `order_cap_exceeded`. The order is valued at the dollars the bridge values the amount at.
- Docs: sells and Solana orders run over HTTP, `POST /orders` refuses a quote older than 60 seconds, exact BTC exists, and `quote.details` carries no `maxSats`.

## 0.13.1 (2 November 2026)

### Fixed

- A price or quote on SOL or an SPL coin to BTC, or BTC to SOL, larger than the market maker holds now answers at the same rate instead of failing with a size in the error. Placing it is refused with `insufficient_liquidity` and no figure.
- A sell paid out on Ethereum, Optimism or Polygon names its coin and chain: `to.symbol`, `to.decimals`, `to.chainName` and `formatted` were null.

## 0.13.0 (2 November 2026)

### Added

- **Every route over HTTP.** BTC to SOL or an SPL token: `POST /orders`, then the stages of
  `POST /orders/{id}/steps`, with the BTC sent last and only with the payment locked on Solana. Sells paid in a coin no
  settler pays: the settler leg as any sell, then `GET /orders/{id}/bridge`. EVM to EVM: `GET /quote`,
  `POST /orders` (checked and simulated), `POST /orders/submit`. No route answers `execution.by` any more.
- **Buy by exact BTC.** `swap.price` and `swap.quote` take `receive` (`'1.31'`, or a bigint of sats), and `/price` and
  `/quote` take `receive` or `toAmount`, at the same price as sizing by the amount sent.
- A sell from a contract wallet: `POST /orders` checks ERC-1271, as the settler does.

### Changed

- **Quotes last 60 seconds at `POST /orders`:** an older one is `409 quote_expired` (it was only the intent's 2 hours).
- **No per-order maximum.** The 500,000-sat limit is gone from the SDK and the API (`BUY_MAX_SATS` is removed): it copied a
  solver setting that no longer exists, and no contract has one. Your key's order size cap stays. An order larger than
  Maxy can fill now is refused when it is placed (`insufficient_liquidity`, "Unfillable right now"), with no figure.
- **Prices and quotes answer at any size, for sells too,** with the solver's own number; the order is what gets refused.
- `maxSatsOf` is removed, and no error or quote carries a maximum size.
- `toAmountMin` on a route through a bridge is the bridge's own minimum (it repeated `toAmount`).

### Fixed

- A two-leg sell quote with a Bitcoin `fromAddress` answers (it was a 500).
- `GET /` lists the webhook routes and `POST /orders/watch`.

## 0.12.0 (2 November 2026)

### Added

- **Selling BTC over HTTP.** `GET /quote` for a settler payout returns the sell order to sign; `POST /orders`
  sends it and the solver locks the payout in the settler; `GET /orders/{id}/deposit` reads the escrow from the
  settler and answers the address to pay, decoded from the settler's own script; `GET /orders/{id}/claim` answers
  the proof of the payment as a simulated transaction any wallet can send.
- **SOL and SPL tokens to BTC over HTTP.** `GET /quote` returns the message to sign; `POST /orders` opens the
  market maker's offer and returns the deposit transaction; `POST /orders/{id}/steps` checks the signed deposit,
  byte for byte, and sends it; `GET /orders/{id}/steps` says what is left.
- **Refunds over HTTP.** `GET /orders/{id}/refund` answers the settler call, simulated, for the user's wallet to
  send, or why it is not open yet and when it opens.
- The new routes are in `GET /` and `GET /openapi.json`.

## 0.11.0 (2 November 2026)

### Added

- **The integration guide**, rebuilt as its own chapter: what Maxy is, which path is yours, a ten-minute quickstart,
  the concepts (order lifecycle; prices, quotes and orders; keys, limits and retries; the security model), one page per
  integration path, step-by-step guides with curl, TypeScript and Python, UX guidelines, security and compliance,
  testing and going live, support, and the reference (contracts, chains and tokens, runnable samples).
- **Runnable samples** for every step of the reference flow in `examples/integrate/`, each with the real response it
  returned from the live API.
- `GET /addresses/validate`: whether an address is well formed and whether a Maxy order can pay it, with a reason.
- `GET /health`: `ok` or `degraded`, for routers that skip a degraded source.
- `GET /limits`: your key's order size cap, the smallest order, the quote lifetime and where you stand on your rate
  limit.
- CAIP-2 chain ids everywhere a chain is accepted (`eip155:8453`, `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`,
  `bip122:000000000019d6689c085ae165831e93`), and `caip2` on chains, prices and quotes.
- `expiresAt` on `POST /orders`: when an order whose escrow was never sent lapses.

### Changed

- **Prices answer at any size, with no size check.** Prices and quotes carry only `limits.minSats`. The separate size-check calls and fields are removed.
- **An order above the per-order maximum reads as the order size cap:** `order_cap_exceeded`, "Order size is capped
  for this API key. Try $X or less.", flagged on the quote for the order (`issues.orderCap`, `steps: null`) and
  refused by `createOrder` and `POST /orders` before anything is signed. Before, a price said
  `"liquidityAvailable": false` and the order failed with `insufficient_liquidity`.
- The cap message is now "Order size is capped for this API key. Try $100 or less." (was "API key's order size cap
  has been met. Try $100 or less."), the same from the SDK, the HTTP API and Maxy's servers.
- `waitForCompletion` (and `execute`) stops at `refundable`: nothing more happens there without the user.
- A refused key (`invalid_api_key`, `key_revoked`) answers with a `requestId`, the `x-request-id` header and the error
  page link, like every other error.

### Fixed

- `GET /status?txHash=` finds an order from any of its transactions, including a gasless order's escrow and every
  settlement (read from the settler's own events); a hash no order has is a 404 (it could return another order).
- `GET /status?orderId=` refuses a value that is not an order id (it could return another order), and without
  `route` reads the order's own route (a gasless order read as `evm-btc-escrow`).
- `txs` lists only real transactions: EVM hashes with `0x`, the Bitcoin txid bare.
- A malformed signature on `POST /orders` is `400 wallet_mismatch` (was `500`); an order without its `chainId` is
  `400 invalid_input`.
- `GET /orders` lists a new order as `pending` until Maxy first reads it (was `null`).
- Solana phases `REFUNDED`, `COOPERATIVELY_CANCELLED`, `LATE_UNPAID` and `EXPIRED_AFTER_PAY` read as final states (they
  read `pending`).
- The "Too small" error no longer carries the solver's internal pricing in `details`.

## 0.10.0 (2 November 2026)

### Added

- **Rate limits per key.** 600 calls a minute per API key (120 per IP without one), counted per key wherever the
  calls come from, for the HTTP API and for quotes through the SDK. Every HTTP API answer carries `RateLimit-Limit`,
  `RateLimit-Remaining` and `RateLimit-Reset`; over the limit is `429 rate_limited` with `Retry-After`.
- **Status by any transaction:** `GET /status?txHash=` (escrow, settlement or Bitcoin payment), and
  `GET /orders/{id}`.
- **Your orders:** `GET /orders` (JSON, or `format=csv`). Orders the SDK places with a partner key are filed under
  it, so they are listed there and reach your webhooks.
- Error bodies link the error catalogue (`docs`); browsers cache the API's CORS answer for a day.

### Changed

- A revoked key answers `403 key_revoked` (an unknown key stays `401 invalid_api_key`).
- Versioning policy: the API only gains fields; a breaking change comes with at least 90 days' notice.

## 0.9.0 (1 November 2026)

### Changed

- **Price and quote are split, the way swap APIs split them.** `swap.price()` and `GET /price` check what an
  amount gets right now, for showing while the user types; nothing is reserved. `swap.quote()` and `GET /quote` are
  for the order about to be placed. `GET /quote` now needs `fromAddress` and `toAddress` (without them it answers 400
  and points to `/price`) and returns `quoteId` and `issues.orderCap`. The CLI's `quote` and `quotes` are now
  `price <amount> <coin>` and `prices` (the old names still work); `price` alone still shows live coin prices.
- **Prices and quotes answer at any size.** An API key's order size cap refuses the order, not the quote:
  `createOrder` throws `order_cap_exceeded` (new code) before anything is signed, `POST /orders` answers 422, and
  Maxy's servers refuse a gasless buy or a sell above the cap before the solver acts. Above what Maxy can fill right
  now, `/price` and `/quote` show the amounts with `"liquidityAvailable": false` instead of no number.

### Added

- `GET /key`: your key and its order size cap.
- Browser apps can call Maxy's services with a partner key from any origin (the key is what is checked), and from
  maxy.co.

## 0.8.1 (1 November 2026)

### Changed

- **Faster.** Contract reads made together go out as one Multicall3 call; a buy's fill cost is read alongside its chain
  reads, and the free settler nonce is found in one round for a wallet's first 16 orders. A BTC buy's steps
  (`GET /quote` with addresses) come back in about half the time.
- **HTTP API reads need no key:** `GET /pairs`, `/price` and `/status` answer without one, limited per calling IP;
  a key that is sent is checked and metered as before. `GET /` lists every route with a link to try, a mistyped path
  answers with the route it was probably meant to be, JSON comes back indented, and every answer carries
  `Server-Timing: total;dur=…`.

## 0.8.0 (1 November 2026)

### Added

- **The HTTP API** ([HTTP API](http-api.md)): price, quote and place swaps from any language, at
  `https://whhxyutitykcsdpvdgcd.supabase.co/functions/v1/maxy-api`. `GET /chains`, `/tokens`, `/pairs`, `/price`,
  `/quote`, `/status`, `POST /orders`, `/orders/submit`, and an OpenAPI 3.1 spec at `/openapi.json`. Buying BTC runs end
  to end: the quote returns the typed data to sign, `POST /orders` returns the transaction to send (or, for USDC, hands
  the gasless order to the solver). Prices take plain words or the parameter names route aggregators and swap APIs use.
  It is this SDK running on Maxy's side, so every order is rebuilt and checked before anything is returned.
- **Signed webhooks** for the HTTP API: register HTTPS endpoints per key (`POST /webhooks`); each change of an
  order's state is delivered as an `order.updated` event signed with HMAC-SHA256 (`Maxy-Signature`), retried with
  backoff for about 22 hours, with a test event and a delivery log per endpoint. Orders placed through the API are
  followed automatically; `POST /orders/watch` follows any other. `verifyWebhook()` checks a delivery.
- `swap.chains()` and `swap.tokens(chain?)`: the chains Maxy swaps on and their tokens with decimals.
- `quote.formatted` carries `send`, `receive` and `pair`.
- `prepareGaslessOrder` / `submitGaslessOrder` (gasless USDC in two halves), `restoreEscrowOrder`,
  `restoreGaslessOrder`, `nativeEscrowTransaction`, `intentFromJson`: the building blocks the HTTP API uses, exported
  from `@maxy-labs/sdk/swap`.

### Changed

- `createGaslessOrder` runs on the two halves above; what the wallet is asked to sign is unchanged.

## 0.7.0 (1 November 2026)

### Added

- **Plain words.** `swap.quote` and the new `swap.execute` take coins as words (`'ETH'`, `'USDC on arbitrum'`,
  `'arbitrum:USDC'`, `'BASE.ETH'`, `'BTC'`, `'SOL'`) and amounts in whole coins (`'0.01'`, `25`). The exact form
  (`{ chain: 8453, token: '0x…' }`, a `bigint` in the smallest unit) is unchanged. Sats stay a `bigint`.
- **`swap.execute()`**: quote, sign, send and follow a swap in one call, with `onUpdate` steps for a progress UI.
- **`quote.formatted`**: the quote in words (`'0.01 ETH on Base'`, `'0.00025 BTC'`, the pair).
- **`swap.pairs()`** lists every pair; **`swap.describeAsset()`** gives a coin's symbol, decimals and chain name.
- `parseAsset`, `parseAmount`, `formatAmount` and `parseChain` are exported.
- CLI: `swap 20 usdc on base to btc` and `swap 0.001 btc to usdc on base` in one line; `quote` and `buy` accept a
  trailing `to btc`.

### Changed

- `createMaxyClient()` reads `MAXY_API_KEY` from the environment in Node when no `apiKey` is passed.
- The integration guide shows each kind of integrator (swap APIs, route aggregators, wallet SDKs with plugins, card
  on-ramps) with the plain-words calls.

## 0.6.4 (29 October 2026)

### Changed

- **Shorter command pages.** `help <command>` (also `man <command>` and `<command> --help`) shows the summary, the
  usage and the examples only; the explanatory paragraphs are gone.

## 0.6.3 (29 October 2026)

### Changed

- **Results stay on screen in the menu.** After Quotes, Orders and Prices, `maxy` waits for Enter before showing
  the menu again. With every quote now arriving at once, the menu printed right under the table pushed its top rows
  (the Buy BTC routes) off a normal-size terminal.

## 0.6.2 (29 October 2026)

### Changed

- **Many quotes in the time of one.** Quotes started together (`Promise.all` over several `swap.quote` calls, a price
  list, `maxy quotes`) go to Maxy as one request that the order bot prices in parallel in one warm container. All 21
  routes of `maxy quotes` now arrive in about 1.5 s, the time of a single sell quote, instead of 3 to 8 s. Each quote
  still resolves or fails on its own with the same result and `MaxyError` as before; a lone quote is sent as it always
  was, and if the combined request fails each quote is asked for alone.

## 0.6.1 (28 October 2026)

### Changed

- **`maxy quotes` prints each route the moment its quote is in**, in order, with a count of what is left, instead of
  one table after every quote has come back.
- **No wait before the first question.** `maxy swap` (and `buy` / `sell`) reads live prices in the background while
  the coin and amount are chosen; the paying wallets' balances load while the amount is quoted; `maxy quote` asks for
  the quote and the prices at the same time.
- **Per-key order size cap** (server side, no SDK change): a swap quote above your key's cap, $100 unless agreed
  otherwise, is refused with HTTP 422, `serverCode` `order_cap_exceeded`, and a message naming the cap (today: "Order
  size is capped for this API key. Try $100 or less."). `maxy` prints that message and asks for a smaller amount
  ([limits](limits.md#swaps)).

## 0.6.0 (28 October 2026)

### Added

- **Your own API key.** `apiKey` takes the key Maxy issues to your integration (`mxk_live_…`). The SDK sends it in
  `x-maxy-key` with the API's public gateway key (`MAXY_PUBLIC_KEY`, new `publicKey` option for a staging `apiUrl`), so
  Maxy counts your calls and can revoke the key on its own. A revoked or unknown key is refused with `auth_required`
  (server code `invalid_api_key`). Also exported: `SDK_VERSION`, `PARTNER_KEY_RE`.
- **`maxy` command line.** `npx maxy` asks how to work: the numbered menu, or a command line with commands like a
  shell's: `ls`, `cat`, `new`, `add`, `mv`, `rm`, `key`, `login`, `price`, `quote 20 usdc base`, `quotes`,
  `buy`/`sell` with `--from`, `--to` and `--yes`, `borrow`, `repay`, `mint`, `redeem`, `apikey`, `help`/`man`. Each runs
  once (`npx maxy ls orders --json`) or at the `maxy ›` prompt, with tab completion and ↑ history. See [the CLI](cli.md).
- `maxy apikey set <key>` saves the key in `~/.maxy/config.json`.

### Changed

- The shared public key of earlier versions still works, but is no longer what Maxy issues: ask for your own key.

## 0.5.5 (24 October 2026)

### Changed

- **`maxy swap` (buy):** "Bitcoin sent" shows the sats that arrive.

## 0.5.4 (24 October 2026)

### Added

- **`maxy borrow` (MaxyLock) and `maxy mint` (Maxy Mint), built like `maxy swap`.** Numbered choices, saved, pasted or new
  wallets with their balances, a wallet that is short shows what to send and where; a review confirmed with `OK` before
  anything is signed; then every transaction with its explorer link, followed live (Enter stops watching).
  - Borrow: USDC on Base or USDG on Robinhood Chain against BTC, from the quote to the loan claimed into the wallet
    (Maxy sends a little gas when the wallet has none); repay, with the secret revealed and the BTC coming back; your
    loans, and claiming a payout. A quote MaxyLock cannot take is shown and refused only after `OK`, before anything is
    signed. Shortcuts `npx maxy repay`, `npx maxy loans`.
  - Mint: BTC.R on Robinhood Chain from BTC, with the custody of the BTC stated in the review; redeem BTC.R for BTC (the
    exact fee in a second review before the burn); refund a payment that cannot mint. The mints and redemptions made from
    a computer are kept by id in `~/.maxy/mints.json` (Maxy Mint has no list by wallet) and also show up in `orders`.
    Shortcuts `npx maxy redeem`, `npx maxy mints`.
  - `loans` and `mints` take `--json`.

## 0.5.3 (23 October 2026)

### Changed

- **Wording.** "Solver" everywhere a partner reads (docs, diagrams, the `maxy` command, error messages). The docs describe
  what the contracts do rather than how Maxy runs the solver; BTC to EVM payouts on other chains are described for any
  EVM chain; the EVM to EVM route is marked as a bridge, not a Bitcoin swap.

## 0.5.2 (23 October 2026)

### Changed

- **`maxy swap` is as fast as the swap page.** Everything OK needs is read while the review is on screen (the order,
  checked on-chain, and the wallet's nonce and fees on Base, BNB Chain and Avalanche), so OK only signs and broadcasts;
  a prepared order is not simulated again; an instant fill prints the Bitcoin transaction straight from the order's answer,
  and otherwise the order is checked every 0.4 s at first. "Bitcoin sent in N s" counts from the escrow reaching the chain.

### Fixed

- A 64-hex Bitcoin private key starting with 1 or 3 was refused as a legacy address when pasted into `maxy`.

## 0.5.1 (23 October 2026)

### Changed

- **Wording.** "Maxy does not store your key; it remains only on your hardware"; creating a wallet during a swap is
  marked optional; buying ends with one line: "Bitcoin sent in 0.8 s", the sats, where they went and the link.
- **`maxy swap` is done when the user's coins are sent, like the swap page.** Buying BTC finishes the moment the BTC is
  sent to the user's address (usually under a second); the escrow settling afterwards is Maxy's side and is not waited for.
  Selling finishes when the payout reaches the user's wallet, with a live count of the confirmations left and the minutes
  to the payout.

## 0.5.0 (23 October 2026)

### Added

- **The `maxy` command** ([the CLI](cli.md)): `npx maxy` opens a numbered menu: Swap (buy or sell BTC end to end,
  every step a numbered choice), Quotes, Orders (with each order's transactions), Wallets and Prices. Wallets are picked,
  pasted or created on the spot during a swap, for EVM and Bitcoin; the first sign-in creates the wallet's Maxy profile.
  `--json` for scripts.
- **Key-backed signers in one call**: `evmSignerFromPrivateKey(key)` (follows the SDK to every Maxy chain),
  `bitcoinSignerFromKey(key)` (WIF or hex, native SegWit), `createEvmKey()`, `createBitcoinKey()`,
  `bitcoinAddressOfKey(key)`.
- `createMaxyClient({ solanaWeb3 })`: the Solana library for Solana orders in a browser bundle.
- Error code `missing_dependency`; `UNFILLABLE_MESSAGE`.

### Changed

- **Orders larger than Maxy can fill right now are refused "Unfillable right now"** (`insufficient_liquidity`), and the
  message names no limit. This covers EVM to BTC orders above the per-order range (before: `amount_out_of_range` with the
  range in the message) and BTC to EVM quotes Maxy could not pay (before: the quote succeeded and the order was
  refused later).
- **Too small reads too small.** An EVM to BTC quote whose amount does not cover the solver's costs is
  `amount_out_of_range` "Too small: orders start at 546 sats after costs" (before: `bad_response` "No BTC quote right
  now").
- **A clean install.** `@solana/web3.js` is an optional peer dependency, loaded only when a Solana order runs.
  `npm install @maxy-labs/sdk viem` installs 21 packages instead of 71, prints no deprecation warning (the `uuid@8` warning came
  from `@solana/web3.js`) and audits with 0 vulnerabilities. Solana quotes, previews and status work without it; Solana
  orders need `npm install @solana/web3.js` (Node loads it by itself) and throw `missing_dependency` without it.

## 0.3.2 (23 October 2026)

### Fixed

- **EVM to BTC orders lock what the quote says.** The quote already takes the solver's fill cost out of the sats;
  the signed price now always carries that cost too, so the escrow matches the quote's amount. Before, an order whose
  fill cost was over 25 % of it (under about $1.60) was signed at the bare market price and locked less than quoted
  (0.0004 ETH quoted, 0.00024 ETH locked). An order whose fill cost is more than the BTC it buys is refused as
  `amount_out_of_range`.
- **Solana previews reject an asset that was not awaited.** `swap.solanaAsset` returns a promise; passing it to
  `previewSolToBtc`, `previewBtcToSol` or `createSolToBtcOrder` without `await` priced SOL whatever the asset was.
  It now throws `invalid_input`.

### Security

- **`prepareOrder` / `createOrder` refuse an escrow above the quote.** An `evm-btc-escrow` order that would lock more
  than the quote's `sendAmount` plus the intent's slippage and 1 % throws `quote_mismatch` before anything is signed,
  so a bad price or cost feed cannot overcharge.

## 0.3.1 (22 October 2026)

### Added

- **`swap.prepareOrder(quote, { evm, btcAddress })`** and `createOrder(quote, { ..., prepared })` for
  `evm-btc-escrow`: every read happens before the user confirms, so confirming only signs, broadcasts and notifies the
  solver. Also `swap.prepareNativeEscrowOrder`, the `PreparedEscrowOrder` type and `PREPARED_TTL_SEC`.
- **`simulate`** on `createOrder` for the EVM to BTC routes (default `true`), as the route builders already had.

### Fixed

- **Status of an EVM to BTC order** always finds the order by its on-chain intent hash and keeps the BTC txid: every buy
  sends `fallbackOrderId`, status falls back to the solver's own order id, and a buy counts as completed once its
  BTC is sent.

## 0.3.0 (21 October 2026)

Upgrading from 0.2.0: since 21 October 2026 the solver refuses BTC to EVM orders created by 0.2.0
(`settler_only`). Install 0.3.0 before creating new ones; the exports removed below have no replacement to call.

### Changed

- **BTC to EVM runs through the settler.** `createBtcToEvmOrder` signs the solver's SELL intent (EIP-712, checked
  field by field and against the settler's `hashIntent`), and returns the deposit only once the payout is escrowed in the
  settler for the signing wallet, read on-chain (`deposit.verifiedBy: 'settler'`, new `order.settler`). The payout always
  goes to the signing wallet; `destAddress` is now optional and must equal it for a settler coin. Settler coins: ETH /
  USDC / USDT on Base and Arbitrum, BNB / USDC / USDT on BNB Chain, AVAX / USDC / USDT on Avalanche, ETH / USDG on
  Robinhood. Any other EVM coin is two legs: the settler pays ETH on Base to your wallet, then `bridgeBtcToEvmPayout`
  sends a checked LI.FI bridge from it. Removed: the `SettlementForward` payout authorization (`settlementForwardTypedData`,
  `SETTLEMENT_FORWARD_TYPES`, `SETTLEMENT_OUTPUT_KIND`, `DEFAULT_MM_WALLET`, `SELL_DIRECT_CHAINS`, `SELL_BRIDGED_CHAINS`).
- `payDeposit` re-reads a btc-evm escrow before paying and refuses when it closed or too few blocks are left.
- `createBtcToSolOrder` prices the sats again before any wallet prompt, asks for that fresh settler price, and throws
  `quote_mismatch` if it is more than 0.1% below `assetAmount` (previously it asked for `assetAmount` unchecked).

### Added

- `swap.claimBtcToEvm`: prove your BTC payment from public Esplora data and receive the escrow from your own wallet,
  without the solver (`slashSellWithProof` in the one-block late window). `buildSellProof`, `stripWitness`,
  `merkleRoot`.
- `swap.getSellTemplate`, `swap.getSellEscrow`, `swap.bridgeBtcToEvmPayout`; exports `SETTLER_SELL_CHAINS`,
  `SELL_SETTLER_CHAINS`, `MM_SAFE`, `bridgedSellPlan`, `settlerSellAsset`, `readSettlerEscrow`.
- `getStatus` of a btc-evm order reads the settler escrow (`rawStatus` `settler:COMMITTED|FILLED|SLASHED|REFUNDED`).
- A btc-evm quote of a coin no settler holds is two legs (`details.legs: 2`, `bridge`, `minReceiveAmount`, `via`).
  `details.symbol` / `decimals` describe `receiveAmount`, the coin asked for; the settler leg's coin is the new
  `details.settlerSymbol` / `settlerDecimals`.

### Deprecated

- `SETTLEMENT_CHAIN_ID`: unused since the SettlementForward authorization was removed.

### Fixed

- LI.FI quotes (`cross-evm`, the bridge leg of a two-leg `btc-evm`) are asked from LI.FI directly when Maxy's
  `lifi-quote` relay is rate limited or unavailable; it shares one LI.FI allowance between every caller. The
  transaction is checked the same way whichever answered. A LI.FI refusal of the route itself is not retried.
- EVM to BTC orders (`createNativeEscrowOrder`, `createDirectEscrowOrder`, `createGaslessOrder`, `createOrder`) fold the
  solver's fill cost (BTC network fee and EVM gas, from `get_live_rate`) into the signed limit price, as the app
  does. Orders signed at the bare market price were not filled: the solver requires an escrow that covers the
  cost, so they waited for the refund. New optional `prices.fillCostUsd`; new exports `fillCostUsd`, `withFillCost`,
  `MAX_FILL_COST_FRACTION`. If the cost cannot be read, nothing is signed (`bad_response`).
- `planRefund` on a committed order before its Bitcoin deadline throws `not_refundable` (previously `tx_reverted`):
  the RPC names the settler's `IntentNotExpired()` error only by its selector.
- Documentation: the `btc-sol` route is described as it works (trustless, through the Solana settlement program, with
  the solver settling a paid offer for you); SOL to BTC limits are the solver's live limits.

## 0.2.0 (16 October 2026)

### Added

- `apiKey` and `apiUrl` configuration options, and the `MAXY_API_URL` constant.
- MaxyLock market id `'base-mainnet'` for Base; `canonicalMarket(market)`.
- Typed readers for error details: `maxSatsOf`, `retryAfterSecondsOf`, `unlocksAtOf`, `preparedPostOf`.
- `MAXY_ATTEST_SIGNERS` environment variable as the fallback for the `attestSigners` option.
- Documentation: signers, glossary, environments, limits, operations, data handling, audits, endpoints; architecture and
  sequence figures.

### Changed

- MaxyLock results report the market as `'base-mainnet'` (previously `'mainnet'`).
- The one notice the SDK can print, when no attestation signers are configured, now names the SDK option.
- A MaxyLock `keeper_unhealthy` refusal maps to `route_disabled`.

### Deprecated

- The previous names of the API key and base URL options; they are accepted unchanged, and the new names win when both
  are set.
- Market id `'mainnet'` for Base; accepted as an alias of `'base-mainnet'`.

## 0.1.0 (16 October 2026)

First version.

### Added

- `createMaxyClient` with one shared configuration, transport, read clients and clock.
- `auth`: Sign-In with Ethereum.
- `swap`: quotes and orders for `evm-btc-escrow`, `evm-btc-direct`, `evm-btc-gasless`, `btc-evm`, `sol-btc`, `btc-sol`
  and `cross-evm`; status, waiting, escrow reads and refunds.
- `borrow`: MaxyLock loans on Base (USDC) and Robinhood Chain (USDG) with local plan verification.
- `mint`: Maxy Mint on Robinhood Chain (BTC.R) in direct-custody mode; HTLC mode implemented and disabled until deployed.
- `orders`: one list of swaps, loans and mints.
- `btc`: payment builder (deposit first, change last), broadcast, Bitcoin chain readers, HTLC scripts.

## Where next

- [Documentation index](README.md)
- [Core reference](reference/core.md)

**Next:** [Migration guides](integrate/migration-guides.md).

_Last verified: 2 November 2026._
