---
name: liquidity
description: Manage Uniswap V4 and V3 liquidity positions on Base — list positions, read pool state, mint/add/remove liquidity, and collect fees.
metadata: { "openclaw": { "emoji": "🌊" } }
---

# Liquidity — Uniswap Position Management

## When to Use

- User wants to provide liquidity on Uniswap V3 or V4
- User wants to view their existing LP positions
- User wants to add liquidity to an existing position
- User wants to remove liquidity or withdraw
- User wants to collect accumulated trading fees from positions
- User wants to check a V4 pool's current state (price, tick, liquidity)

## When NOT to Use

- Simple token swaps (use defi-trading skill)
- Checking token prices (use defi-trading skill)
- Launching new tokens (use clawnch-launchpad skill)

## Tool: `liquidity`

All write operations go through ClawnchConnect for approval.

### Read Actions

| Action | Params | Description |
|--------|--------|-------------|
| `positions` | — | List all V3 LP positions for the connected wallet |
| `v4_position` | token_id | Read a specific V4 position by NFT token ID |
| `v4_pool` | token0, token1, fee?, tick_spacing?, hook_address? | Read V4 pool state: price, tick, liquidity |

### Write Actions

| Action | Params | Description |
|--------|--------|-------------|
| `v3_mint` | token0, token1, fee, tick_lower, tick_upper, amount0, amount1 | Open a new V3 position |
| `v4_mint` | token0, token1, fee, tick_spacing, tick_lower, tick_upper, amount0, amount1, hook_address?, slippage_bps? | Open a new V4 position |
| `v3_add` | token_id, amount0, amount1 | Add liquidity to an existing V3 position |
| `v3_remove` | token_id, percentage? | Remove liquidity (default: 100% = full withdrawal) |
| `v3_collect` | token_id | Collect accumulated fees |

### Pool Parameters

| Param | Default | Description |
|-------|---------|-------------|
| `token0` | — | Lower address token (addresses must be sorted) |
| `token1` | — | Higher address token |
| `fee` | 3000 | Fee tier in hundredths of bps (500 = 0.05%, 3000 = 0.3%, 10000 = 1%) |
| `tick_spacing` | 60 | V4 tick spacing |
| `hook_address` | 0x0000...0000 | V4 hook contract (zero = no hook) |
| `slippage_bps` | 50 | Slippage tolerance (50 = 0.5%) |

### Tick Range Selection

The tick range determines the price range where your position earns fees:

- **Narrow range** (e.g., current tick +/- 100): Higher capital efficiency, more fees when price is in range, but goes out of range more often
- **Wide range** (e.g., current tick +/- 10000): Lower capital efficiency, earns less per trade but stays in range longer
- **Full range** (min tick to max tick): Similar to V2-style liquidity, always earning but very low efficiency

Use `v4_pool` to check the current tick, then set `tick_lower` and `tick_upper` around it.

### Fee Tiers

| Fee | Use Case |
|-----|----------|
| 500 (0.05%) | Stablecoin pairs (USDC/USDT) |
| 3000 (0.3%) | Standard pairs (ETH/USDC) |
| 10000 (1%) | Exotic or volatile pairs |

### Typical Workflow

1. Check current pool state: `action: v4_pool, token0: ..., token1: ...`
2. View existing positions: `action: positions`
3. Mint new position: `action: v3_mint, token0: ..., token1: ..., tick_lower: ..., tick_upper: ..., amount0: "1.0", amount1: "1000"`
4. Monitor fees: `action: positions` (check unclaimed fees)
5. Collect fees: `action: v3_collect, token_id: ...`
6. Remove liquidity: `action: v3_remove, token_id: ..., percentage: 50`

### Important Notes

- Token addresses must be sorted: `token0` < `token1` (lower address first)
- Amounts are in human-readable units (e.g., "1.0" = 1 token, not wei)
- All writes require gas — pre-flight balance check is automatic
- Removing 100% of liquidity also burns the position NFT
- V4 positions with hooks interact with the hook contract on every swap — verify the hook is safe
- Impermanent loss is real — explain the risks to users before they add liquidity