# 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 by your own wallet (or agent). Domain: vortragents.com · Token: $VORTR.

Vortr is agent-first: the swap runs in your agent over the MCP, signed by your own wallet.
The website (/swap) is a read-only showcase (live quotes, chart, real Base-swaps feed). Two
ways for agents to connect:
- Remote connector (the way; no install, NO SECRET): add https://www.vortragents.com/mcp as a custom
  MCP connector (Claude web/desktop), or `claude mcp add --transport http vortr
  https://www.vortragents.com/mcp` in Claude Code, or add it by URL in Hermes (`url:
  https://www.vortragents.com/mcp` — Hermes speaks HTTP MCP, no bridge). It prices + builds; your
  agent signs the returned ERC-5792 payload (or run @vortr/wallet alongside it for autonomous
  signing). No Vortr secret anywhere.
- Self-host only (advanced): run the `@vortr/mcp` stdio package against your OWN deployment with
  your own VORTR_API_BASE + VORTR_API_SECRET (those gate your 0x key). Regular users never need this.

Docs (humans + agents): /docs
This file: /llms.txt
Skill guide (drop-in Claude Code / Hermes skill, with frontmatter): /skill.md

## What Vortr is

- Non-custodial swap on Base mainnet. Vortr never custodies funds; you sign 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, cbETH, USDe, AERO.
- Live swap-page data is real: prices/route from 0x, OHLCV chart + live Base-swaps feed from
  GeckoTerminal, USD values from DefiLlama. (Read-only showcase — no wallet is connected on the web.)

## 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)`
  -> the Base token set for an address (portfolio scaffold). Balances are read by your own
     agent/wallet, not over MCP.

- `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 the calldata for your agent to sign + send.

Your agent signs. build_swap returns the ERC-5792 payload — sign + send it with your agent's own
wallet, or run @vortr/wallet alongside the connector for autonomous signing. Vortr never holds keys.

## Agent recipe — a swap, end to end

1. `vortr.search_tokens("USDC")` / `search_tokens("WETH")` -> Base token addresses.
2. `vortr.get_quote(sellToken, buyToken, amount[BASE UNITS], taker)` -> price + route.
3. `vortr.build_swap(...same args...)` -> { payload, summary }.
4. Sign + send `payload` with your agent's wallet (or @vortr/wallet). If `summary.expiresAt` passed, call build_swap again first.

### Autonomous signing — @vortr/wallet
Run @vortr/wallet (first-party local signer) alongside the connector.
It holds your EOA key in VORTR_SIGNER_KEY (env, never in chat), auto-fills the taker, fetches the
keyless calldata itself, and signs+broadcasts on Base after a per-swap confirm:
  wallet_address -> use as taker
  prepare_swap { sellToken, buyToken, usd|amount } -> { confirm_token, summary }
  execute_swap { confirm_token } -> broadcasts; swap_status { hash } to poll
The hosted Vortr still never holds the key.
@vortr/wallet is self-contained — it also exposes search_tokens + get_quote, so you can run JUST it
(one local MCP) instead of also adding the remote connector. Still non-custodial.
Install (published on npm; npx auto-fetches it):
  Claude Code:  claude mcp add --scope user vortr -e VORTR_SIGNER_KEY=0x… -- npx -y @vortr/wallet
  Hermes (~/.hermes/config.yaml):
    vortr: { command: "npx", args: ["-y","@vortr/wallet"], env: { VORTR_SIGNER_KEY: "0x…" }, connect_timeout: 60 }

## Setup — no secret

Use the remote connector. Your agent signs the `payload` build_swap returns. No `@vortr/mcp`
install, no API key, no secret.

Claude (web/desktop): Settings -> Connectors -> Add custom connector -> paste
  https://www.vortragents.com/mcp

Claude Code:

```
claude mcp add --transport http vortr https://www.vortragents.com/mcp
```

Hermes Agent (NousResearch) speaks HTTP MCP directly — add the connector by URL (no secret, no bridge):

```
mcp_servers:
  vortr:
    url: "https://www.vortragents.com/mcp"
```

Signing: the connector never signs (non-custodial). build_swap returns the ERC-5792 `payload` —
your agent signs + sends it. For hands-off signing, run @vortr/wallet locally
(VORTR_SIGNER_KEY in env; see @vortr/wallet README).

### Self-host (advanced)

Running your OWN Vortr deployment? Use the `@vortr/mcp` stdio package with your own
VORTR_API_BASE + VORTR_API_SECRET (those gate your 0x key) instead of the connector — point
VORTR_API_BASE at your deployment (or your running web app for local dev). Not needed to use
hosted Vortr.

## Notes

- `amount` is BASE UNITS, not decimals. Exact-input only.
- Vortr never signs; your agent signs the payload in its own wallet (or run @vortr/wallet for autonomous signing).
- On-chain data cannot certify a swap as agent-vs-human; the "Live swaps" feed shows real
  on-chain Base swaps without that distinction.