Qmax

QMax

About this repository. This is the open part of QMax: the router, the HTTP API, the website, the SDK, the MCP server and the x402 helpers. Some parts of QMax's own deployment are not included: the Max planner, the Max pass logic, the Discord bot (apart from its QU price feed), the server deployment files and every secret. Where code here depends on a withheld part there is a small stand-in file that keeps the types and says so, so the rest builds and runs. All rights reserved: no license is granted.

QMax finds the best route to get you the max for your money on Qubic. Given buy 5000 ASSET, it prices the order on the QX order book and the QSwap pool (fees, price impact and transfer costs included) and routes to the cheaper venue, or splits across both.

npm i

npm run qmax -- buy 100000 [--snapshot file.json] [--no-split] npm test

What costs money (and what does not)

Almost everything is free, to help adoption, since other Qubic sites are free: the website (no pass, no per-trade fee), the HTTP API (no key, no billing), the SDK, the MCP server and agents. The one thing sold is Max quotes for agents (GET /v1/max, API_MAX_PRICE_QU, 100 QU a plan on the live server): an agent pays from a prepaid key's balance or holds an x402 session, while the website's own Max and QMax's own keys never pay (below). The Discord bot's subscription exists in the code but is switched off. "Free" is not "unlimited": callers without QMax's own key are limited per IP on the market endpoints (API_FREE_PER_MIN, default 60 a minute) so one of them cannot swamp the Qubic node, and QMax's own key (the Discord bot) is not limited. Income is therefore the Max quotes agents buy (and any support tips), and the Discord subscriptions if they are ever switched back on, which is also what the subscribers' profit share is made from (below).

• API_ACCESS=free (default): everyone, no key. billing: the old prepaid per-call prices and x402 sessions, kept but off. private: only API_KEY gets in.
• `API_MAX_PRICE_QU` (default 0: Max quotes are free; 100 on the live server) sells Max plans to agents inside API_ACCESS=free: the meter then serves only GET /v1/max, and keys and top-ups work (POST /v1/keys, GET /v1/topup, POST /v1/topup/claim, GET /v1/account) but nothing else is charged. Who pays: an agent with a prepaid key (x-api-key) is charged the price after the plan is made, so a request that cannot be planned costs nothing (and one whose balance was spent meanwhile gets a 402, not the plan); an agent with an x402 session (GET /v1/x402, API_SESSION_PRICE_QU for API_SESSION_SECONDS) pays nothing per plan; anyone else gets a 402 that names the price and both ways to pay. Never charged: QMax's own keys (API_KEY, ADMIN_KEY) and requests the website's own page makes (a browser marks them Sec-Fetch-Site: same-origin, which a page's script cannot change, so another site's page is charged). That is a soft check, not a lock: a program outside a browser can send the same header and save the price, which is why the price is small. A per-plan payment is not offered on purpose: QPayhub keeps at least 100 QU of every payment and a payment takes about ten seconds, so a 100 QU payment per call would lose all its value to the fee. A top-up of 10,000 QU buys 100 plans for a fee of about 1%.
• The website's pass is off. Build the site with VITE_REQUIRE_PASS=on to ask for it again (PAYWALL in src/config.ts sets its price).
• The sections below on the pass, prepaid API keys and x402 sessions describe those optional modes.

Fee model (from qubic/core Qx.h and Qswap.h; verify before trusting)

• QX: trade fee 0.3% (tradeFee 3,000,000 / 1e9), rounded up per match (floor(v*rate)+1). In the contract it comes out of the seller's QU proceeds, so the buyer pays no fee (the docs say "the party holding QUBIC"; check this). No flat fee on an order (checked on-chain on 2026-10-08: a bid attaches exactly price x quantity and fills for no more, e.g. 1,303 QMINE at 3,989 sent 5,197,667 QU and cost exactly that; an ask attaches nothing). The 100 QU asset transfer fee is charged only when management rights are moved between QX and QSwap, which is a step of its own.
• QSwap: swap fee 0.3% (swapFeeRate 30 / 10,000). Buys use QuoteExactAssetOutput (fee on QU in, rounded up); sells use QuoteExactAssetInput (fee deducted from QU out). The protocol/shareholder/QX shares are paid out of that 0.3% and are not extra. A flat 100,000 QU per-operation fee plus the asset transfer fee is modeled as QSwap's fixed cost.
• Fees, rounding and fixed costs live in QxConfig / QswapConfig, so they can be changed without touching the router.

HTTP API

Other DEX sites can call QMax over HTTP (no wallet or SDK needed): npm run api (env: PORT, SNAPSHOT, optional API_KEY).

GET  /v1/quote?side=buy&asset=DEMO&qty=100000[&split=false]

POST /v1/quote {"side":"sell","asset":"DEMO","qty":500} GET /v1/quotes?side=sell&asset=DEMO&qtys=1000,10000,50000 (several sizes at once; free access only) GET /v1/assets[?category=contract|token&q=CF] GET /v1/assets/search?name=CFB GET /v1/openapi.json GET /health

The quote response gives `route` (venue, qty, effective price, price impact, fees, QX depth used), `totalQu`, `fillable`, single-venue `alternatives` and `warnings`, and a plain-language `summary` (`src/quotesummary.ts`): the total, the average, where the order goes and what the split is worth, for an assistant that reads rather than computes. `GET /v1/quotes` (`src/quotesroute.ts`) prices up to 10 sizes of the same order from one reading of the markets and says how much worse each size is than the smallest (`averageVsSmallestPct`), so a bot can choose a piece size in one call; it is offered only with `API_ACCESS=free`, because a prepaid deployment bills each split quote and a batch would get around that. Every call that is limited per address carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (seconds), so a caller can slow down before it is refused with a 429 and `Retry-After`; and every error has a steady `code` (`bad_request`, `unauthorized`, `payment_required`, `not_found`, `rate_limited`, …) beside its sentence. CORS is open so browsers can call it directly; set `API_KEY` to require an `x-api-key` header. 

Asset list

GET /v1/assets returns every tradable asset (a QX book or a QSwap pool), most liquid first, each with id, symbol, issuer, category (contract = smart contract shares, token = everything else), venues, priceQu and liquidityQu. ready is false until the first network scan finishes; results are cached in .cache/catalog.json so restarts are instant.

src/catalog.ts builds the list: all contract shares (issued by the zero identity), the tokens named in assets.json, and the network's issuance list (which the RPC caps at 150 entries). A token that is not in the list can be added with GET /v1/assets/search?name=ABC, which looks the name up on the network, checks that it trades, and keeps it. If two issuers share a name the token gets an id like GARTH.PHOEN; the contract share keeps the plain symbol. Scanning is throttled (3 requests/s) and uses its own client, so it never slows a quote.

Activity filter

Each asset in GET /v1/assets has activity (active, inactive or unknown) and lastActiveAt. inactive means no QX order and no pool change within two epochs (14 days). src/activity.ts reads QX order history from the archive Query API (/query/v1/getTransactionsForIdentity, order types 5 and 6, in 100,000-tick windows, splitting any window that hits the 10,000-result cap). The first scan covers 14 days in a few minutes; after that only new ticks are read, and progress is kept in .cache/activity.json. The response also carries activity: { ready, progress } while the first scan runs.

Limits: this counts orders placed on QX (including market makers' orders), not completed trades. QSwap has no cheap history, so a pool counts as active when QMax has seen its reserves change since it started watching; a pool is only called quiet after 24 hours of watching, until then it is unknown and is not hidden.

Live data

npm run api serves live Qubic data (set ASSETS=file to use another seed file; it is a JSON list of token names or { symbol, issuer } objects; QUBIC_RPC_URL to change the RPC, default https://rpc.qubic.org). Without that file, or with SNAPSHOT=file set, it serves the demo snapshot and says so on startup.

src/live.ts reads, per asset, through /live/v1/querySmartContract:

• QX (contract 1): Fees (trade fee, transfer fee) and AssetAskOrders / AssetBidOrders, paged 256 at a time with offset up to 2,048 orders per side (a QX book has N+ orders warning appears if the cap is hit).
• QSwap (contract 13): Fees (swap fee, transfer fee) and GetPoolBasicState for the reserves. The flat 100,000 QU per-swap fee is the contract's QSWAP_ADDITIONAL_FEE.
• State is cached for 5 seconds per asset, and failed reads are retried and never cached.
• Each QSwap allocation is re-checked against the contract's own QuoteExactAssetOutput / QuoteExactAssetInput and reported as onChainCheck (differenceQu should be 0).

To always include a token, add its name to assets.json. A snapshot-backed or custom source can be used by implementing MarketData in src/data.ts.

Web app and wallet

web/ is a Vite + React app (npm run dev). The wallet code in web/wallet/ is ported from the connect module in double-k-3033/QRaffle-frontend, with the same four login options: MetaMask Snap, WalletConnect (including the existing WalletConnect project ID), private seed and .qubic-vault file, plus a fifth, the Qubic Wallet browser extension (qubic/wallet-extension, beta; it puts window.qubic on the page, web/wallet/extension.ts). QubicConnectContext.getSignedTx signs transactions for whichever method is connected. The extension signs with whichever account is active in it, so the signed bytes it returns are checked against exactly what was asked (account, destination, amount, tick, call and data: src/signedtx.ts) before anything is broadcast, and switching account or disconnecting inside the extension is followed on the page. A WalletConnect session and an extension connection are picked up again after a reload (a seed or vault was only ever in memory, so those start from the dialog). A phone puts the browser to sleep while the wallet app is open and may throw the page away, so a WalletConnect approval that arrives while the page is away is taken up when it comes back (the page remembers it started a pairing), the dialog looks again at once when the tab returns, and on a phone the button goes through QMax's own hand-off page (/open, the one the Discord bot uses).

Changes from the Qraffle module: the connect modal is plain React/CSS (no Tailwind or UI kit), the jotai balance store is dropped, a vault login reveals the selected account's seed so it can sign, and the wallet saved to localStorage never includes the private key (the original saved it in plain text).

The app quotes through the API (/api in dev is proxied to npm run api; set VITE_API_URL otherwise) and lists the assets the API serves. Start both with npm run api and npm run dev. Trying it on a phone (same Wi-Fi): npm run start:lan starts the API and the website and prints the address to open, for example http://10.0.0.4:5173. Only the website is shared with the network (it is the same dev server, which cannot read .env or .cache); the API stays on 127.0.0.1 and the website's server passes /api on to it. The page is plain http, so a phone browser treats it as an insecure context: browsing, chart