Qmax MCP Server

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, charts and the trade dialog work, but wallet connections that need HTTPS may not. A macOS firewall prompt for node has to be allowed, and a guest network that isolates devices will not work.

Look and feel. The interface is a trading terminal, not a landing page: flat charcoal panels with hairline borders, small system type with tabular numerals for every figure, one blue accent, an orange mark on the active tab, and green and red only for buy and sell. The logo is the supplied artwork (brand/qmax-logo-source.jpg): the letters "QMa" with the two-arrow X in place of the "x". The letters are a picture used as a CSS mask over the text colour (so they follow the theme), and the X is vector, which is also what is shown alone where there is no room for the whole logo (a phone's title bar, the favicon, the home-screen icon); npm run brand (scripts/make-brand.mjs, macOS) rebuilds web/public/brand, favicon.svg, favicon-32.png and apple-touch-icon.png from the artwork. It is one design system in web/style.css (colour, radius and font tokens at the top; dark and light themes, switched by the sun/moon button, remembered in this browser, following the system until chosen) with the workspace layout and dense overrides in web/styles/zz-terminal.css, which loads last. From 1000px wide the page is a workspace (between 1000 and 1260px the whole workspace is drawn at a smaller scale, useWorkspaceScale in web/media.ts, so a normal browser window shows the same three-panel layout rather than the phone one; the chart is counter-scaled so the pointer and crosshair stay exact): a title bar with the Trade, Orders, History, Pools and Swap screens, a market bar (asset counts and the latest trades), a watchlist on the left (Mine, Favorites, All, Contracts, Tokens; click a column heading to sort, and pick 24h, 72h or 7d beside Vol: the volume and the price-change column both follow that window), and the chart with its tools taking the middle and most of the width and height, in the arrangement of a trading platform like thinkorswim: assets on the left, a large chart in the centre, the latest trades on the right at the top and the order panel (side, amount, quote, readiness and the Buy or Sell button) on the right underneath them. The chart is the first thing anyone sees: until an asset is picked the centre is Qubic's own price chart (web/QubicDesk.tsx, the same chart and tools as every asset, from the MEXC and Gate.io candles) with the latest trades of every asset beside it and, under them, a Swap panel (the Swap section's form, QU for a token or a token for QU on QSwap, and one asset for another with Max on; compact mode of SwapPanel) where an asset's order panel would be The symbol at the top has arrows and a search to move to another asset without closing anything ([ and ] go to the previous and next by volume, / opens the search in the trade dialog), the "Hide order panel" strip puts the order panel away (remembered in this browser; the trades stay), and "Wide chart" hides the whole right-hand side for a still bigger chart. The dividers between the watchlist, the chart and the right-hand side can be dragged to resize them (double-click one to put it back, or focus it and use the arrow keys; web/Resizer.tsx and web/layout.ts: each width is kept in this browser, stays within limits and never leaves the chart narrower than a set minimum). The chart's own buttons (fit, latest, settings, picture, full screen) float over its top-right corner. The trades list has this asset's trades and a tab for every asset's (columns: time, side, quantity, price, QU, market; a time under an hour is shown as 4 min, with no "ago"). Below 1000px wide (a tablet, a phone) the same three columns are three screens in one row, swiped sideways, with a fourth for the portfolio past them (web/Pager.tsx, one scroll-snap row; the layout is the workspace's own components): Assets on the left (the markets: Favorites, All assets, Contracts and Tokens, with search, sort and filters), the Chart in the middle (it opens on this one, with Qubic's chart until an asset is picked, the symbol bar and figures pinned above whichever of the two right-hand screens is showing), Trades & order on the right (the latest trades with the order panel under them, or the Swap panel for Qubic), and Portfolio last (My assets with their worth and profit, Orders, History, Pools and Swap, the same tabs as the workspace's Portfolio, Orders, History, Pools and Swap pages). A strip along the bottom names the screen and a tap goes to another; picking an asset in the list slides to its chart, and a link that brings an amount opens at the order panel. A sideways touch drag on the chart swipes to the next screen instead of panning the chart (the chart pans with the mouse, pinch zooms it, and the buttons above it move it); an up-down drag scrolls the screen. Above the list, the tab bar comes first (on a phone in two rows, yours on top and the markets under them, so nothing scrolls sideways) and the search, the sort and the filters follow it as one group, the sort and the filters the same segmented control; on a phone the sort also holds the 24h, 72h or 7d menu that sets the window for the volume and the price change (a wide screen has it in the Vol column heading). The filters are a choice of one at a time (Both markets: assets that trade on QX and QSwap; Active: traded in the last 2 epochs; Arbitrage, part of Max), and picking the one that is on shows the whole list again. On a phone each asset is a compact row under column titles (Asset, Price, the 24h change, Vol: tapping a title sorts): star, logo, name with the market it trades on beneath it (QX, QSwap or both), price, the change and the volume; the grade, what it is and the "cheaper on" hint are in its chart's header. The whole row opens the asset, so there are no Buy and Sell buttons and no spread there. The latest-trades strip under the title bar slides slowly from right to left, new trades joining at the right edge; it stops under the pointer or with its pause button, and is a plain row you scroll by hand if your system asks for less motion. The pieces shared by every screen are in web/ui.tsx (icons, the QMax mark, an accessible Modal that closes on Esc and keeps focus inside, avatars, step markers) and the page frame (title bar, wallet menu with balance, market bar, status bar) in web/chrome.tsx. / focuses search. No web fonts are loaded, and the asset logos are copies served from QMax's own address (web/public/logos, saved from qubictrade.com by npm run logos; an asset with no logo of its own keeps a lettered badge; a round logo on a plain square, white or see-through at the corners, is looked at once it loads, and its badge is filled with the colour of the logo's rim with the picture cut to its disc, so no white corners show: src/logofill.ts, web/logofill.ts), so nothing is fetched from a third party to draw the page.

Limit orders. Each ticket has a Market / Limit switch. A limit order is a QX bid or ask at a price you choose: whatever already rests at that price or better matches at once (at the resting prices, never worse than yours) and the rest waits on the book until it fills or you cancel it under Orders. QSwap is a pool with no order book, so limit orders are QX only. The order is built in the browser from your own price, amount and the asset and issuer from the asset list (src/limit.ts) and checked against exactly that before it is signed (one bid or ask to QX, the right asset, price and units, a bid attaching price times units, nothing else); afterwards the wallet and book are read again and the result says what matched and what is waiting.

My assets: worth, cost and profit. The My assets tab (and the Portfolio page in the workspace) shows what each holding would really fetch if sold now: POST /v1/liquidation runs the whole holding through the router a real sale uses, so the depth of the QX book and the pool and every fee are in it (a holding the market cannot take in full is marked, and only what it can take is counted). Beside it are the average cost and profit or loss against that sale value, and when it was first bought, from the wallet's trade ledger for the last 365 days (src/portfolio.ts); units bought earlier or received from another wallet have a worth but no profit. Totals are also shown in dollars. What it costs the server, and why that stays small: pricing a sale reads the live order book and pool of each asset (about 10 to 15 seconds for 25 holdings, longer while the public node is limiting requests), and the same sale of the same asset is priced once and shared for two minutes between everyone who asks (LIQUIDATION_CACHE_SECONDS) (many wallets hold the same few shares), with at most three portfolios priced at once and a per-address limit; the page keeps the last pricing in the browser, shows it at once whenever My assets is opened again, and prices again only when it is 15 minutes old or when Refresh is pressed (the line under the figures says how old it is). The purchase history is the expensive part (it reads the public archive, which limits how often it is asked), so a wallet's ledger is built once and reused for five minutes by everyone (LEDGER_CACHE_SECONDS), only two are built at once (the rest are told to ask again in a few seconds and do, automatically), a wallet's history is kept in the browser for fifteen minutes, and when the archive says it is rate limiting no new ledger is started for 30 seconds.

Looking at a wallet without connecting it. Some people will not connect a wallet to a site they have just found, and everything the portfolio shows is public on the Qubic network. So every portfolio screen (My assets, Orders, History, Pools) has a box to paste an address into (web/ViewWallet.tsx, web/viewwallet.ts): the address is taken from whatever was pasted (the 60 letters, in either case, or a link to an explorer page) and its last four letters, a checksum, are checked, so a typo is refused with a sentence instead of showing an empty wallet. The portfolio then shows that wallet's holdings (worth if sold now, cost, profit), open orders, trade history and pool positions, under a line saying whose it is and that it is read-only, with Change and Stop viewing. Nothing for a wallet looked at this way can be signed: the Buy, Sell and Swap buttons become Open, orders cannot be cancelled, pool positions have no Add or Remove, and Swap says it needs your own wallet. The address is remembered in this browser (qmax.view) until the person stops, and connecting a wallet of their own ends it. It is read straight from the public node and QMax's ledger API, the same as for a connected wallet.

Max, and QMax Pro. Normal Buy and Sell are ordinary orders, and every one of them already goes at the best route (the router prices each market alone and a split, and takes the cheapest). Max is the part that searches for the best position for a trade (how to execute it, what size, an arbitrage between the two markets, and the best exit for what is held). It is one switch, Max mode, in Settings, and it is served by GET /v1/max. The Max planner is not part of this repository: src/maxplan.ts keeps its types (the shape of a plan, as the API documents it) and a stand-in that says so, and the pass logic behind it (src/pro.ts, src/proapi.ts, src/procover.ts) are stand-ins that make Max free. QMax's own server runs the real ones.

The welcome window (web/WelcomeModal.tsx) opens when the site loads: a few plain lines on what QMax does (free for everyone, you keep your keys), a Support QMax button (web/SupportModal.tsx: the support address, a QR code with the QMax X in it, a Copy button) and a "Don't show this again" box (kept in this browser).

Live prices. The list is read again every 20 seconds while the page is in view (and at once when it comes back into view), and so is the open asset's header. Prices are drawn from QX. Every asset trades on QX (a QSwap pool is an extra market beside it, never the only one), so there is always a QX price: the price of the asset's newest QX trade when that is recent (within 7 days). A QSwap pool is only a reserve ratio and stays put when nobody trades against it (QMINE's said 4,157 for days while QX traded at 3,994), and the middle of a thin QX book can sit far from every trade (QSILVER's was 3.65 million against a last trade at 100,001). An older trade may no longer be where the market is (QEARN's, 146 days ago, was above today's best ask), so it is kept inside the current QX bid and ask; an asset with no QX trade takes the middle of its QX bid and ask. GET /v1/assets puts that price in priceQu and also gives lastPriceQu (the raw trade), lastTradeAt, bookPriceQu (the order-book or pool price) and probedAt (when the books were last read, every 10 minutes, to spare the public node); the trade list is read every 15 seconds on the server and the website's list every 20 (src/api.ts priceFromQx, src/liveprice.ts). The trades list and the ticker poll every few seconds, the Qubic dollar price every minute.

All, and Max. A button that fills in everything you have (all of a token you hold, all the QU you can put into a pool) says All. Max is reserved for QMax's search for the best position, and for swapping one asset for another.

What Max mode unlocks beyond the search. The ordinary trading screens are the same with Max off. These are part of Max (src/chartaccess.ts lists the free set): the market each trade in the recent-trades lists was on (with Max off its place holds a dash), the notice of which market is cheaper (on each row of the list, and the QX-against-QSwap comparison in the trade panel; with Max off a row only says there is a cheaper price), the arbitrage flags (the ARB tag on a row, the Arbitrage filter and its count, the Arbitrage figure in the market bar, and the live arbitrage check in the trade panel; with Max off the tag, the filter and the figure are muted teasers that switch Max on, the filter is ignored and the live check is not made, and the arbitrage limits in Settings apply while Max is on; the API's /v1/arbitrage stays as it was), and most of the chart. The chart is free with candles and the line, every range, every candle width (automatic, 1, 5, 15 and 30 minutes, 1 and 4 hours, a day), volume, the 20-candle average, the linear axis, the market choice, a trend line and a horizontal line, fit, full screen, and a picture at screen size. The other chart styles, the other indicators, epoch marks, filling gaps, the log and percent axes, the chart settings panel, pictures bigger than the screen and the other drawing tools are marked in words ("part of Max" in a tooltip, and "· Max" on a choice), and picking one while Max is off switches Max on. There are no little marks on Max features any more, since Max is free. A choice made while Max was on is kept and comes back with it.

The trade card. When a market order, a limit order or a swap is signed, a card at the top of the dialog follows it (src/tradecard.ts, web/TradeCard.tsx): a bar with a part for each step and one for the wallet check, what it is waiting for (your wallet, the chain, the check), how long it has taken and how far along it is. The whole dialog is outlined by how it is going: a steady blue outline while it is under way, a green outline and a bounce when the wallet confirms it went through, a red outline and a sideways shake when a step failed (or the order was refused before anything was signed), and amber, still, when it needs a look (part of it done, or nothing moved yet). Nothing moves for anyone whose system asks for less motion; the colours stay.

The price of QU. The middle of the title bar always shows QU in dollars and how it moved in 24 hours; clicking it opens the same chart any asset has (candle styles, intervals from a minute to a day, indicators, drawing tools, epoch lines, volume, chart settings, saving a picture), drawn in dollars for one million QU because one QU is worth a tiny fraction of a cent (GET /v1/qu, /v1/qu/candles). The price is the checked median of five sources, the same one that prices the Discord subscription (bot/price.ts); the market figures are CoinGecko's, and the candles are the QUBIC/USDT market on MEXC (Gate.io if MEXC cannot be reached; USDT counted as a dollar), up to 5,000 per answer and read in 500-candle pages. MEXC lists QU from 17 July 2024; for a longer range at 4-hour or daily candles the days before come from Gate.io, where QU first traded on 9 May 2024 (Gate.io will not give hourly or finer candles that far back, and no free source has an earlier price). CoinGecko's free plan only reaches back a year, so it supplies the market figures and the one-year-or-less candles of /v1/qu/candles without interval. Everything is kept for a minute to a few minutes, per range and width, so a crowd of people opening the chart makes the server ask the exchange a handful of times, not once each. /v1/qu/candles without interval still gives CoinGecko's own candles.

Chart settings. The gear on a chart opens settings for the colour scheme, a flat or gradient background, candle, wick and line colours, hollow candles, line thickness, grid, volume strength, typeface and text size. They are kept in this browser, checked again when read back (src/chartstyle.ts), and used by saved pictures too. Epochs (Wednesday 12:00 UTC, src/epochs.ts) can be marked on any candle chart.

Trading

src/exec.ts turns a quote into the ordered transactions the wallet signs. The quote API returns each leg's limits in route[].execution (set with slippageBps, default 100 = 1%), so any front end can build the same transactions:

ExecuteModal re-quotes right before signing, warns if the price moved, checks the wallet balance (buys) and share holdings (sells), then signs, broadcasts and waits for each transaction in turn (web/exec/), stopping at the first failure. The API only returns execution hints when it serves live data.

After the trade, ExecuteModal re-reads the wallet (src/verify.ts): it compares QU balance and share holdings with a baseline taken at signing time and reports shares filled vs requested, QU actually spent or received (venue fees included), the real price and how far it was from the quote, plus any QX orders still resting on the book (and the QU locked in them). Open QX orders are read with EntityBidOrders / EntityAskOrders.

Used with real funds. Trades made on the website have been signed, broadcast and confirmed on mainnet: QX trades, QSwap swaps and QSwap liquidity changes. The usage record (GET /v1/stats, see Usage tracking) checks every trade it counts against the chain, so the count is a measurement, not a claim. Payload layouts and transaction sizes are also unit-tested against the contract source and the Qubic library. The Discord bot and the agent SDK build the same transactions with the same code, but have had less real-money use than the website: start with a small amount (for an agent, the dry run, agentPlan). Try a tiny trade first with anything new. Known limits: a QX bid that is not fully matched stays on the book as an open order, and balances can take a few ticks to update, so the result check may need a moment.

Market comparison, arbitrage, orders and trade-ready

• Price comparison (src/arbitrage.ts, comparePrices): for assets on both QX and QSwap, per-unit buy and sell prices after the 0.3% fees, shown on the card ("buy 5% cheaper on QSwap") and in the trade panel (both part of Max mode).
• Arbitrage flag (findArbitrage): looks for a buy on one market and sell on the other that ends with more QU after every fee (QX's 0.3%, QSwap's 0.3% and flat 100,000 QU, QMax adds nothing), the pool's price impact, and the depth of the top of the QX book. An ARB pill marks any asset where it finds one, there is an Arbitrage filter, and the trade panel explains it. It is only a snapshot: the two legs are separate transactions, and QMax does not execute arbitrage for you.
• Live arbitrage check (GET /v1/arbitrage?asset=ID, findArbitrageVenues): the card flag comes from cached top-of-book data (up to 10 minutes old), so the trade panel re-checks against the live full order book and pool before showing anything. At the time of writing none of the 16 two-market assets had one.
• Settings (gear in the header, src/settings.ts, web/settings.tsx): default slippage (capped at 10%), hide quiet assets, default sort, short or full prices, and the arbitrage filters (see below). Stored in the browser's localStorage; invalid stored values fall back to defaults.
• Open orders (src/verify.ts fetchAllRestingOrders, web/OrdersPanel.tsx): lists the wallet's resting QX bids and asks across all assets and cancels them with RemoveFromBidOrder / RemoveFromAskOrder (buildCancelStep in src/exec.ts). Cancelling is free, and a cancelled bid returns its locked QU.
• Trade-ready checklist (src/readiness.ts): before Review is enabled, the panel checks wallet connected, enough liquidity, enough QU for the fees (also when selling), shares in the right contract (or the extra move step it needs), and warns about quiet markets and fee-heavy trades. Failures block the trade, warnings do not.

Documentation truncated — see the full README on GitHub.