# QMax

> QMax is a non-custodial liquidity router and trading terminal for Qubic. It compares the QX order book with the QSwap pool and splits an order across both for the best price. It is free to use. AI agents can call its HTTP API, pay for Max plans with x402 and sign their own trades.

QMax never holds keys: every trade is signed in the person's or the agent's own wallet, and QMax never signs or sends a transaction for anyone. Prices are in QU, Qubic's coin; quantities are whole units of an asset. A quote is a snapshot: prices move, so quote again before signing.

## Use the API

API base URL: https://qmax.exchange/api

- [OpenAPI document](https://qmax.exchange/api/v1/openapi.json): every endpoint, its parameters and responses.
- [Plans](https://qmax.exchange/api/v1/plans): what is free and what agents pay, as JSON.
- [Assets](https://qmax.exchange/api/v1/assets): every tradable asset (QX tokens and smart-contract shares) with its markets, price, liquidity and volume.
- [Quote](https://qmax.exchange/api/v1/quote?side=buy&asset=QDOGE&qty=1000000): the cheapest way to fill an order across QX and QSwap, splits included, with each leg's venue, size, price, fees and the limits to sign against. Free.
- [Order book](https://qmax.exchange/api/v1/book?asset=QDOGE): the QX ladder and the QSwap pool's depth. Free.
- [Candles](https://qmax.exchange/api/v1/candles?asset=QDOGE&range=7d): open, high, low, close and QU volume from real trades, about six months back. Free.
- [Arbitrage check](https://qmax.exchange/api/v1/arbitrage?asset=QDOGE): a live search for a profitable loop between QX and QSwap after every fee. Free.
- Also free: price history, pools and their fee yield, asset health, the live trade tape, a wallet's trade ledger and QSwap liquidity positions. See the OpenAPI document.
- [Max plan](https://qmax.exchange/api/v1/max?asset=QDOGE&side=buy&balanceQu=5000000): the best position for a trade, not just the best route (a normal quote already takes the best route): the best way to execute (a market order now, a resting limit order at the touch, 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, the best exit. Nothing is signed or sent. **Costs 100 QU per plan for agents**, charged only for a plan that was made.

Without a key the market endpoints are limited to 60 requests a minute per IP, and answer 429 with Retry-After past that. No account or key is needed otherwise.

## Paying for Max plans (x402)

QMax follows Q+Pay's x402 wire format (scheme `exact`, network `qubic:mainnet`, asset `QUBIC`), settled on-chain through QPayhub, so an agent that already pays Q+Pay resources can pay QMax the same way, with no account. Two ways to pay for a Max plan:

- **An x402 session:** 10,000 QU buys 1 hour of unlimited Max plans. Call `GET https://qmax.exchange/api/v1/max` without a session: the 402 answer carries the price, a payment ticket and the exact QPayhub payment to make; pay it, then repeat the same request with an `X-PAYMENT` header. The reply carries `X-ACCESS-GRANT`: send it on later calls for the rest of the session. [Offer](https://qmax.exchange/api/v1/x402)
- **A prepaid key:** `POST https://qmax.exchange/api/v1/keys` makes a key (shown once), `GET https://qmax.exchange/api/v1/topup` gives the QPayhub payment that fills its balance, `POST https://qmax.exchange/api/v1/topup/claim` counts it once it confirms, and then each plan takes 100 QU from the balance (send `x-api-key`). A top-up of 10,000 QU buys 100 plans.

A payment per call is not offered: QPayhub keeps at least 100 QU of every payment, so a payment that small would lose its value to the fee. Everything else in the API is free.

## MCP server and SDK

- [Guide](https://qmax.exchange/agents/): what is here and how to run it.
- [MCP server](https://qmax.exchange/agents/qmax-mcp.mjs): one file, run with Node 22 or newer (`node qmax-mcp.mjs`, MCP over stdio); it talks to https://qmax.exchange/api by default. Its tools are read-only: quotes, order books, candles, arbitrage checks, pools and unsigned trade plans, plus `qmax_best_position` (Max), which costs 100 QU a plan.
- [TypeScript SDK](https://qmax.exchange/agents/qmax-sdk.tgz): an npm package with types (`npm install https://qmax.exchange/agents/qmax-sdk.tgz`); `@qmax/sdk/agent` signs an agent's own trades inside limits it sets. The same client as one file: [qmax-sdk.js](https://qmax.exchange/agents/qmax-sdk.js).
- [SHA256SUMS](https://qmax.exchange/agents/SHA256SUMS): the hash of each download; check it before running anything.

## Trading safely

- A quote's `route[].execution` carries the limits (minimum received or maximum paid) for each leg; sign only inside limits you set yourself, and refuse anything outside them.
- Only QX and QSwap are ever involved. Check every transaction's destination before signing.
- Steps run one at a time; stop at the first failure and read the wallet back to see what happened.

## Optional

- [QMax website](https://qmax.exchange/): the trading terminal: charts, order book, swap, portfolio, pools.
- [Support QMax](https://useqpay.com/s/oY6W64P): a Q+Pay tip jar; QMax is free for everyone.