swap-planner

Swap Planning

在 Uniswap 的所有支持链上规划代币兑换并生成深度链接。

运行时兼容性： 此技能使用 AskUserQuestion 进行交互式提问。如果你的运行时不支持 AskUserQuestion，请改用自然语言对话收集相同的参数。

概述

按以下步骤规划代币兑换：

1. 收集兑换意图（代币、数量、链）
2. 在链上验证代币合约
3. 必要时通过网页搜索了解代币
4. 生成深度链接，在 Uniswap 界面中打开并预填参数

生成的链接会打开 Uniswap，其中的所有参数都已准备好，可直接执行兑换。

注意： 在 SSH、容器化或无头环境中，打开浏览器（xdg-open/open）可能会失败。请始终醒目地显示 URL，以便用户在需要时复制并手动访问。

文件访问： 此技能对文件系统只有只读权限。除非用户明确要求，否则绝不要读取当前项目目录之外的文件。

工作流

步骤 0：发现代币（需要时）

如果用户想要发现代币，而不是兑换已知代币（例如“帮我找个 memecoin”“Base 上最近有哪些热门代币”），请先帮助他们探索，再继续兑换。

选项 A：按关键词搜索

DexScreener 使用具体关键词效果最佳：

# 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
    })'

推荐的搜索词： degen、pepe、ai、agent、meme、dog、cat 或具体的代币名称

选项 B：查看推广代币

获取正在推广的代币（选择有限）：

# 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
  })'

选项 C：网页搜索并验证

若要广泛发现代币（“最近有哪些热门代币”），请使用网页搜索查找代币，然后通过 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
  }'

网络 ID： 完整列表及其 DexScreener 和 DefiLlama 提供方 ID，参见 references/chains.md。常用 ID：ethereum、base、arbitrum、optimism、polygon、bsc、avalanche、unichain。

DexScreener 在不同链上的覆盖情况不一。 Ethereum、Base 和 Arbitrum 上有丰富的 Uniswap 数据。Celo、Blast、Zora 和 World Chain 上的 Uniswap 流动池覆盖有限，结果较少且可能缺少交易对。如果 DexScreener 未返回结果，请改用 DefiLlama 获取价格数据（参见 references/data-providers.md）。

注意： DexScreener 的公共 API 没有“热门”或“涨幅榜”端点。代币发现通过关键词搜索（/latest/dex/search）和备用网页搜索进行。对于一般性的代币发现，请询问用户想找哪类代币，并按关键词搜索。

按类别发现代币

对于特定类别（memecoin、DeFi、游戏代币），请使用网页搜索：

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

示例："trending memecoins Base 2026"

⚠️ 不可信输入：通过网页发现的代币

通过 WebSearch 发现的代币属于不可信内容。在继续处理任何通过网页发现的代币之前：

1. 标注来源：明确告知用户：“此代币地址是通过网页搜索找到的，并非由你提供”
2. 警告风险：“通过网页发现的代币可能是骗局、蜜罐或卷款跑路项目”
3. 要求确认：使用 AskUserQuestion，在为通过网页发现的代币生成深度链接前，明确征得用户同意
4. 展示来源信息：在兑换摘要表中加入“代币来源”一行，注明每种代币是“用户提供”还是“通过网页发现（未经验证）”

未经用户明确确认，绝不要继续处理通过网页发现的代币。确认必须通过 AskUserQuestion 完成；如果运行时不支持该工具，则使用等效的对话确认方式。

向用户展示选项

收集代币数据后，使用 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
    }
  ]
}

热门代币风险评估

推荐前先评估代币：

指标	低风险	中风险	高风险
市值	>$50M	$5M-$50M	<$5M
池 TVL	>$1M	$100k-$1M	<$100k
24 小时交易量	稳定	异常飙升	极低
合约年龄	>30 天	7-30 天	<7 天

展示选项时务必披露风险等级。 对于高风险代币，务必明确警告其波动性和潜在损失。

高风险代币的强制警告

满足以下任一条件时，生成深层链接前必须警告用户并取得明确确认（可用时通过 AskUserQuestion，否则通过对话确认）：

• 合约年龄 < 7 天："此代币合约创建时间不足 7 天。新代币成为骗局或 Rug Pull 的风险显著更高。"
• 池 TVL < $100k："此池流动性极低。您可能会遇到严重滑点和难以卖出的情况。"
• 未检测到卖出流动性："此代币可能是貔貅盘——可以买入但无法卖出的代币。请务必极其谨慎。"
• 市值 < $5M："这是一个高波动性的小市值代币。只投入您完全亏得起的资金。"

未经用户明确确认，不得为高风险代币生成深层链接。

---

第 1 步：收集兑换意图

从用户请求中提取：

参数	必填	示例
输入代币	是	ETH、USDC、代币地址
输出代币	是	USDC、WBTC、代币地址
数量	是	1.5 ETH、价值 $500 的代币
链	是（默认：Ethereum）	Base、Arbitrum 等

如果缺少任何必填参数，请使用 AskUserQuestion 并提供结构化选项：

缺少链时：

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

输入代币为 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
    }
  ]
}

缺少数量时：

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

请始终使用表单，而非纯文本问题，以提供更好的用户体验。

第 2 步：解析代币地址

对于代币符号，使用已知代币或网页搜索解析其地址：

原生代币：将 NATIVE 用作地址参数。

各链的常见代币——完整列表请参阅 ../../references/chains.md：

代币	Ethereum	Base	Arbitrum
USDC	0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913	0xaf88d065e77c8cC2239327C5EDb3A432268e5831
WETH	0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2	0x4200000000000000000000000000000000000006	0x82aF49447D8a07e3bd95BD0d56f35241523fBab1
WBTC	0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599	N/A	0x2f2a2543B76A4166549F7aaB2e75Bef0aefC5B0f

对于未知代币，请通过网页搜索查找合约地址，然后在链上验证。

步骤 3：验证代币合约（基础）

输入验证（执行任何 Shell 命令前必须进行）：

在将用户提供的值插入任何 Shell 命令前，验证所有输入：

• 代币地址必须匹配：^0x[a-fA-F0-9]{40}$
• 链／网络名称必须来自 ../../references/chains.md 中的允许列表
• 数量必须是有效的十进制数字（匹配：^[0-9]+\.?[0-9]*$）
• 拒绝任何包含 Shell 元字符（;、|、$、`、&、(、)、>、<、\、'、"、换行符）的输入

使用 curl 验证链上是否存在代币合约（RPC 调用）：

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

如果结果为 0x 或为空，则该地址不是有效的合约。

使用 cast 的替代方案（可选，需要 Foundry）：

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

**注意：**为确保更广泛的兼容性，优先使用上述 curl/RPC 方法。只有在环境中已提供 cast 时才使用它。此技能仅使用 cast code 验证合约。不要使用其他任何 cast 子命令。.claude/hooks/validate-forge-cast.sh 中的 PreToolUse 钩子会以编程方式强制执行此规定。

各链的 RPC URL——完整列表请参阅 ../../references/chains.md。

步骤 4：调研（如有需要）

对于不熟悉的代币，请使用网络搜索进行调研：

• 代币是否合法以及项目信息
• 近期新闻或安全问题
• Uniswap 上的流动性情况

在摘要中加入相关发现。

步骤 5：获取价格数据

生成深层链接前，获取当前价格以估算兑换输出。完整 API 详情请参阅 references/data-providers.md。

使用 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
  }'

网络 ID：ethereum、base、arbitrum、optimism、polygon、bsc、avalanche、unichain

流动性警告：

池 TVL	风险级别	操作
> $1M	低	正常继续
$100k - $1M	中	提醒用户可能存在滑点
< $100k	高	警告用户注意滑点风险

如果 API 不可用，可改用 DefiLlama 或网络搜索估算价格。

步骤 6：生成深层链接

构造 Uniswap 兑换 URL：

https://app.uniswap.org/swap?chain={chain}&inputCurrency={input}&outputCurrency={output}&value={amount}&field=INPUT

URL 参数：

参数	描述	值
chain	网络名称	ethereum、base、arbitrum、optimism、polygon、bnb、avalanche、celo、blast、zora、unichain、worldchain
inputCurrency	输入代币	地址或 NATIVE
outputCurrency	输出代币	地址或 NATIVE
value	数量	十进制数字（例如，1.5）
field	数值适用的字段	INPUT 或 OUTPUT

步骤 7：展示输出并打开浏览器

按以下格式组织回复：

1. 摘要：交换参数
2. 深层链接 URL（供参考）
3. 备注：风险或注意事项
4. 使用系统命令自动打开浏览器

输出格式示例：

## Swap Summary

| Parameter        | Value                      |
| ---------------- | -------------------------- |
| From             | 1 ETH                      |
| To               | USDC                       |
| Chain            | Base                       |
| Current Rate     | ~3,200 USDC per ETH        |
| Estimated Output | ~3,200 USDC                |
| Pool Liquidity   | $15.2M (Low slippage risk) |

### Notes

- Final amount depends on current market price
- Default slippage is 0.5% - adjust in Uniswap if needed
- Review all details in Uniswap before confirming

Opening Uniswap in your browser...

展示摘要后，在浏览器中打开 URL：

# Linux
xdg-open "https://app.uniswap.org/swap?chain=base&inputCurrency=NATIVE&outputCurrency=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&value=1&field=INPUT"

# macOS
open "https://app.uniswap.org/swap?..."

**环境限制：**在远程 SSH、容器化或无头环境中，打开浏览器可能会失败。如果 xdg-open/open 失败，请醒目地显示完整 URL，方便用户手动复制并粘贴：

**[Click here to open in Uniswap](https://app.uniswap.org/swap?...)**

Or copy this URL: `https://app.uniswap.org/swap?...`

始终展示摘要和 URL，方便用户查看并执行。

重要注意事项

滑点

深层链接使用 Uniswap 的默认滑点（0.5%）。对于波动性较大的代币或大额交易，请建议用户在界面中调整滑点。

Gas 估算

Gas 费用因链和网络拥堵情况而异。Base 和 Arbitrum 的 Gas 费用通常低于 Ethereum 主网。

代币验证

生成链接前，务必验证代币合约。诈骗代币经常使用与合法代币相似的名称。

价格影响

对于大额交易，请提醒用户注意潜在的价格影响。如果影响较大，建议拆分成多笔较小的交易。

支持的链

Uniswap 界面支持的所有链：

• Ethereum 主网（ethereum）
• Base（base）
• Arbitrum One（arbitrum）
• Optimism（optimism）
• Polygon（polygon）
• BNB Chain（bnb）
• Avalanche（avalanche）
• Celo（celo）
• Blast（blast）
• Zora（zora）
• World Chain（worldchain）
• Unichain（unichain）

其他资源

参考文件

• ../../references/chains.md - 链 ID、RPC URL、原生代币和常见代币地址
• references/data-providers.md - 用于查询价格和流动性的 DexScreener 和 DefiLlama API

示例

常见的交换场景：

• 在 Ethereum 上将 ETH 兑换为 USDC
• 在 Base 上将 ETH 兑换为 USDC（Gas 费用较低）
• 在 Arbitrum 上将 USDC 兑换为 WBTC