Overview

Routey Docs

A swap router that quotes Uniswap V3 and Relay side-by-side and picks the better execution — on four chains, for humans and AI agents, over the same pipeline.

path 1

For humans

Connect a wallet, enter an amount, review the route, sign, done.

Open →

path 2

For agents

Call the MCP tools from Claude Code or hit the REST API from any runtime.

Open →

What Routey is

Routey is a thin coordination layer over two liquidity sources — Uniswap V3 (onchain AMM) and Relay (cross-chain router). Given an input token, an output token, a chain, and an amount, Routey fetches both quotes in parallel, compares the final amountOut after fees, and surfaces the winner through a shared pipeline.

The same pipeline powers two surfaces:

a hand-drawn web UI at /swap for humans using a wallet;
an stdio MCP server and a REST API for agents running autonomously.

Both paths use the same quote engine, the same provider selection, and the same execution code. There is no “agent mode” that behaves differently from what a human sees in the UI.

Why Routey

Route comparison is a primitive, not a feature

Every swap call fans out to both providers in parallel and returns both quotes, the winner, and the saved amount. You do not choose “which router” when you start — Routey decides per swap, per block, based on the number that matters: how much output the user actually receives.

Agents are first-class, not an afterthought

The MCP server and REST API are not a side door onto the UI. They are the same code the UI calls — identical validation, identical quote logic, identical execution. An agent running through execute_swap and a human clicking Swap Now reach the same contract call with the same calldata.

Transparent by construction

The quote you see is the quote you sign. Both provider amounts are displayed before execution, along with fees, gas estimates, and provider latency. The savings figure is shown explicitly; nothing is rolled into an opaque “best price.”

Four chains, one interface

Ethereum mainnet, Base, Arbitrum One, and Optimism. Chain is a parameter — not a tab, not a wizard, not a network-switching modal. The agent API takes the slug (ethereum, base, arbitrum, optimism); the UI exposes a single dropdown.

Open by default

The MCP server is a thin wrapper over the same library functions the app imports. The REST endpoints are documented and stable. The event stream is plain text/event-stream with JSON-encoded events. There is no SDK to adopt and no auth handshake to ship before you can send a single quote request.

What Routey is not

Not a custody layer, not a wallet, not a token list. Routey routes swaps through existing providers and signs with keys you provide — either a connected browser wallet (human path) or a private key you pass explicitly or via the AGENT_PRIVATE_KEY environment variable (agent path).

Core concepts

Providers

Two routing providers are supported.

Uniswap V3 — onchain AMM, same-chain swaps, pool fees visible per route (0.05% / 0.3% / 1%).
Relay — cross-chain router, gasless on the destination side, may bridge + swap in a single intent.

The best field is decided on the wire output after fees. Both raw quotes are always returned; you can override the winner by passing provider: "uniswap" or provider: "relay" to execute a specific route.

Quote lifecycle

A quote is not a commitment. The UI polls every 30 seconds and refetches on every input change. Agents should re-quote immediately before executing — between quoting and broadcasting, pools can shift. Slippage tolerance (default 0.5%) covers ordinary movement; larger orders should tune it up, smaller ones may safely tune it down.

Execution path

Every execution goes through lib/swap.ts. The human path uses wagmi / a connected wallet; the agent path uses a viem wallet client built from a private key. The contract call, calldata, and slippage math are the same — only the signing surface differs.

Chains

Four networks. RPC endpoints are configurable via RPC_ETHEREUM, RPC_BASE, RPC_ARBITRUM, RPC_OPTIMISM environment variables, with public fallbacks. Chain IDs are the standard ones (1, 8453, 42161, 10).

Event stream

A server-sent event endpoint at GET /api/events emits every lifecycle event — agent_connect, quote_request, quote_result, swap_execute, swap_confirmed — so agents or dashboards can mirror activity in real time without polling.

Where to go next

For humans → — wallet flow, chain selection, approve + swap, troubleshooting.
For agents → — MCP server install, tool reference, REST endpoints, SSE events, end-to-end example.