SkillsSKILLS
Productivity

grimoire-uniswap▌

franalgaba/grimoire · updated Apr 8, 2026

$npx skills add https://github.com/franalgaba/grimoire --skill grimoire-uniswap
summary

Retrieve Uniswap router metadata, token lists, and pool snapshots via CLI commands.

  • ›Four command categories: info (adapter overview), routers (by chain), tokens (by symbol or address), and pools (with fee and liquidity filtering)
  • ›Supports Uniswap V3 (SwapRouter02) and V4 (Universal Router with Permit2) adapters across multiple chains
  • ›Output formats include JSON, table, and spell (a params snapshot block for agent workflows)
  • ›Pools can query via The Graph API or onchain factory look
skill.md

Grimoire Uniswap Skill

Use this skill to inspect Uniswap metadata and produce token/pool snapshots for spells.

Preferred invocations:

  • grimoire venue uniswap ...
  • npx -y @grimoirelabs/cli venue uniswap ... (no-install)
  • bun run packages/cli/src/index.ts venue uniswap ... (repo-local)
  • grimoire-uniswap ... (direct binary from @grimoirelabs/venues)

Recommended preflight:

  • grimoire venue doctor --adapter uniswap --chain 1 --rpc-url <rpc> --json

Commands

  • grimoire venue uniswap info — adapter metadata
  • grimoire venue uniswap routers [--chain <id>] — router addresses per chain
  • grimoire venue uniswap tokens [--chain <id>] [--symbol <sym>] [--address <addr>] [--source <url>] — token list lookup
  • grimoire venue uniswap tokens-snapshot [--chain <id>] [--symbol <sym>] [--address <addr>] [--source <url>] — generate spell params: block for tokens (agent-only)
  • 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 pair
  • 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)

Pool Data Sources

Pools can be fetched from The Graph (subgraph) or directly from on-chain factory contracts:

  • Subgraph (default when GRAPH_API_KEY is set): queries The Graph decentralized network. Built-in subgraph IDs for Ethereum, Optimism, Polygon, Base, Arbitrum.
  • 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).
  • To force RPC mode: provide --rpc-url and omit --graph-key.

Environment Variables

Variable Description
GRAPH_API_KEY The Graph API key for subgraph queries (get one at https://thegraph.com/studio/apikeys/)
RPC_URL Fallback RPC URL for on-chain pool lookups

Examples

grimoire venue uniswap info --format table
grimoire venue uniswap routers
grimoire venue uniswap routers --chain 1
grimoire venue uniswap tokens --chain 1 --symbol USDC --format spell
grimoire venue uniswap pools --chain 1 --token0 USDC --token1 WETH --fee 3000 --format spell
grimoire venue uniswap pools --chain 8453 --token0 USDC --token1 WETH --fee 500 --rpc-url $RPC_URL --format table
grimoire venue uniswap pools --chain 8453 --token0 USDC --token1 WETH --fee 500 --graph-key $GRAPH_API_KEY --subgraph-id <id>
grimoire venue uniswap tokens-snapshot --chain 1 --symbol USDC
grimoire venue uniswap pools-snapshot --chain 1 --token0 USDC --token1 WETH --rpc-url $RPC_URL

Use tokens-snapshot or pools-snapshot to emit a params: block for spell inputs. These are agent-only commands (output suppressed in interactive mode).

Metric Surface (Spell Comparisons)

Uniswap V3 and V4 expose quote_out for protocol comparison:

v3_out = metric("quote_out", uni_v3, USDC, "asset_out=WETH,amount=1000000,fee_tier=3000")
v4_out = metric("quote_out", uni_v4, USDC, "asset_out=WETH,amount=1000000,fee_tier=3000,tick_spacing=60")

Selector fields:

  • required: asset_out
  • optional: amount (defaults to 1 unit of input asset), fee_tier
  • V4 optional: tick_spacing

Spell Constraints

When writing swap actions in .spell files targeting Uniswap, use with clauses to set constraints:

uniswap_v3.swap(USDC, WETH, params.amount) with (
  fee_tier=3000,
  max_slippage=50,
  min_output=900000000000000,
  deadline=300,
)

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.

Common fee tiers: 500 (0.05%), 3000 (0.3%), 10000 (1%).

Parameter Type Description
fee_tier integer (bps) Required. Uniswap pool fee tier (e.g. 500, 3000, 10000)
Constraint Type Description
max_slippage integer (bps) Maximum slippage in basis points (e.g. 50 = 0.5%)
min_output integer (wei) Minimum output amount floor
max_input integer (wei) Maximum input amount cap
deadline integer (seconds) Transaction deadline from now
require_quote boolean Fail if on-chain quote fetch fails
require_simulation boolean Fail if simulation unavailable
max_gas integer (wei) Gas estimate cap

Always set both max_slippage and min_output for swaps to prevent unexpected losses.

Supported Adapters

Adapter Router Approval Flow
@uniswap_v3 SwapRouter02 Standard ERC20 approve
@uniswap_v4 Universal Router Permit2

Notes

  • CLI currently exposes V3 metadata. V4 adapter is available programmatically via createUniswapV4Adapter().
  • For metadata lookups (tokens, pools), use grimoire venue uniswap ... even when your spell venue is uniswap_v4.
  • Outputs JSON/table; tokens and pools also support --format spell.
  • Prefer --format json for automation and reproducible snapshots.
  • Only metadata is exposed (no on-chain quote endpoints).