# swap — full agent context > DEX meta-aggregator (CLI + web dApp) that races major EVM DEX aggregator APIs, ranks quotes, and builds executable swap transactions or EIP-712 intent orders. Public deployment: https://swap.9summits.io. Copyright 9Summits. This file expands [/llms.txt](https://swap.9summits.io/llms.txt) with enough detail for an agent to use the product and HTTP API without scraping the SPA. ## What swap is - **Not a DEX.** It does not hold liquidity. It queries third-party aggregators/solvers and presents the best route. - **Two UIs, one engine.** The browser dApp and the `swap` CLI share quote ranking and build logic (composition layer + venue adapters). Locally, `swap` with no args serves the dApp; with args it runs the CLI. - **No telemetry** in the CLI binary description; no separate SaaS account system on the public host. - **Public dApp has no session gate** (unlike the local CLI, which can use a session `?id=` token). Calls consume the host’s venue/RPC API quotas. ## Agent quickstart 1. Read https://swap.9summits.io/docs.md (CLI manual) or install the skill at https://swap.9summits.io/skills/swap-cli/SKILL.md. 2. Install: `curl -fsSL https://swap.9summits.io/install.sh | bash` (macOS/Linux, arm64/x64; binary in `~/.local/bin`). The binary is **hosted by default** (`SWAP_API_URL=https://swap.9summits.io` baked in): it quotes and builds through this host's `/api/*`, so every venue works with zero key configuration and no RPC except `--simulate`. 3. Configure through env only, and only if self-hosting with `--local`: `ALCHEMY_API_KEY` (or `RPC_URL_`), `SENDER_ADDRESS`, optional venue keys. The CLI never prompts when stdin/stderr is not a TTY; `--init` exits 1 instead of hanging. 4. Quote with `swap 1 WBTC ETH --json`; build with `--from 0x… -d --json`; dry-run with `--simulate`. Exit code 0 on success, 1 on any error (`{"error": "…"}` on stdout under `--json`, message on stderr). 5. Prefer the binary. If you must call HTTP, the contract is in https://swap.9summits.io/openapi.json — public host or the local `swap` server (`SWAP_NO_AUTH=1` to drop the `?id=` gate, `NO_BROWSER_OPEN=1` on headless machines). ## Hosted mode (CLI) The `swap` CLI resolves its backend in this order: `--local` > `--hosted` > `SWAP_API_DISABLED=true` > `SWAP_API_URL` env var > local engine. `--hosted` forces this host (`https://swap.9summits.io`) for one run; `--local` forces the local venue engine (the user's own keys and RPC) even when `SWAP_API_URL` is set. `SWAP_API_DISABLED` (default `false`) does the same persistently from the environment, so the URL embedded in the public binary can be opted out of without clearing it; it accepts `1`/`true`/`yes`/`on` and `0`/`false`/`no`/`off`, and any other value is a hard error. The public prebuilt binary embeds `SWAP_API_URL=https://swap.9summits.io`, so it is hosted unless the user opts out. In hosted mode the CLI never signs anything (unchanged from local mode): it renders whatever the API returns. `--nofee` is refused (fee policy is server-side, not the client's to zero); the venue list is whatever `GET /api/mode` reports (this host omits `curve`); a `GET /api/mode.apiVersion` mismatch with the CLI's expected version fails with "hosted API contract mismatch … run `swap update`" rather than degrading silently. `--simulate`, the local-only actions (`send`, `unwrapwrseth`, `withdrawsparkweth`, `unstakesavax`, `claimsavax`) and `swap loop` always run against the caller's own RPC, hosted or not (`swap loop` refuses `--hosted`). A rate-limited (429) or unreachable API fails loud, naming `--local` as the escape hatch, never falling back silently. `swap --show-mode` prints which backend the current configuration resolves to (`hosted ` or `self-hosted`) and exits, without quoting. ## Surfaces | Surface | How to use | |---------|------------| | Web dApp | Open https://swap.9summits.io/ — select chain, tokens, amount; quotes stream; connect wallet to execute | | CLI install | `curl -fsSL https://swap.9summits.io/install.sh \| bash` → binary `swap` in `~/.local/bin` | | CLI update | `swap update` — replace the installed binary with the latest public prebuilt (same Blob assets as the installer) | | CLI quote | `swap 1 WBTC ETH` — ranks venues by amountOut (Fusion: auction-end min) | | CLI comparison | `swap 1000 USDC USDT -v all` | | CLI build | `swap 100 USDC USDT --from 0x… -d` — calldata + allowance | | CLI simulate | `swap 100 USDC USDT --from 0x… --simulate` — `eth_simulateV1` with pranked balance | | CLI browser sign | `swap 0.1 WETH USDC --from 0x… --browser` — local RainbowKit page | | CLI exact-out | `swap 1000 USDC WETH --exact-out` — amount is tokenOut; minimize tokenIn | | CLI send | `swap 100 USDC -a send --to 0x… --from 0x… -d` — transfer, no DEX | | CLI wrap | `swap 1 ETH WETH -d --from 0x…` — direct WETH9 deposit/withdraw, no venue (displayed as `9summits`; `--json` keeps `"venue": "wrap"`) | | CLI loop | `swap loop 1000 usdc --market fxsave-usdc --leverage 3 --from 0x… -d` — leveraged fxSAVE/USDC position on Morpho Blue in one tx (local engine, own RPC); `--chain base\|robinhood\|monad\|arc --market 0x` for a Morpho market on another chain | | dApp Loop tab | https://swap.9summits.io/?action=loop — same loop engine in the browser (Beta), on the header's chain; a market picker over the 20 Ethereum markets plus a search of each chain's Morpho-listed markets, `&market=` with `&chain=` in the URL | Platforms for the one-shot installer and `swap update`: macOS (arm64, x64), Linux (arm64, x64). Env: `SWAP_INSTALL_DIR`, `SWAP_INSTALL_BASE`. ## Chains Aliases (CLI `--chain` / API `chain` field): | Alias | Network | Native | |-------|---------|--------| | `eth` | Ethereum mainnet | ETH | | `arb` | Arbitrum One | ETH | | `base` | Base | ETH | | `op` | Optimism | ETH | | `avax` | Avalanche C-Chain | AVAX | | `bsc` | BNB Chain | BNB | | `hype` | HyperEVM | HYPE | | `unichain` | Unichain | ETH | | `robinhood` | Robinhood Chain | ETH | | `arc` | Arc | USDC | | `monad` | Monad | MON | | `plasma` | Plasma | XPL | | `polygon` | Polygon | POL | | `gnosis` | Gnosis | XDAI | | `ink` | Ink | ETH | Native token is represented internally as the sentinel address `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` (adapters translate at venue boundaries). Arc is the exception: its gas token is USDC, reachable only as the ERC-20 at `0x3600000000000000000000000000000000000000` (6 decimals), and the sentinel is rejected there. Token symbols or `0x` addresses are accepted; decimals must be resolved correctly (never assumed to be 18). ## Venues **Sync** (broadcastable tx): `kyber`, `velora`, `matcha` (0x), `1inch`, `curve`, `uniswap`, `openocean`, `fynd`, `9summits`. `odos` / `odosv2` are discontinued. **`9summits`** is the in-house route, for USDC → fxSAVE, fxUSD → fxSAVE and fxSAVE → any token on Ethereum only. On any other pair it is absent from the race (no error row); an explicit `-v 9summits` or `/api/route` / `/api/build` there fails with "9summits only quotes USDC or fxUSD → fxSAVE, or fxSAVE → any token, on Ethereum". It builds one Bundler3 multicall. fxUSD is deposited straight into fxSP. USDC is split like the Loop's deposit into a gas-gated USDC → fxUSD swap, sized on the Curve pool's marginal rate against fxSP's USDC credit, and a direct fxSP deposit for the rest. The swap runs on the best of kyber / velora / matcha / 1inch / openocean / fynd with fxUSD delivered to GeneralAdapter1, or on the Curve pool when it is at least as good. All fxSP goes into fxSAVE for the sender, and fxUSD the swap delivers above what was deposited is returned to the sender. `tx.to` = Bundler3, `tx.spender` = GeneralAdapter1, `value` = 0. Partner fee only on the swap leg (the leg venue's normal `REFERRAL_FEE_BPS`, 0 on the Curve pool); no loop surcharge. The reverse, fxSAVE → any token (native ETH included) except fxSP, redeems through fxSP's instant redeem and sells the fxUSD and USDC it returns on aggregators only (never the Curve pool), in one multicall. f(x) charges a 1% instant-redemption fee, shown on the row as `Incl. 1% f(x) redemption fee — 1h cooldown avoids it`; ranking is net of gas. **Async / intent** (sign EIP-712 + POST off-chain; filler settles on-chain): `cow`, `delta`, `uniswapx`, `fusion` (and related such as Ophis when configured). CLI requires `--allow-async`. Output is an order payload, not a simple unsigned swap tx. **Exact-out / buy-capable** (minimize tokenIn for a fixed tokenOut): `velora`, `matcha`, `uniswap`, `cow`, `ophis` have a native buy path; the dApp exposes that set as `buyVenues` from `GET /api/mode`. In a multi-venue race, sell-only venues (including `9summits` on its pairs) are re-quoted exact-in at the best native pay and must still deliver the target; a sell-only venue selected alone is rejected. **Availability by chain** (✓ served, · not; snapshot of the CLI adapters, live set per deployment in `GET /api/mode`): | Venue | eth | base | arb | op | unichain | bsc | avax | hype | robinhood | arc | monad | plasma | polygon | gnosis | ink | |---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:| | `kyber` (sync) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | · | | `velora` (sync) | ✓ | ✓ | ✓ | ✓ | · | ✓ | ✓ | · | · | · | · | · | ✓ | ✓ | · | | `matcha` (sync) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | · | ✓ | | `1inch` (sync) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | ✓ | ✓ | · | | `curve` (sync) | ✓ | ✓ | ✓ | ✓ | · | · | ✓ | · | · | · | · | · | · | ✓ | · | | `uniswap` (sync) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | ✓ | ✓ | ✓ | · | ✓ | · | ✓ | | `openocean` (sync) | ✓ | ✓ | ✓ | · | · | ✓ | ✓ | · | ✓ | ✓ | · | · | ✓ | ✓ | · | | `fynd` (sync) | ✓ | ✓ | ✓ | · | ✓ | ✓ | · | · | ✓ | · | · | · | ✓ | · | · | | `9summits` (sync) | ✓ | · | · | · | · | · | · | · | · | · | · | · | · | · | · | | `cow` (intent) | ✓ | ✓ | ✓ | · | · | · | · | · | · | · | · | · | ✓ | ✓ | ✓ | | `ophis` (intent) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | ✓ | · | · | ✓ | ✓ | ✓ | ✓ | | `delta` (intent) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | · | · | · | · | ✓ | · | · | | `uniswapx` (intent) | ✓ | ✓ | ✓ | · | ✓ | · | · | · | · | · | · | · | · | · | · | | `fusion` (intent) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | ✓ | · | ✓ | · | ✓ | ✓ | · | | *venues per chain* | 14 | 13 | 13 | 9 | 9 | 10 | 10 | 2 | 8 | 5 | 5 | 3 | 11 | 7 | 4 | Venue availability depends on server env keys (e.g. `ZEROEX_API_KEY`, `ONEINCH_API_KEY`, `UNISWAP_API_KEY`, `FYND_API_KEY`; optional `KYBER_API_KEY` moves kyber to its higher-limit API gateway; optional `OPENOCEAN_API_KEY` moves openocean to its pro host) and `SWAP_DISABLE_VENUES` (production often disables `curve` because cold init is slow on serverless). ## Short-circuit actions (no aggregator) - **Wrap / unwrap:** native ↔ wrapped pair → direct `deposit()` / `withdraw()` on the chain’s wrapped-native contract. Displayed as 9summits (CLI `venue` / `via` lines, dApp 9Summits label and mark); `--json` and the API keep `"venue": "wrap"`. - **Send (`-a send`):** ERC-20 `transfer` or native value transfer to `--to`; no allowance for transfer path. ## Loop (Morpho Blue leverage, fxSAVE/USDC) `swap loop usdc --market fxsave-usdc --leverage ` opens a leveraged fxSAVE position on Morpho Blue, or adds to an open one, in one transaction. Loop chains: Ethereum (default), Base, Robinhood, Monad, Arc (`--chain`). The 20 aliases are fork-tested Ethereum markets; `--market` also takes any Morpho market id on the chain, read from that chain and the Morpho API, entered with one loan token → collateral swap, and simulated (`eth_simulateV1`) before it is built: a route that reverts or delivers under the plan's floor is rebuilt through the next venue. Base's Morpho has Ethereum's address, so an id is only read on the chain passed. This section details `fxsave-usdc` (fxSAVE collateral, USDC loan, LLTV 91.5 %, market id `0x17f7ae1b52670010976b3fe41324cbb2b1eb7dd8f492e51764b2828371b86b84`); `--market` also takes 19 other stable markets (`swap loop --help`), which buy the collateral with one aggregator swap from the loan token. Their entry cost cap is also 25 bps of the oracle value, except `pt-fxsave-29oct2026-usdc` at 2 %: its oracle values the PT about 1.6 % under its market price, which lowers its max leverage (about 7.6x instead of 8.6x at the default max LTV). The dApp exposes it as the **Loop** tab (Beta, `/?action=loop`), with a picker over the 20 markets (`&market=`). Full manual: https://swap.9summits.io/docs.md (section 08). - **Engine is always local.** Loop reads Morpho, fxSP and Curve on the caller's RPC and builds the bundle itself, even when `SWAP_API_URL` is set; `--hosted` is refused. Every run, including a plain plan, needs an RPC for the loop's chain (`ALCHEMY_API_KEY`, `RPC_URL_` or `--rpc`); a market resolved from its id also needs `eth_simulateV1` there to build. Morpho / Bundler3 / GeneralAdapter1 per chain: Ethereum `0xBBBBBbbBBb9cC5e90e3b3Af64bdAF62C37EEFFCb` / `0x6566194141eefa99Af43Bb5Aa71460Ca2Dc90245` / `0x4A6c312ec70E8747a587EE860a0353cd42Be0aE0`; Base `0xBBBBBbbBBb9cC5e90e3b3Af64bdAF62C37EEFFCb` / `0x6BFd8137e702540E7A42B74178A4a49Ba43920C4` / `0xb98c948CFA24072e58935BC004a8A7b376AE746A`; Robinhood `0x9D53d5E3bd5E8d4Cbfa6DB1ca238AEA02E651010` / `0x6478e9393d4C5bB4d53ee881d1DE78786A0344a6` / `0xc5E188541D107e8B79e43478bDE365F1406665D6`; Monad `0xD5D960E8C380B724a48AC59E2DfF1b2CB4a1eAee` / `0x82b684483e844422FD339df0b67b3B111F02c66E` / `0x725AB8CAd931BCb80Fdbf10955a806765cCe00e5`; Arc `0x34CD04070dD72b14E241112F6d83812Df5Af7fCD` / `0x855dbe13C409Df75CAF6a985Cf6993a4D0319Feb` / `0x0AF5BE7BD7B615e94e1d9275414482D028952466`. - **Mechanics.** Bundler3 `multicall` → GeneralAdapter1 `morphoFlashLoan(USDC, flash)`. In the callback: flash USDC → fxSP (f(x) stability pool) as a direct USDC deposit and/or a USDC → fxUSD swap whose fxUSD is deposited → all fxSP into fxSAVE (ERC-4626, max share price) → fxSAVE supplied as Morpho collateral for the sender → USDC borrowed (skipped at 1x) → equity pulled from the sender (skipped for 0 USDC); borrow + equity repays the flash exactly. The swap pays its fxUSD to GeneralAdapter1, which hands Bundler3 the swap's min out for a hard fxSP deposit, then the rest of the built quote for a deposit skipped when the swap filled short; any fxUSD left on GeneralAdapter1 is swept back to the sender as fxUSD. Nothing stays on Bundler3 or GeneralAdapter1. - **Sizing.** Fresh position: flash = equity × leverage, borrow = flash − equity. Open position (sender has collateral or debt): `--leverage` is the whole position's target; with C collateral value, E = C − debt, N new USDC: flash = (E + N) × L − C, borrow = flash − N. The target cannot be below (C + N) / (E + N), the position with N added and nothing borrowed; with `0 usdc` it must be above the current leverage. Lower targets need an unloop and are refused. - **Risk numbers.** LTV = debt / collateral value at the Morpho oracle, on the minimum fxSAVE the hard deposits (direct USDC and the swap's min out) guarantee under the slippage bounds. Health factor = LLTV / LTV. Liquidation price = USDC per fxSAVE where LTV hits LLTV. Default max LTV = LLTV − 3 % (88.5 %); `--max-ltv` accepts up to LLTV (0.915, health factor 1, liquidatable once interest accrues). Max leverage ≈ 1 / (1 − max LTV) before entry cost, also capped by the market's available USDC; the plan reports it at the requested max LTV (`maxLeverageBps`), at the default (`safeMaxLeverageBps`) and at LLTV (`lltvMaxLeverageBps`). - **Refusals** (no tx built): LTV above max LTV, borrow above available liquidity, fxSP entry cost above 25 bps of the oracle value, `--max-ltv` above LLTV, 0 USDC without an open position, a target below the position floor. The message carries the reachable max leverage when there is one. - **Entry optimiser.** If the Curve USDC/fxUSD marginal rate beats fxSP's USDC credit (`getStableTokenPrice`), the engine bisects for the largest amount still worth swapping and keeps the swap only if its gain beats ~170k gas with a 50 % margin. That amount is quoted on the aggregators whose build can pay GeneralAdapter1 (KyberSwap, Velora, 0x/Matcha, 1inch, OpenOcean, Fynd) and on the Curve pool's own `exchange`; the higher output wins, the pool on a tie (`optimiser.venue` = `curve`). The winner is rebuilt with Bundler3 as sender and GeneralAdapter1 as recipient; if no aggregator builds, the pool is used. Otherwise the whole flash is a direct USDC deposit. `optimiser.executed`, `optimiser.venue` and `optimiser.reason` report the decision. - **Fees.** The flash pays `LOOP_FLASH_FEE_BPS` (integer 0–1000, default 0) of itself in the loan token to `REFERRAL_ADDRESS`, reported as `fee` / `feeBps`; none on the deposits or the borrow. The embedded swap pays `REFERRAL_FEE_BPS` + `LOOP_SWAP_FEE_SURCHARGE_BPS` (default 1 bp, integer 0–1000), capped at 1000 bps, on fee-taking venues (KyberSwap, Velora, 0x, 1inch, OpenOcean); 0 on Curve and Fynd, without `REFERRAL_ADDRESS`, or under `--nofee`. Reported as `optimiser.feeBps`. - **Preflight.** USDC `approve(GeneralAdapter1, equity)` when the allowance is short (none for 0 USDC), and Morpho `setAuthorization(GeneralAdapter1, true)` once. Multicall `tx.to` = Bundler3, `tx.spender` = GeneralAdapter1 (the USDC approval target). On the authorization step `to` = Morpho and `spender` names the authorized adapter, not an ERC-20 spender. - **Exit.** `swap unloop --market fxsave-usdc` (or `/api/loop/unwind/*`) unwinds the position. On the fxSAVE market the sale also races `fxsave-redeem` (fxSAVE → fxSP → fxUSD + USDC through f(x)'s 1% instant redeem, then aggregator legs); the better net of gas wins, `-v fxsave-redeem` forces it, and the exit-cost cap leaves that disclosed fee out, up to 1% of the sale (any excess counts). `--leg-venue ` (API body `legVenue`) sends that exit's fxUSD → loan leg through one aggregator when it quotes it; the fxsave-redeem route row carries `legChoice` like the Swap's 9summits row. - **CLI flags.** `--market` and `--leverage` required; `` in human USDC, `max` = sender's USDC balance, `0` = flash-only top-up; `--max-ltv `; `--slippage-bps ` (default 10; bounds fxSP deposits, fxSAVE share price and swap min-out); `--chain eth|mainnet|base|robinhood|monad|arc` (default eth); `--from` / `-w` / `SENDER_ADDRESS` required for `-d`, `--json`, `--simulate`, `--browser`, `max`; `--json` builds (plan + `preflight` + `tx`, plus `simulation` under `--simulate`); `--browser` sends preflight then multicall; `--nofee`; `--rpc`. `--json` and `--browser` are exclusive. Simulation exits 1 on a revert. - **`--json` shape.** `action: "loop"`, `market`, `marketId`, `chainId`, `sender`, `equity`, `leverageBps`, `flashTotal`, `fee`, `feeBps`, `feeRecipient`, `depositAmount`, `usdcLeg`, `borrowAmount`, `expectedFxSp`, `expectedFxSave`, `collateralValue`, `ltvBps`, `maxLtvBps`, `lltvBps`, `healthFactorWad`, `liquidationPrice`, `maxLeverageBps`, `safeMaxLeverageBps`, `lltvMaxLeverageBps`, `borrowApyWad`, `borrowApyAfterWad`, `position`, `forward`, `fxSaveApyWad`, `loopApyWad`, `availableLiquidity`, `oraclePrice`, `entryCostBps`, `slippageBps`, `exitWarning`, `optimiser`, `swapGraph`, `preflight`, `tx`. `swapGraph` is null when the plan does not swap; otherwise it is the embedded swap's symbol-labelled hops, the same shape as POST /api/route. Amounts are base-unit strings (USDC 6 decimals, fxSP / fxSAVE 18), leverage and LTV bps, rates and health wad (1e18 = 100 % or 1.0); `loopApyWad` can be negative. - **Contracts.** Morpho Blue `0xBBBBBbbBBb9cC5e90e3b3Af64bdAF62C37EEFFCb`, Bundler3 `0x6566194141eefa99Af43Bb5Aa71460Ca2Dc90245`, GeneralAdapter1 `0x4A6c312ec70E8747a587EE860a0353cd42Be0aE0`, fxSAVE `0x7743e50F534a7f9F1791DdE7dCD89F7783Eefc39`, fxSP `0x65C9A641afCEB9C0E6034e558A319488FA0FA3be`, fxUSD `0x085780639CC2cACd35E474e71f4d000e2405d8f6`, USDC `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`, Curve USDC/fxUSD `0x5018BE882DccE5E3F2f3B0913AE2096B9b3fB61f`. ## HTTP API (public host) Base: `https://swap.9summits.io` Contract is **stateless**: every call carries full inputs; `quoteId` is a client round key only. Local CLI may require `?id=`; production typically does not. ### GET /api/mode Bootstrap for the SPA. Response fields (conceptual): `interactive`, `sid`, `chains`, `venues`, `buyVenues`, `defaultChain`, `walletConnectProjectId`. ### GET /api/tokens?chain= Curated token list for the chain (native first). Used by the dApp token picker. ### POST /api/resolve-token Body: `{ "chain": "eth", "input": "WBTC" }` or a `0x` address. Returns: `{ address, symbol, name, decimals }`. Fail loudly if decimals cannot be resolved. ### POST /api/quote Body (conceptual): ```json { "chain": "eth", "tokenInAddress": "0x…", "tokenOutAddress": "0x…", "amountIn": "1000000", "slippageBps": 10, "allowAsync": false, "venues": null } ``` Use **either** `amountIn` **or** `amountOut` (XOR). With `amountOut`, only buy-capable venues participate. Amounts are base units (stringified integers), not human floats. Optional `sender` (EIP-55 address) is the taker for indicative quotes (CoW `from`/`receiver`); omit when unknown. Returns ranked quotes (best first for the active side). Server ranking is **gross** variable-leg amounts. Fusion routes may include `minAmountOut` (Dutch-auction floor); ranking uses that instead of the headline `amountOut` when present. The serverless path does not fetch CoinGecko. Each route includes `gasUnits` and `gasPriceWei` so a client with spots can reorder net-of-gas. ### POST /api/quote/stream Same body as quote. Response: **NDJSON** lines — `meta`, then per-venue `route` or `verror`, then `done`. Stream order is unsorted. Each `route` includes `gasUnits` and `gasPriceWei`. Clients with CoinGecko prices may reorder net-of-gas. Prefer this for multi-venue UX. ### POST /api/route Re-quotes a single venue and returns symbol-labelled hops for route visualization. Invalid/disabled venues are rejected. ### POST /api/build Re-quotes the chosen venue (quotes go stale quickly), checks allowance when needed, returns a **Payload**: - `kind: "tx"` — broadcastable transaction fields (`to`, `data`, `value`, gas hints, spender for approval) - `kind: "order"` — EIP-712 typed data + submit URL for intent venues - `kind: "permit-tx"` — Permit2 first leg + `assembleContext` for `/assemble` **Critical:** the address that needs ERC-20 approval is `tx.spender` (or equivalent payload field), **not** always `tx.to` (Velora’s spender can diverge; `9summits` has `tx.to` = Bundler3 and `tx.spender` = GeneralAdapter1). Optional flags mirrored from CLI: `odosNotCompact`, `disableOdosRfq`, `veloraMethods`, `legVenue`. `veloraMethods` (on `/api/quote`, `/api/quote/stream`, `/api/route` and `/api/build`, CLI `--velora-methods`) only affects `velora`: an array (or comma-separated string) of Augustus v6.2 methods the route must use, e.g. `["swapExactAmountIn"]`, sent to Velora as `includeContractMethods`. Velora's row becomes a per-venue error (`verror`) when it has no route under the constraint, answers with another method, or builds calldata whose 4-byte selector is not listed. An unknown method name is a 400 (Velora would ignore it and route freely). Every Velora route row carries `contractMethod` (e.g. `swapExactAmountInOnUniswapV3`); other rows omit it. `legVenue` (on `/api/quote`, `/api/quote/stream`, `/api/route` and `/api/build`, CLI `--leg-venue`) only affects the `9summits` fxSAVE exit: its fxUSD / USDC swap legs go through that aggregator (`kyber`, `velora`, `matcha`, `1inch`, `openocean`, `fynd`) when it quotes them all, else each leg takes its best quote. The `9summits` route row then carries `legChoice: {pinned, legs, options[]}`: the venue every leg went through (null when none was honoured), each leg's venue, and per aggregator the route's `amountOut` and `gasUnits` through it alone. Every other row has `legChoice: null`. ### POST /assemble Body: `{ "signature": "0x…", "context": }` — Permit2 second leg; returns the final tx to broadcast. ### POST /submit Authed async order submission (e.g. Fusion). Query params such as `venue`, `chainId`, `orderHash` are validated server-side; the relayer URL is reconstructed on the server (never trust a client-supplied relayer URL). ### POST /simulate · POST /done · GET/POST /tx Used heavily by the local `--browser` flow. On the public dApp, simulation may be skipped or limited; `/done` is an acknowledgment callback. ### POST /api/loop/quote · POST /api/loop/build Morpho Blue leverage loop, same engine as `swap loop`. Body: ```json { "chain": "eth", "market": "fxsave-usdc", "sender": "0x…", "equity": "1000000000", "leverageBps": 30000, "maxLtvBps": 9150, "slippageBps": 10 } ``` `chain` is `eth` (or `mainnet` / `ethereum`), `base`, `robinhood`, `monad` or `arc`; any other chain is a 400. `market` is an alias (Ethereum markets) or any Morpho market id on `chain`. `equity` is the market's loan-token base units as a string (`"0"` = flash-only top-up of the sender's open position). `leverageBps` is an integer (30000 = 3x); on an open position it is the whole position's target. `maxLtvBps` is optional (default LLTV − 300, max LLTV); `slippageBps` optional, integer, default 10. `sender` is optional for quote (omit it, or pass the zero address, to plan without any open position) and required for build. Quote returns the plan (the `swap loop --json` object with `preflight` and `tx` null). Build returns the `/api/build` Payload shape with `venue: "loop"`, `kind: "tx"`, `approval: null`, `preflight: [{kind: "approve" | "morpho-authorize", label, tx}]` to send in order before `tx` (the Bundler3 multicall), and `plan`. A refused plan or malformed body is HTTP 400 `{"error", "maxLeverageBps"}` (`maxLeverageBps` a bps string or null); other failures are 502 `{"error"}`. `GET /api/loop/markets?chain=` (default eth) is the dApp's market picker: `market=` answers `{market, stats}`, the market resolved on the chain with its APRs; `q=` answers `{hits}`, Morpho's listed markets of the chain whose tokens match, largest supply first; without either, one APR row per Ethereum registry market (`{"markets": []}` on another chain). Cached per chain. ### POST /api/loop/unwind/quote · /quote/stream · /build · GET /api/loop/positions Unwind the sender's Morpho borrow, same engine as `swap unloop` (local; the CLI refuses `--hosted`). Body for the three POSTs: ```json { "chain": "base", "market": "0x…", "sender": "0x…", "mode": "close", "receive": "loan", "slippageBps": 10 } ``` `sender` is required. `mode` is `partial` (integer `targetLeverageBps` ≥ 10000, no `receive`; 10000 repays every share and leaves the unsold collateral supplied) or `close` (`receive` `collateral` by default, or `loan`; no target). `venues` / `venue` are recipient venues only (`curve` is 400). The API does not accept a max exit cost. Quote returns the plan (`preflight` and `tx` null). The stream is NDJSON: `leg` (`amountIn`, `usdcIn`), `route` / `verror`, then `plan` (`expiresAt` 30s out) or `error` (`status` 400 or 502). Build returns the `/api/build` Payload with `venue: "loop"`, `tokenIn` the collateral, `tokenOut` the loan token, `amountIn` the collateral sold, `amountOut` the loan token quoted, `preflight` (`morpho-authorize` when needed) and `plan`. A malformed field or a refused plan is 400 `{"error"}`; other failures are 502. `GET /api/loop/positions?chain=&sender=
` returns `{positions}`, that wallet's Morpho borrows with debt on the chain, largest debt first. Cached 15s in-process per chain and sender. `cache-control: private, no-store`. An unknown wallet is `{positions: []}`. A Morpho API failure is 502. ### Rate limits (public host) Per-IP token buckets, refilled continuously, per minute: `quote` 60 (`/api/quote`, `/api/quote/stream`, `/api/route`, `/api/loop/quote`, `/api/loop/quote/stream`, `/api/loop/unwind/quote`, `/api/loop/unwind/quote/stream`), `build` 12 (`/api/build`, `/assemble`, `/api/loop/build`, `/api/loop/unwind/build`), `submit` 6 (`/submit`), `light` 120 (mode, tokens, resolve-token, icon, done, tx, `/api/loop/markets`, `/api/loop/positions`). When drained: HTTP 429, body `{"error":"rate limited, retry shortly"}`, `Retry-After` in seconds. Not applied on the local server. ### Error shape Every JSON error is `{"error": ""}` with a 4xx/5xx status (400 bad input or unsupported side, 429 rate limited, 502 upstream venue/RPC failure). ### Not provided There is **no** public `/api/balances` — balances are read client-side via the wallet or a public RPC so the host’s Alchemy quota is not an open hole. ## CLI flags (summary) | Flag | Meaning | |------|---------| | `-v ` | Venue filter; default races all available | | `--allow-async` | Include intent venues | | `--chain ` | Network | | `--slippage ` | Percent (default `0.1` = 10 bps); same value for quote and build | | `--exact-out` | Amount is tokenOut | | `--from ` | Sender; required for `-d`, `--simulate`, `--browser`, `max` | | `-d` / `--data` | Build calldata / order | | `--simulate` | `eth_simulateV1` with pranked balance | | `--browser` | Local wallet UI for sign/send | | `--json` | Machine-readable output | | `-s` / `--simple` | Print only the numeric variable leg | | `-a send` | Transfer instead of swap | | `swap loop usdc --market fxsave-usdc --leverage ` | Morpho leverage loop (fxSAVE/USDC and 19 other Ethereum markets, or any Morpho market id on `--chain` eth, base, robinhood, monad or arc); own flags (`--chain`, `--max-ltv`, `--slippage-bps`, `-d`, `--json`, `--simulate`, `--browser`), see Loop | | `--hosted` | Quote and build through this host's `/api/*` for this run, no venue key or RPC needed except `--simulate` | | `--local` | Force the local venue engine for this run even if `SWAP_API_URL` is set (`SWAP_API_DISABLED=true` does the same from the environment) | | `--show-mode` | Print the effective mode (`hosted ` or `self-hosted`) on stdout and exit, without quoting; honours `--hosted` / `--local` passed alongside | | `-V` / `--version` | Print the version and the commit the binary was built from (`swap 0.1.0 (2c02339, 2026-09-15)`) and exit, without quoting or any network call | ## Safety rules agents should respect 1. **Decimals are safety-critical.** Never invent or coerce `decimals` to 18. 2. **Approval target = spender**, not necessarily the router `to`. 3. **Same slippage** for quote and build so displayed route matches execution. 4. **Async orders:** never put the quote-only dead-address placeholder into a signed order. CoW stamps the real sender on the reused envelope; other async venues re-quote with the real sender. 5. **No public RPC fallbacks in the CLI** — missing RPC config fails with the env var name to set. The hosted dApp last-resorts to the shared PublicNode table when Alchemy and per-chain overrides are unset. 6. **Do not treat this host’s `/api/*` as unlimited free infrastructure** — it consumes operator API keys; rate-limit and cache responsibly. ## Pricing / commercial No public pricing page. The public dApp is a free hosted instance of the same engine; availability of venues depends on the operator’s API keys. ## Legal - CLI manual (human-readable `swap --help` with examples): https://swap.9summits.io/docs (Markdown: /docs.md) - Disclaimer: https://swap.9summits.io/disclaimer.html (non-custodial interface, no accounts, no cookies, no trackers, no client-side analytics; keeps aggregate anonymous swap-outcome counters — venue, chain id, outcome — via server logs). ## Related files on this host - https://swap.9summits.io/docs.md — CLI manual (Markdown; `/docs` with `Accept: text/markdown` serves it) - https://swap.9summits.io/docs — CLI manual (HTML) - https://swap.9summits.io/openapi.json — OpenAPI 3.1 for `/api/*` - https://swap.9summits.io/skills/swap-cli/SKILL.md — installable agent skill - https://swap.9summits.io/llms.txt — compact link index (llmstxt.org) - https://swap.9summits.io/robots.txt — crawler rules - https://swap.9summits.io/sitemap.xml — public URL list - https://swap.9summits.io/install.sh — CLI installer script