/swap-planner

name: swap-planner
description: This skill should be used when the user asks to "swap tokens", "trade ETH for USDC", "exchange tokens on Uniswap", "buy tokens", "sell tokens", "convert ETH to stablecoins", "find memecoins", "discover tokens", "research tokens", "tokens to buy", "find tokens to swap", "what should I buy", or mentions swapping, trading, researching, discovering, buying, or exchanging tokens on any Uniswap-supported chain. Supports both known token swaps and token discovery workflows (discovery uses keyword search and web search — there is no live "trending" feed). Generates deep links to execute swaps in the Uniswap interface.
allowed-tools: Read, Glob, Grep, Bash(curl:*), Bash(jq:*), Bash(cast:*), Bash(xdg-open:*), Bash(open:*), WebFetch, WebSearch, Task(subagent_type:Explore), AskUserQuestion
model: sonnet
license: MIT
metadata:
  author: uniswap
  version: '0.2.1'

Swap Planning

Plan and generate deep links for token swaps on Uniswap across all supported chains.

> **Runtime Compatibility:** This skill uses `AskUserQuestion` for interactive prompts. If `AskUserQuestion` is not available in your runtime, collect the same parameters through natural language conversation instead.

Overview

Plan token swaps by:

1. Gathering swap intent (tokens, amounts, chain) 2. Verifying token contracts on-chain 3. Researching tokens via web search when needed 4. Generating a deep link that opens in the Uniswap interface with parameters pre-filled

The generated link opens Uniswap with all parameters ready for execution.

> **Note:** Browser opening (`xdg-open`/`open`) may fail in SSH, containerized, or headless environments. Always display the URL prominently so users can copy and access it manually if needed.

<!-- markdownlint-disable-next-line MD028 -->

> **File Access:** This skill has read-only filesystem access. Never read files outside the current project directory unless explicitly requested by the user.

Workflow

Step 0: Token Discovery (When Needed)

If the user wants to **discover** tokens rather than swap a known token (e.g., "find me a memecoin", "what's trending on Base"), help them explore before proceeding to the swap.

Option A: Search by Keyword

DexScreener search works best with specific terms:

# Search for tokens by name/category (e.g., "degen", "pepe", "ai agent")
curl -s "https://api.dexscreener.com/latest/dex/search?q=degen" | \
  jq '[.pairs[] | select(.chainId == "base" and .dexId == "uniswap")] |
    sort_by(-.volume.h24) | .[0:5] | map({
      token: .baseToken.symbol,
      address: .baseToken.address,
      price: .priceUsd,
      volume24h: .volume.h24,
      liquidity: .liquidity.usd
    })'

**Good search terms:** `degen`, `pepe`, `ai`, `agent`, `meme`, `dog`, `cat`, or specific token names

Option B: Check Promoted Tokens

Get tokens with active promotions (limited selection):

# Get boosted/promoted tokens on a chain
curl -s "https://api.dexscreener.com/token-boosts/top/v1" | \
  jq '[.[] | select(.chainId == "base")] | .[0:5] | map({
    tokenAddress,
    url
  })'

Option C: Web Search + Verify

For broad discovery ("what's trending"), use web search to find tokens, then verify with DexScreener:

# After finding a token address from web search, verify it exists
curl -s "https://api.dexscreener.com/token-pairs/v1/{network}/{address}" | \
  jq '[.[] | select(.dexId == "uniswap")][0] | {
    name: .baseToken.name,
    symbol: .baseToken.symbol,
    price: .priceUsd,
    liquidity: .liquidity.usd,
    volume24h: .volume.h24
  }'

**Network IDs:** See `references/chains.md` for the full list with DexScreener and DefiLlama provider IDs. Common IDs: `ethereum`, `base`, `arbitrum`, `optimism`, `polygon`, `bsc`, `avalanche`, `unichain`.

**DexScreener coverage varies by chain.** Ethereum, Base, and Arbitrum have deep Uniswap data. Celo, Blast, Zora, and World Chain have limited Uniswap pool coverage — fewer results and potentially missing pairs. Fall back to DefiLlama for price data when DexScreener returns empty results (see `references/data-providers.md`).

**Note:** DexScreener's public API doesn't have a "trending" or "top gainers" endpoint. Token discovery uses keyword search (`/latest/dex/search`) and web search as a fallback. For general discovery, ask the user what type of token they're looking for and search by keyword.

Category-Based Discovery

For specific categories (memecoins, DeFi, gaming tokens), use web search:

"trending {category} {chain} {current_year}"

Example: `"trending memecoins Base 2026"`

⚠️ UNTRUSTED INPUT: Web-Discovered Tokens

Tokens discovered via WebSearch are **UNTRUSTED**. Before proceeding with any web-discovered token:

1. **Label the source**: Explicitly tell the user "This token address was found via web search, not provided by you" 2. **Warn about risks**: "Web-discovered tokens may be scams, honeypots, or rug pulls" 3. **Require confirmation**: Use AskUserQuestion to get explicit user consent before generating a deep link for a web-discovered token 4. **Show provenance**: In the swap summary table, include a "Token Source" row showing whether each token was "User-provided" or "Web-discovered (unverified)"

**Never proceed with a web-discovered token without explicit user confirmation — via AskUserQuestion, or an equivalent conversational confirmation where that tool is unavailable.**

Present Options to User

After gathering token data, present options using AskUserQuestion:

{
  "questions": [
    {
      "question": "Which token would you like to swap to?",
      "header": "Token",
      "options": [
        { "label": "MOLT ($23M mcap)", "description": "$5.9M liquidity, $7.8M 24h volume" },
        { "label": "CLANKER ($31M mcap)", "description": "$3.1M liquidity, established token" },
        { "label": "CLAWSTR ($13M mcap)", "description": "$2.1M liquidity, high volume spike" }
      ],
      "multiSelec