# Vortr

> Vortr is an agent-first, non-custodial DEX on Base (Coinbase L2). Swaps are routed
> through the 0x aggregator. Vortr never holds your funds and never signs — every trade
> is signed in the user's own wallet. Domain: vortr.xyz · Token: $VORTR.

Humans and agents use the same surface. Humans swap in the web app at /swap. Two ways for
agents to connect:
- Remote connector (no install): add the URL https://www.vortr.xyz/mcp as a custom MCP
  connector (Claude web/desktop, or any remote-MCP client). Read/build tools only — signing is
  NOT available over a remote URL (non-custodial); build_swap returns calldata + a sign_url.
- Local stdio (full flow incl. signing): run `npx -y @vortr/mcp` (server name `vortr`) paired
  with a wallet MCP (`@walletchan/mcp`); the user signs in their own wallet.

Docs (humans + agents): /docs
This file: /llms.txt

## What Vortr is

- Non-custodial swap on Base mainnet. Vortr never custodies funds; the user signs every trade.
- Routing/quotes/firm calldata come from the 0x aggregator (smart-order-routed across Base pools).
- Base assets supported: native ETH, WETH, USDC, USDT, DAI, cbBTC.
- Live swap-page data is real: prices/route from 0x, OHLCV chart + live Base-swaps feed from
  GeckoTerminal, USD values from DefiLlama, balances via the user's wallet RPC.

## The Vortr MCP (server name: `vortr`) — 4 tools

- `search_tokens(query, chain?="base")`
  -> Base token metadata: { address, symbol, decimals, ... }.

- `get_quote(sellToken, buyToken, amount, taker, slippageBps?)`
  -> price quote: { buyAmount, minBuyAmount, priceImpact, route, ... }. Exact-input only.
  -> `amount` is in BASE UNITS (stringified integer). 1 USDC = "1000000"; 18-decimal tokens
     are scaled by 1e18.

- `get_portfolio(address)`
  -> token balances for an address on Base.

- `build_swap(sellToken, buyToken, amount, taker, slippageBps?)`
  -> { payload, summary }.
     `payload` is an ERC-5792 `wallet_sendCalls` batch (approve + swap): payload.calls.
     `summary` carries { taker, expiresAt }.
  -> Vortr never signs. `build_swap` only returns calldata to hand to the wallet MCP.

Non-custodial signing is delegated to `@walletchan/mcp`: the user approves in the WalletChan
browser-extension popup over WalletConnect. Vortr itself never holds keys and never signs.

## Agent recipe — a swap, end to end

1. `walletchan.get_pairing_uri` -> if unpaired, show the `wc:` URI; user pairs in the WalletChan extension.
2. `walletchan.get_wallets`     -> the approved Base account = the TAKER. Pin this address.
3. `vortr.get_quote(sellToken, buyToken, amount[BASE UNITS], taker)` -> price + route.
4. `vortr.build_swap(...same args...)` -> { payload, summary }.
5. Verify `summary.taker === the get_wallets address`. Abort on mismatch.
6. `walletchan.send_calls({ chain: "base", from: summary.taker, calls: payload.calls })`
   -> user approves in the WalletChan popup.
7. `walletchan.get_request_status(requestId)` -> 100-199 pending · 200-299 confirmed · >=400 failed.

### Recovery
- `needs_pairing` / `walletconnect_disconnected` -> call `walletchan.get_pairing_uri` and re-pair.
- `summary.expiresAt` passed OR `reprepareRequired` -> call `vortr.build_swap` again before retrying.

## Setup

### Remote connector (no install)

Add this URL as a custom MCP connector in Claude (web/desktop) or any remote-MCP client:

  https://www.vortr.xyz/mcp

Streamable HTTP, public, stateless. Exposes search_tokens, get_quote, get_portfolio, build_swap.
Signing is NOT available over a remote URL (non-custodial) — build_swap returns the ERC-5792 calls
plus a `sign_url` to open and sign in your own wallet. For full programmatic signing, use the local
stdio setup below with `@walletchan/mcp`.

### Local (stdio) — full flow incl. signing

Vortr is a standard stdio MCP server, so any MCP-capable runtime works. Register two
servers: `vortr` (quote/build) and a wallet MCP (`walletchan`) for signing.

Claude Code:

```
claude mcp add --scope user vortr -e VORTR_API_BASE=<vortr url> -e VORTR_API_SECRET=<secret> -- npx -y @vortr/mcp
claude mcp add --scope user walletchan -- npx -y @walletchan/mcp
```

Hermes Agent (NousResearch) — add to `~/.hermes/config.yaml`, then restart Hermes. Hermes
does NOT inherit your shell environment for stdio subprocesses, so the secrets MUST live in
the `env:` block:

```
mcp_servers:
  vortr:
    command: "npx"
    args: ["-y", "@vortr/mcp"]
    env:
      VORTR_API_BASE: "<vortr url>"
      VORTR_API_SECRET: "<secret>"
    timeout: 60
    connect_timeout: 30
  walletchan:
    command: "npx"
    args: ["-y", "@walletchan/mcp"]
```

Env var names are `VORTR_API_BASE` / `VORTR_API_SECRET` (internal legacy names, kept).
The secret must match the web app's `VORTR_API_SECRET`.

For local dev: point `VORTR_API_BASE` at your running web app and run the local binary
`node /path/packages/mcp/dist/index.js` instead of `npx -y @vortr/mcp`.

## Notes

- `amount` is BASE UNITS, not decimals. Exact-input only.
- Vortr never signs; the only approval/signature is the WalletChan popup.
- On-chain data cannot certify a swap as agent-vs-human; the "Live swaps" feed shows real
  on-chain Base swaps without that distinction.