# 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://swagg-neon.vercel.app. License: BUSL-1.1 (Business Source License 1.1; change license GPL-2.0-or-later after the change date). Licensor: 9Summits.

This file expands [/llms.txt](https://swagg-neon.vercel.app/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.

## Surfaces

| Surface | How to use |
|---------|------------|
| Web dApp | Open https://swagg-neon.vercel.app/ — select chain, tokens, amount; quotes stream; connect wallet to execute |
| CLI install | `curl -fsSL https://swagg-neon.vercel.app/install.sh \| bash` → binary `swap` in `~/.local/bin` |
| CLI quote | `swap 1 WBTC ETH` — ranks venues by amountOut |
| 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 |

Platforms for the one-shot installer: 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 |

Native token is represented internally as the sentinel address `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` (adapters translate at venue boundaries). Token symbols or `0x` addresses are accepted; decimals must be resolved correctly (never assumed to be 18).

## Venues

**Sync** (broadcastable tx): `kyber`, `odos`, `velora`, `matcha` (0x), `1inch`, `curve`, `uniswap`.

**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): includes `velora`, `matcha`, `uniswap`, `cow`, and similar buy-side paths. Sell-only venues are excluded from exact-out races. The dApp exposes the set as `buyVenues` from `GET /api/mode`.

Venue availability depends on server env keys (e.g. `ZEROEX_API_KEY`, `ONEINCH_API_KEY`, `UNISWAP_API_KEY`) 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.
- **Send (`-a send`):** ERC-20 `transfer` or native value transfer to `--to`; no allowance for transfer path.

## HTTP API (public host)

Base: `https://swagg-neon.vercel.app`

Contract is **stateless**: every call carries full inputs; `quoteId` is a client round key only. Local CLI may require `?id=<sid>`; 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=<alias>

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.

Returns ranked quotes (best first for the active side).

### POST /api/quote/stream

Same body as quote. Response: **NDJSON** lines — `meta`, then per-venue `route` or `verror`, then `done`. 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).

Optional flags mirrored from CLI: `odosNotCompact`, `disableOdosRfq`.

### POST /assemble

Body: `{ "signature": "0x…", "context": <assembleContext from build> }` — 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.

### 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\|all\|a,b>` | Venue filter; default races all available |
| `--allow-async` | Include intent venues |
| `--chain <alias>` | Network |
| `--slippage <pct>` | Percent (default `0.1` = 10 bps); same value for quote and build |
| `--exact-out` | Amount is tokenOut |
| `--from <addr>` | 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 |

## 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; re-quote with the real sender.
5. **No public RPC fallbacks** in the CLI design — missing RPC config fails with the env var name to set.
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 product is distributed as open-source-style source under BUSL-1.1 (non-production use rights as stated in the license; production use requires compliance with BUSL terms until the change date). The public dApp is a free hosted instance of the same engine; availability of venues depends on the operator’s API keys.

## Legal

- License: Business Source License 1.1 (Licensed Work: swap-cli, © 9Summits). Change Date and Change License are defined in the LICENSE file of the source repository.
- No Terms of Service or Privacy Policy pages are published on this host as of the sitemap’s generation.

## Related files on this host

- https://swagg-neon.vercel.app/llms.txt — compact link index (llmstxt.org)
- https://swagg-neon.vercel.app/robots.txt — crawler rules
- https://swagg-neon.vercel.app/sitemap.xml — public URL list
- https://swagg-neon.vercel.app/install.sh — CLI installer script