| 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
- Check current pool state:
action: v4_pool, token0: ..., token1: ...
- View existing positions:
action: positions
- Mint new position:
action: v3_mint, token0: ..., token1: ..., tick_lower: ..., tick_upper: ..., amount0: "1.0", amount1: "1000"
- Monitor fees:
action: positions (check unclaimed fees)
- Collect fees:
action: v3_collect, token_id: ...
- 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
