swap-planner

What this skill does

# 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.

> **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:

```bash
# 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):

```bash
# 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:

```bash
# 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:

```text
"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.**

#### Present Options to User

After gathering token data, present options using AskUserQuestion:

```json
{
  "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" }
      ],
      "multiSelect": false
    }
  ]
}
```

#### Risk Assessment for Trending Tokens

Evaluate tokens before recommending:

| Metric       | Low Risk   | Medium Risk       | High Risk |
| ------------ | ---------- | ----------------- | --------- |
| Market Cap   | >$50M      | $5M-$50M          | <$5M      |
| Pool TVL     | >$1M       | $100k-$1M         | <$100k    |
| 24h Volume   | Consistent | Spiking unusually | Very low  |
| Contract Age | >30 days   | 7-30 days         | <7 days   |

**Always disclose risk level** when presenting options. For high-risk tokens, explicitly warn about volatility and potential for loss.

#### Mandatory Warnings for High-Risk Tokens

When ANY of these conditions are met, you MUST use AskUserQuestion to warn the user and get explicit confirmation before generating a deep link:

- **Contract age < 7 days**: "This token contract is less than 7 days old. New tokens carry significantly higher risk of being scams or rug pulls."
- **Pool TVL < $100k**: "This pool has very low liquidity. You may experience significant slippage and difficulty selling."
- **No sell liquidity detected**: "This token may be a honeypot — tokens that can be bought but not sold. Proceed with extreme caution."
- **Market cap < $5M**: "This is a micro-cap token with high volatility. Only invest what you can afford to lose entirely."

Do NOT generate a deep link for high-risk tokens without explicit user acknowledgment via AskUserQuestion.

---

### Step 1: Gather Swap Intent

Extract from the user's request:

| Parameter    | Required                | Example                   |
| ------------ | ----------------------- | ------------------------- |
| Input token  | Yes                     | ETH, USDC, token address  |
| Output token | Yes                     | USDC, WBTC, token address |
| Amount       | Yes                     | 1.5 ETH, $500 worth       |
| Chain        | Yes (default: Ethereum) | Base, Arbitrum, etc.      |

**If any required parameter is missing, use AskUserQuestion with structured options:**

For missing chain:

```json
{
  "questions": [
    {
      "question": "Which chain do you want to swap on?",
      "header": "Chain",
      "options": [
        { "label": "Base (Recommended)", "description": "Low gas fees, fast transactions" },
        { "label": "Ethereum", "description": "Main network, higher gas" },
        { "label": "Arbitrum", "description": "Low fees, Ethereum L2" },
        { "label": "Optimism", "description": "Low fees, Ethereum L2" }
      ],
      "multiSelect": false
    }
  ]
}
```

For missing output token (when input is ETH):

```json
{
  "questions": [
    {
      "question": "What token do you want to receive?",
      "header": "Output",
      "options": [
        { "label": "USDC", "description": "USD stablecoin" },
        { "label": "USDT", "description": "Tether stablecoin" },
        { "label": "DAI", "description": "Decentralized stablecoin" },
        { "label": "WBTC", "description": "Wrapped Bitcoin" }
      ],
      "multiSelect": f