liquidity-planner

流动性头寸规划

规划并生成用于在 Uniswap v2、v3 和 v4 上创建流动性头寸的深层链接。

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

概述

通过以下步骤规划流动性头寸：

1. 收集 LP 意向（代币对、数量、版本）
2. 检查当前池价格和流动性
3. 根据当前价格建议价格范围
4. 生成深层链接，在 Uniswap 界面中打开并预填参数

生成的链接会打开 Uniswap，并填好创建头寸所需的所有参数。

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

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

工作流

第 1 步：收集 LP 意向

从用户的请求中提取：

参数	必填	默认值	示例
代币 A	是	-	ETH、USDC、地址
代币 B	是	-	USDC、WBTC、地址
数量	是	-	1 ETH、$1000
链	否	Ethereum	Base、Arbitrum
版本	否	V3	v2、v3、v4
费率档位	否	自动	0.05%、0.3%、1%
价格范围	否	建议	全范围、±5%、自定义

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

缺少链时：

{
  "questions": [
    {
      "question": "Which chain do you want to provide liquidity on?",
      "header": "Chain",
      "options": [
        { "label": "Base (Recommended)", "description": "Low gas, growing DeFi ecosystem" },
        { "label": "Ethereum", "description": "Deepest liquidity, higher gas" },
        { "label": "Arbitrum", "description": "Low fees, high volume" },
        { "label": "Optimism", "description": "Low fees, Ethereum L2" }
      ],
      "multiSelect": false
    }
  ]
}

缺少代币对时：

{
  "questions": [
    {
      "question": "Which token pair do you want to provide liquidity for?",
      "header": "Pair",
      "options": [
        { "label": "ETH / USDC", "description": "Most popular pair, high volume" },
        { "label": "ETH / USDT", "description": "High volume stablecoin pair" },
        { "label": "WBTC / ETH", "description": "Blue chip crypto pair" },
        { "label": "Custom pair", "description": "Specify your own tokens" }
      ],
      "multiSelect": false
    }
  ]
}

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

第 2 步：解析代币地址

将代币符号解析为地址。常见链上代币请参见 ../../references/chains.md。

对于未知代币，请使用网页搜索并进行链上验证。

不可信输入：网页搜索发现的代币

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

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

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

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

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

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

第 3 步：发现可用的池

在获取指标前，确认池是否存在并发现可用的费率档位。

使用 DexScreener 查找代币的池：

# Get all Uniswap pools for a token (replace {network} and {address})
# IMPORTANT: Validate address matches ^0x[a-fA-F0-9]{40}$ and network is from allowed list
curl -s "https://api.dexscreener.com/token-pairs/v1/{network}/{address}" | \
  jq '[.[] | select(.dexId == "uniswap")] | map({
    pairAddress,
    pair: "\(.baseToken.symbol)/\(.quoteToken.symbol)",
    version: .labels[0],
    liquidity: .liquidity.usd,
    volume24h: .volume.h24
  })'

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

从结果中识别：

• 可用的池及其地址（多个池 = 不同的费率档位）
• 池的 TVL（liquidity.usd），用于评估流动性深度
• 根据 labels[0] 判断版本（v3 或 v4）

**如果未找到 Uniswap 池：**该交易对可能还没有现有池。告知用户他们将创建一个新池并设置初始价格。

第 4 步：评估池的流动性

评估池是否有足够的流动性：

TVL 范围	评估	建议
> $1M	流动性充足	适合大多数仓位规模
$100K - $1M	流动性中等	适合最高约 $10K 的仓位
$10K - $100K	流动性较低	提醒用户注意滑点风险，建议减少仓位
< $10K	流动性极低	强烈提醒——IL 风险高，进场/出场时价格影响大

对于流动性较低的池，请给出警告：

⚠️ **Low Liquidity Warning**

This pool has only ${tvl} TVL. Consider:

- Your position will be a significant % of the pool
- Entry/exit may move the price against you
- Impermanent loss risk is amplified in thin pools
- You may want to use a wider price range for safety

第 5 步：获取池指标

在建议区间前，先获取池数据，以便做出明智的决策。完整的 API 详情请参见 references/data-providers.md。

使用 DefiLlama 获取池 APY 和交易量：

# Find Uniswap V3 pools for a token pair
curl -s "https://yields.llama.fi/pools" | jq '[.data[] | select(.project == "uniswap-v3" and .chain == "Ethereum" and (.symbol | test("WETH.*USDC|USDC.*WETH")))]'

要使用的响应字段：

字段	用途
apy	显示预期收益
tvlUsd	评估池的深度
volumeUsd1d	估算手续费收益
volumeUsd7d	检查交易量是否稳定

使用 DexScreener 获取当前价格：

# Get token prices from the pool data (already fetched in Step 3)
curl -s "https://api.dexscreener.com/token-pairs/v1/{network}/{address}" | \
  jq '[.[] | select(.dexId == "uniswap")][0] | {
    baseTokenPrice: .baseToken.priceUsd,
    quoteTokenPrice: .quoteToken.priceUsd
  }'

比较费率档位（如果有 APY 数据）：

# Find all fee tier variants and compare APY
curl -s "https://yields.llama.fi/pools" | jq '[.data[] | select(.project == "uniswap-v3" and (.symbol | test("WETH.*USDC")))] | map({symbol, tvlUsd, apy, volumeUsd1d})'

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

第 6 步：建议价格区间

根据当前价格和交易对类型，使用 AskUserQuestion 提供区间选项。

对于主流交易对（ETH/USDC、ETH/WBTC）：

{
  "questions": [
    {
      "question": "What price range do you want for your position? (Current: ~3,200 USDC/ETH)",
      "header": "Range",
      "options": [
        {
          "label": "±10% (Recommended)",
          "description": "2,880 - 3,520 USDC. Higher fees, monitor weekly"
        },
        { "label": "±20%", "description": "2,560 - 3,840 USDC. Balanced risk/reward" },
        { "label": "±50%", "description": "1,600 - 4,800 USDC. Rarely out of range" },
        { "label": "Full Range", "description": "Never out of range, lower fee efficiency" }
      ],
      "multiSelect": false
    }
  ]
}

对于稳定币交易对（USDC/USDT、DAI/USDC）：

{
  "questions": [
    {
      "question": "What price range for your stablecoin position?",
      "header": "Range",
      "options": [
        { "label": "±0.5% (Recommended)", "description": "0.995 - 1.005. Tight range, high fees" },
        { "label": "±1%", "description": "0.99 - 1.01. Standard for stables" },
        { "label": "±2%", "description": "0.98 - 1.02. Safer, lower fees" },
        { "label": "Full Range", "description": "Maximum safety, lowest fees" }
      ],
      "multiSelect": false
    }
  ]
}

建议逻辑：

• 稳定币交易对（USDC/USDT）：默认 ±0.5-1%
• 相关性较高的交易对（ETH/stETH）：默认 ±2-5%
• 主流交易对（ETH/USDC）：默认 ±10-20%
• 波动较大的交易对：默认 ±30-50% 或全区间

第 7 步：确定费率档位

如果该交易对有多个费率档位，请根据第 3 步的池数据让用户选择。

展示带有 APY 数据的费率档位选项：

{
  "questions": [
    {
      "question": "Which fee tier? (Based on current pool data)",
      "header": "Fee Tier",
      "options": [
        { "label": "0.30% (Recommended)", "description": "TVL: $15M, APY: 12.5%, highest volume" },
        { "label": "0.05%", "description": "TVL: $8M, APY: 8.2%, lower fees per trade" },
        { "label": "1.00%", "description": "TVL: $2M, APY: 18.1%, less competition" }
      ],
      "multiSelect": false
    }
  ]
}

费率档位指南：

手续费	刻度间距	最适合
0.01% (100)	1	稳定币交易对
0.05% (500)	10	相关性较高的交易对（ETH/stETH）
0.30% (3000)	60	大多数交易对（默认）
1.00% (10000)	200	小众/波动较大的交易对

**v4 费率档位：**借助 hooks 可实现动态手续费。默认采用与 V3 类似的费率档位。

如果池数据显示某个档位的 APY 或交易量显著更高，请推荐该档位。

步骤 8：生成深层链接

构造 Uniswap 头寸创建 URL：

基础 URL： https://app.uniswap.org/positions/create

URL 参数：

参数	描述	格式
chain	网络名称	ethereum、base 等
currencyA	第一个代币	地址或 NATIVE
currencyB	第二个代币	地址或 NATIVE
priceRangeState	区间配置	JSON（仅编码引号）
depositState	存入数量	JSON（仅编码引号）
fee	费率等级配置	JSON（仅编码引号）
hook	v4 hook 地址（可选）	地址或 undefined
step	流程步骤	1（用于创建）

重要：URL 编码

仅对 JSON 值中的双引号进行编码（" → %22）。不要对花括号 {} 或冒号 : 进行编码。

priceRangeState JSON 结构：

适用于全区间：

{
  "priceInverted": false,
  "fullRange": true,
  "minPrice": "",
  "maxPrice": "",
  "initialPrice": "",
  "inputMode": "price"
}

适用于自定义区间：

{
  "priceInverted": false,
  "fullRange": false,
  "minPrice": "2800",
  "maxPrice": "3600",
  "initialPrice": "",
  "inputMode": "price"
}

depositState JSON 结构：

{ "exactField": "TOKEN0", "exactAmounts": { "TOKEN0": "1.0" } }

注意：currencyA 使用 TOKEN0，currencyB 使用 TOKEN1。

fee JSON 结构：

{ "feeAmount": 3000, "tickSpacing": 60, "isDynamic": false }

不同费率对应的 Tick 间距：

费率	Tick 间距
100 (0.01%)	1
500 (0.05%)	10
3000 (0.30%)	60
10000 (1.00%)	200

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

按以下格式组织回复：

1. 摘要：头寸参数
2. 价格区间可视化（非全区间时）
3. 注意事项：无常损失（IL）和管理
4. 使用系统命令自动打开浏览器

输出格式示例：

## Liquidity Position Summary

| Parameter | Value                   |
| --------- | ----------------------- |
| Pair      | ETH / USDC              |
| Chain     | Base                    |
| Version   | V3                      |
| Fee Tier  | 0.30%                   |
| Deposit   | 1 ETH + equivalent USDC |

### Pool Analytics

| Metric      | Value  |
| ----------- | ------ |
| Current APY | 12.5%  |
| 24h Volume  | $2.1M  |
| 7d Volume   | $14.8M |
| Pool TVL    | $15.2M |

### Price Range

| Metric        | Value               |
| ------------- | ------------------- |
| Current Price | ~3,200 USDC per ETH |
| Min Price     | 2,800 USDC per ETH  |
| Max Price     | 3,600 USDC per ETH  |
| Range Width   | ±12.5%              |

### Considerations

- **Impermanent Loss**: If ETH moves outside your range, you'll hold 100% of one asset
- **Rebalancing**: Monitor position and adjust range if price moves significantly
- **Fee Earnings**: Tighter ranges earn more fees but require more active management
- **Gas Costs**: Creating and managing positions costs gas
- **APY Note**: Shown APY is historical and may vary with market conditions

Opening Uniswap in your browser...

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

# Linux - note: only quotes are encoded (%22), not braces or colons
xdg-open "https://app.uniswap.org/positions/create?currencyA=NATIVE&currencyB=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&chain=base&fee={%22feeAmount%22:3000,%22tickSpacing%22:60,%22isDynamic%22:false}&priceRangeState={%22priceInverted%22:false,%22fullRange%22:false,%22minPrice%22:%222800%22,%22maxPrice%22:%223600%22,%22initialPrice%22:%22%22,%22inputMode%22:%22price%22}&depositState={%22exactField%22:%22TOKEN0%22,%22exactAmounts%22:{%22TOKEN0%22:%221%22}}&step=1"

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

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

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

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

始终展示摘要和 URL，方便用户查看并创建头寸。

版本选择

有关详细的版本比较（v2/v3/v4 差异、费率等级、Tick 间距），请参阅 references/position-types.md。

快速指南：

• V2：仅支持全区间，最简单，Gas 费最低
• V3：集中流动性，最常见的选择
• V4：支持 hooks 的高级功能，可用性有限

重要注意事项

无常损失（IL）

提醒用户注意无常损失风险：

• 当代币价格偏离入场价格时，会产生无常损失
• 区间越窄，无常损失越大，但手续费收益也越高
• 全区间可最大限度降低无常损失，但手续费效率较低

头寸管理

集中流动性需要主动管理：

• 监控价格是否保持在区间内
• 价格接近区间边界时重新平衡
• 调整头寸时考虑 Gas 成本

资金要求

对于使用自定义区间的 V3 头寸：

• 当前价格在区间外时，可以只存入一种代币
• 当前价格在区间内时，需要按照价格和区间决定的比例存入两种代币

支持的链

支持所有 Uniswap 支持的链；各链支持的版本请参阅 references/position-types.md。

其他资源

参考文件

• ../../references/chains.md - 链配置和代币地址（与 swap-planner 共用）
• references/position-types.md - v2/v3/v4 差异、费率等级、Tick 间距
• references/data-providers.md - 用于发现池和收益率的 DexScreener 和 DefiLlama API

URL 编码

深层链接中的 JSON 参数只应对双引号进行编码（" → %22）。请勿对花括号 {}、冒号 : 或逗号 , 进行编码。

?priceRangeState={%22fullRange%22:true}

解码后：

{ "fullRange": true }

为什么？ Uniswap 界面需要类似 JSON 的参数结构。对花括号和冒号进行完整 URL 编码会导致解析失败。只需对引号进行编码，以避免与 URL 语法冲突。