Grimoire Uniswap

1---2name: grimoire-uniswap3description: Retrieves Uniswap router metadata using the Grimoire venue CLI. Use when you need router addresses, adapter information, or Uniswap V3/V4 details.4---5 6# Grimoire Uniswap Skill7 8Use this skill to inspect Uniswap metadata and produce token/pool snapshots for spells.9 10Preferred invocations:11 12- `grimoire venue uniswap ...`13- `npx -y @grimoirelabs/cli venue uniswap ...` (no-install)14- `bun run packages/cli/src/index.ts venue uniswap ...` (repo-local)15- `grimoire-uniswap ...` (direct binary from `@grimoirelabs/venues`)16 17Recommended preflight:18 19- `grimoire venue doctor --adapter uniswap --chain 1 --rpc-url <rpc> --json`20 21## Commands22 23- `grimoire venue uniswap info` — adapter metadata24- `grimoire venue uniswap routers [--chain <id>]` — router addresses per chain25- `grimoire venue uniswap tokens [--chain <id>] [--symbol <sym>] [--address <addr>] [--source <url>]` — token list lookup26- `grimoire venue uniswap tokens-snapshot [--chain <id>] [--symbol <sym>] [--address <addr>] [--source <url>]` — generate spell `params:` block for tokens (agent-only)27- `grimoire venue uniswap pools --token0 <address|symbol> --token1 <address|symbol> [--chain <id>] [--fee <bps>] [--limit <n>] [--source <url>] [--endpoint <url>] [--graph-key <key>] [--subgraph-id <id>] [--rpc-url <url>] [--factory <address>]` — find pools for a token pair28- `grimoire venue uniswap pools-snapshot --token0 <address|symbol> --token1 <address|symbol> [--chain <id>] [--fee <bps>] [--limit <n>] [--source <url>] [--endpoint <url>] [--graph-key <key>] [--subgraph-id <id>] [--rpc-url <url>] [--factory <address>]` — generate spell `params:` block for pools (agent-only)29 30## Pool Data Sources31 32Pools can be fetched from The Graph (subgraph) or directly from on-chain factory contracts:33 34- **Subgraph** (default when `GRAPH_API_KEY` is set): queries The Graph decentralized network. Built-in subgraph IDs for Ethereum, Optimism, Polygon, Base, Arbitrum.35- **RPC** (fallback): if no usable graph config is present, pools uses on-chain factory lookups (with `--rpc-url`/`RPC_URL` when provided, otherwise chain default RPC where available).36- To force RPC mode: provide `--rpc-url` and omit `--graph-key`.37 38## Environment Variables39 40| Variable | Description |41|----------|-------------|42| `GRAPH_API_KEY` | The Graph API key for subgraph queries (get one at https://thegraph.com/studio/apikeys/) |43| `RPC_URL` | Fallback RPC URL for on-chain pool lookups |44 45## Examples46 47```bash48grimoire venue uniswap info --format table49grimoire venue uniswap routers50grimoire venue uniswap routers --chain 151grimoire venue uniswap tokens --chain 1 --symbol USDC --format spell52grimoire venue uniswap pools --chain 1 --token0 USDC --token1 WETH --fee 3000 --format spell53grimoire venue uniswap pools --chain 8453 --token0 USDC --token1 WETH --fee 500 --rpc-url $RPC_URL --format table54grimoire venue uniswap pools --chain 8453 --token0 USDC --token1 WETH --fee 500 --graph-key $GRAPH_API_KEY --subgraph-id <id>55grimoire venue uniswap tokens-snapshot --chain 1 --symbol USDC56grimoire venue uniswap pools-snapshot --chain 1 --token0 USDC --token1 WETH --rpc-url $RPC_URL57```58 59Use `tokens-snapshot` or `pools-snapshot` to emit a `params:` block for spell inputs. These are agent-only commands (output suppressed in interactive mode).60 61## Metric Surface (Spell Comparisons)62 63Uniswap V3 and V4 expose `quote_out` for protocol comparison:64 65```spell66v3_out = metric("quote_out", uni_v3, USDC, "asset_out=WETH,amount=1000000,fee_tier=3000")67v4_out = metric("quote_out", uni_v4, USDC, "asset_out=WETH,amount=1000000,fee_tier=3000,tick_spacing=60")68```69 70Selector fields:71 72- required: `asset_out`73- optional: `amount` (defaults to 1 unit of input asset), `fee_tier`74- V4 optional: `tick_spacing`75 76## Spell Constraints77 78When writing swap actions in `.spell` files targeting Uniswap, use `with` clauses to set constraints:79 80```spell81uniswap_v3.swap(USDC, WETH, params.amount) with (82  fee_tier=3000,83  max_slippage=50,84  min_output=900000000000000,85  deadline=300,86)87```88 89**`fee_tier` is required.** The adapter throws if `fee_tier` is not specified. It is an action parameter (not a constraint) and is extracted from the `with()` clause.90 91Common fee tiers: `500` (0.05%), `3000` (0.3%), `10000` (1%).92 93| Parameter | Type | Description |94|-----------|------|-------------|95| `fee_tier` | integer (bps) | **Required.** Uniswap pool fee tier (e.g. `500`, `3000`, `10000`) |96 97| Constraint | Type | Description |98|-----------|------|-------------|99| `max_slippage` | integer (bps) | Maximum slippage in basis points (e.g. `50` = 0.5%) |100| `min_output` | integer (wei) | Minimum output amount floor |101| `max_input` | integer (wei) | Maximum input amount cap |102| `deadline` | integer (seconds) | Transaction deadline from now |103| `require_quote` | boolean | Fail if on-chain quote fetch fails |104| `require_simulation` | boolean | Fail if simulation unavailable |105| `max_gas` | integer (wei) | Gas estimate cap |106 107Always set both `max_slippage` and `min_output` for swaps to prevent unexpected losses.108 109## Supported Adapters110 111| Adapter | Router | Approval Flow |112|---------|--------|---------------|113| `@uniswap_v3` | SwapRouter02 | Standard ERC20 approve |114| `@uniswap_v4` | Universal Router | Permit2 |115 116## Notes117 118- CLI currently exposes V3 metadata. V4 adapter is available programmatically via `createUniswapV4Adapter()`.119- For metadata lookups (`tokens`, `pools`), use `grimoire venue uniswap ...` even when your spell venue is `uniswap_v4`.120- Outputs JSON/table; `tokens` and `pools` also support `--format spell`.121- Prefer `--format json` for automation and reproducible snapshots.122- Only metadata is exposed (no on-chain quote endpoints).