Swap Planning

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"

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

Risk Assessment for Trending Tokens

Evaluate tokens before recommending:

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

Step 1: Gather Swap Intent

Extract from the user's request:

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

For missing chain:

{
  "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):

{
  "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": false
    }
  ]
}

For missing amount:

{
  "questions": [
    {
      "question": "How much do you want to swap?",
      "header": "Amount",
      "options": [
        { "label": "0.1 ETH", "description": "~$320" },
        { "label": "0.5 ETH", "description": "~$1,600" },
        { "label": "1 ETH", "description": "~$3,200" },
        { "label": "Custom amount", "description": "Enter specific amount" }
      ],
      "multiSelect": false
    }
  ]
}

Always use forms instead of plain text questions for better UX.

Step 2: Resolve Token Addresses

For token symbols, resolve to addresses using known tokens or web search:

Native tokens: Use NATIVE as the address parameter.

Common tokens by chain - see ../../references/chains.md for full list:

For unknown tokens, use web search to find the contract address, then verify on-chain.

Step 3: Verify Token Contracts (Basic)

Input Validation (Required Before Any Shell Command):

Before interpolating user-provided values into any shell command, validate all inputs:

• Token addresses MUST match: ^0x[a-fA-F0-9]{40}$
• Chain/network names MUST be from the allowed list in ../../references/chains.md
• Amounts MUST be valid decimal numbers (match: ^[0-9]+\.?[0-9]*$)
• Reject any input containing shell metacharacters (;, |, $, `, &, (, ), >, <, \)

Verify token contracts exist on-chain using curl (RPC call):

# Check if address is a contract using eth_getCode
# IMPORTANT: Validate token_address matches ^0x[a-fA-F0-9]{40}$ before use
curl -s -X POST "$rpc_url" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg addr "$token_address" '{"jsonrpc":"2.0","method":"eth_getCode","params":[$addr,"latest"],"id":1}')" \
  | jq -r '.result'

If the result is 0x or empty, the address is not a valid contract.

Alternative with cast (optional, requires Foundry):

# Validate token_address matches ^0x[a-fA-F0-9]{40}$ before use
cast code "$token_address" --rpc-url "$rpc_url"

Note: The curl/RPC method above is preferred for broader compatibility. Only use cast if already available in the environment.

RPC URLs by chain - see ../../references/chains.md for full list.

Step 4: Research (If Needed)

For unfamiliar tokens, use web search to research:

• Token legitimacy and project info
• Recent news or security concerns
• Liquidity availability on Uniswap

Include relevant findings in the summary.

Step 5: Fetch Price Data

Before generating the deep link, fetch current prices to estimate swap output. See references/data-providers.md for full API details.

Quick price lookup with DexScreener:

# Get token price and pool liquidity
curl -s "https://api.dexscreener.com/token-pairs/v1/{network}/{address}" | \
  jq '[.[] | select(.dexId == "uniswap")][0] | {
    price: .priceUsd,
    liquidity: .liquidity.usd,
    volume24h: .volume.h24
  }'

Network IDs: ethereum, base, arbitrum, optimism, polygon, bsc, avalanche, unichain

Liquidity warnings:

If API is unavailable, fall back to DefiLlama or web search for price estimates.

Step 6: Generate Deep Link

Construct the Uniswap swap URL: