# Swap Planner

> 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-support…

- **Type:** Skill
- **Install:** `agentstack add skill-uniswap-uniswap-ai-swap-planner`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Uniswap](https://agentstack.voostack.com/s/uniswap)
- **Installs:** 0
- **Category:** [Finance & Payments](https://agentstack.voostack.com/c/finance-and-payments)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Uniswap](https://github.com/Uniswap)
- **Source:** https://github.com/Uniswap/uniswap-ai/tree/main/packages/plugins/uniswap-driver/skills/swap-planner
- **Website:** https://developers.uniswap.org

## Install

```sh
agentstack add skill-uniswap-uniswap-ai-swap-planner
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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          | $1M       | $100k-$1M         | 30 days   | 7-30 days         | `, ` $1M       | Low        | Proceed normally              |
| $100k - $1M | Medium     | Note potential slippage       |
| < $100k     | High       | Warn user about slippage risk |

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

### Step 6: Generate Deep Link

Construct the Uniswap swap URL:

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

**URL Parameters:**

| Parameter        | Description                  | Values                                                                                                                       |
| ---------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `chain`          | Network name                 | `ethereum`, `base`, `arbitrum`, `optimism`, `polygon`, `bnb`, `avalanche`, `celo`, `blast`, `zora`, `unichain`, `worldchain` |
| `inputCurrency`  | Input token                  | Address or `NATIVE`                                                                                                          |
| `outputCurrency` | Output token                 | Address or `NATIVE`                                                                                                          |
| `value`          | Amount                       | Decimal number (e.g., `1.5`)                                                                                                 |
| `field`          | Which field value applies to | `INPUT` or `OUTPUT`                                                                                                          |

### Step 7: Present Output and Open Browser

Format the response with:

1. **Summary** of the swap parameters
2. **Deep link** URL (displayed for reference)
3. **Notes** about risks or considerations
4. **Open the browser** automatically using system command

**Example output format:**

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

**After displaying the summary, open the URL in the browser:**

```bash
# 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?..."
```

**Environment limitations:** Browser opening may fail in remote SSH, containerized, or headless environments. If `xdg-open`/`open` fails, display the full URL prominently so users can copy and paste it manually:

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

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

Always present the summary and URL so users can review and execute.

## Important Considerations

### Slippage

The deep link uses Uniswap's default slippage (0.5%). For volatile tokens or large trades, advise users to adjust slippage in the interface.

### Gas Estimation

Gas costs vary by chain and network congestion. Base and Arbitrum typically have lower gas than Ethereum mainnet.

### Token Verification

Always verify token contracts before generating links. Scam tokens often use similar names to legitimate tokens.

### Price Impact

For large trades, warn users about potential price impact. Suggest splitting into smaller trades if impact would be significant.

## Supported Chains

All chains supported by the Uniswap interface:

- Ethereum Mainnet (`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`)

## Additional Resources

### Reference Files

- **`../../references/chains.md`** - Chain IDs, RPC URLs, native tokens, common token addresses
- **`references/data-providers.md`** - DexScreener and DefiLlama APIs for prices and liquidity

### Examples

Common swap scenarios:

- ETH → USDC on Ethereum
- ETH → USDC on Base (lower gas)
- USDC → WBTC on Arbitrum

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Uniswap](https://github.com/Uniswap)
- **Source:** [Uniswap/uniswap-ai](https://github.com/Uniswap/uniswap-ai)
- **License:** MIT
- **Homepage:** https://developers.uniswap.org

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-uniswap-uniswap-ai-swap-planner
- Seller: https://agentstack.voostack.com/s/uniswap
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.