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 metadatagrimoire venue uniswap routers [--chain <id>]— router addresses per chaingrimoire venue uniswap tokens [--chain <id>] [--symbol <sym>] [--address <addr>] [--source <url>]— token list lookupgrimoire venue uniswap tokens-snapshot [--chain <id>] [--symbol <sym>] [--address <addr>] [--source <url>]— generate spellparams: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 pairgrimoire 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 spellparams: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_KEYis 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_URLwhen provided, otherwise chain default RPC where available). - To force RPC mode: provide
--rpc-urland 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_URLUse 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), usegrimoire venue uniswap ...even when your spell venue isuniswap_v4. - Outputs JSON/table;
tokensandpoolsalso support--format spell. - Prefer
--format jsonfor automation and reproducible snapshots. - Only metadata is exposed (no on-chain quote endpoints).
