---
name: vortr-swaps
description: Non-custodial DeFi swaps on Base via the Vortr MCP (remote connector https://www.vortr.xyz/mcp — no secret) — search tokens, get 0x quotes, build ERC-5792 approve+swap calldata, then sign in your own wallet via the returned sign_url (or a wallet MCP for headless signing). Vortr never signs. Use when an agent needs to price or execute a token swap on Base.
---

# Vortr MCP — Skill Guide

Vortr gives AI assistants non-custodial DeFi capabilities on Base: token search, 0x swap quotes, and ERC-5792 swap payloads. You sign every trade in your own wallet — `build_swap` returns a `sign_url` to open and confirm (or hand `payload.calls` to a wallet MCP like `@walletchan/mcp` for headless signing). Vortr never signs anything.

> This file is a valid skill for **both** Claude Code skills and **Hermes Agent**
> (NousResearch) — drop it into `~/.hermes/skills/defi/vortr-swaps/`.

## Installation

Use the remote connector. Sign by opening the `sign_url` `build_swap` returns. No `@vortr/mcp`
install, no API key, **no secret**.

### Remote connector — Claude (web/desktop)

Vortr is a hosted remote MCP. Add this URL as a custom connector:

```
https://www.vortr.xyz/mcp
```

Streamable HTTP, public, stateless — exposes `search_tokens`, `get_quote`,
`get_portfolio`, `build_swap`.

### Claude Code

```bash
claude mcp add --transport http vortr https://www.vortr.xyz/mcp
```

### Hermes Agent (NousResearch)

Hermes is stdio-only, so bridge the remote connector with `mcp-remote` (no secret).
Add it under `mcp_servers:` in `~/.hermes/config.yaml`, then restart Hermes:

```yaml
mcp_servers:
  vortr:
    command: "npx"
    args: ["-y", "mcp-remote", "https://www.vortr.xyz/mcp"]
    timeout: 60
    connect_timeout: 30
```

### Signing

The connector never signs (non-custodial). `build_swap` returns a `sign_url` — open it to
confirm in your own wallet. For headless signing, hand `payload.calls` to a wallet MCP instead
(e.g. `@walletchan/mcp` `send_calls`).

### 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 (localhost is rejected; use your running web app
for local dev). Not needed to use hosted Vortr. To install this skill itself, copy this
folder into `~/.hermes/skills/defi/vortr-swaps/`.

## Tools

| Tool | Description |
|------|-------------|
| `search_tokens` | Search the Base token registry by symbol, name, or address. Returns `TokenInfo[]`. |
| `get_quote` | Get a 0x swap quote on Base (price, `minBuyAmount`, route, price impact). `amount` is base units. |
| `build_swap` | Build an ERC-5792 `send_calls` payload (approve + swap). Returns `{ payload, summary, sign_url }`. |
| `get_portfolio` | Get token balances for an address on Base. |

## Full Swap Recipe

1. `vortr.search_tokens(query)` — find `sellToken` and `buyToken` addresses.
2. `vortr.get_quote(sellToken, buyToken, amount, taker)` — preview price and `minBuyAmount`.
3. `vortr.build_swap(sellToken, buyToken, amount, taker)` — get `{ payload, summary, sign_url }`.
   - `summary.expiresAt` is an epoch ms deadline; call `build_swap` again if it has passed.
4. Open `sign_url`, connect your wallet, and confirm. Vortr never signs.

### Headless signing (optional)

Instead of opening `sign_url`, hand `payload.calls` to a wallet MCP:
`walletchan.send_calls({ chain: "base", from: summary.taker, calls: payload.calls })`, then poll
`walletchan.get_request_status(requestId)` (100–199 pending, 200–299 confirmed, ≥400 failed).

## Recovery

| Error | Action |
|-------|--------|
| `summary.expiresAt` passed | Call `vortr.build_swap` again before retrying |
| (headless) `needs_pairing` / `walletconnect_disconnected` | Re-pair via your wallet MCP, then retry |

## Notes

- **Amount is BASE UNITS**: 1 USDC = `"1000000"` (6 decimals); 1 ETH = `"1000000000000000000"` (18 decimals).
- **Vortr never signs.** You confirm in your own wallet — open the `sign_url`, or use a wallet MCP for headless signing.
- **Base-only**: All tokens must be on Base (chain ID 8453). Use `search_tokens` to look up valid addresses.