---
title: "Max: the best position for a trade"
method: GET
path: "/v1/max"
---

# Max: the best position for a trade

`GET /v1/max`

## Request

- Base URL: `https://qmax.exchange/api`
- URL: `https://qmax.exchange/api/v1/max`
- Auth: none declared

Searches for the best position, not just the best route. A normal order already goes at the best route (each market priced alone and a split, the cheapest taken); Max also looks at what to do with the order: take the best route now, or rest on the QX book at the touch for a better price (with how often QX traded there in the last day), or both; the size where one more unit starts to cost more; an arbitrage between QX and QSwap sized to the wallet; and, for a sale, what it returns against what the units cost. Each pick is a short list of ordinary actions (a market order at the best route or on one market, a limit order) with what it should give. Prices move: quote and check every action again before signing. Nothing is signed or sent. The wallet's numbers (`balanceQu`, `heldQty`, `avgCostQu`) come from the caller and are used only to size the plan. For agents a plan costs 100 QU: from a prepaid key's balance (POST /v1/keys, GET /v1/topup, POST /v1/topup/claim, then send x-api-key) or free inside an x402 session (GET /v1/x402). Without either the answer is a 402 with the price. The website's own Max is free.

## Query parameters

- `asset` string, required
- `side` 'buy' | 'sell', required
- `qty` integer
- `balanceQu` integer
- `heldQty` integer
- `avgCostQu` integer
- `slippageBps` integer

## Response `200`

{ asset, side, qty, baseline, picks, recommendedId, arbitrage, searched, cut, quotesUsed }

## Other responses

- `400`: Bad parameters, or nothing to plan from
- `402`: A Max plan costs 100 QU for agents: send a prepaid key (x-api-key) with at least that balance, or an x402 session
- `404`: Unknown asset
- `422`: The market cannot fill it, or the asset cannot be signed from here

---

[API](https://skmtc.dev/qmax/apis/qmax-api.md) · [All operations](https://skmtc.dev/qmax/apis/qmax-api/llms.txt) · [OpenAPI document](https://skmtc.dev/qmax/apis/qmax-api/revisions/af70e2813a7a?raw)