Uniswap V4

swap tokens and read pool state on uniswap v4 via the universal router.

chains: base (8453), ethereum (1), base sepolia (84532)

contract	base	ethereum
poolmanager	0x498581fF718922c3f8e6A244956aF099B2652b2b	0x000000000004444c5dc75cB358380D2e3dE08A90
universalrouter	0x6ff5693b99212da76ad316178a184ab56d299b43	0x66a9893cC07D91D95644AEDD05D03f95e1dBA8Af
permit2	0x000000000022D473030F116dDEE9F6B43aC78BA3	0x000000000022D473030F116dDEE9F6B43aC78BA3
stateview	0xa3c0c9b65bad0b08107aa264b0f3db444b867a71	0x7ffe42c4a5deea5b0fec41c94c136cf115597227
v4quoter	0x0d5e0f971ed27fbff6c2837bf31316121532048d	0x52f0e24d1c21c8a0cb1e5a5dd6198556bd9e1203

addresses from docs.uniswap.org/contracts/v4/deployments, verified 2026-02-08.

intent

use this skill when you need to swap tokens on uniswap v4, read pool state (price, liquidity, tick, fees), get quotes for expected output amounts, or set up token approvals. the skill covers read operations (free, no private key), quote operations (free simulation via on-chain v4quoter), and write operations (swaps and approvals). supports base, ethereum, and base sepolia testnet. use pool-info for discovery, quote for exact output prediction, approve for permit2 setup, and swap for execution with slippage protection.

inputs

environment variables (set before running):

variable	used by	required	description
PRIVATE_KEY	approve.ts, swap.ts	yes*	wallet private key (64 hex chars, 0x prefix)
BASE_RPC_URL	all scripts (base)	no	base mainnet rpc endpoint (fallback: public)
ETH_RPC_URL	all scripts (eth)	no	ethereum mainnet rpc endpoint (fallback: public)
BASE_SEPOLIA_RPC_URL	all scripts (testnet)	no	base sepolia rpc endpoint (fallback: public)

*only required for write operations (approve, swap). read operations (pool-info, quote) work without PRIVATE_KEY.

external connections:

• rpc endpoint: base, ethereum, or base sepolia mainnet. provide via env var or pass --rpc <url> to override.
• contract calls: read-only calls to poolmanager (state), stateview (state views), v4quoter (quote simulation), and write calls to permit2 + universalrouter (approvals and swaps). no external api or oauth required.
• private key security: never pass private key as cli argument. only accept via PRIVATE_KEY env var. all scripts reject private keys in cli args and log warnings if detected.

token identifiers:

• ETH or eth (case-insensitive): native ether, resolved to address(0) in v4.
• contract address (0x-prefixed hex string, 40 chars): erc20 token.
• common base tokens: usdc 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, weth 0x4200000000000000000000000000000000000006.

chain parameter:

• --chain base (default): base mainnet (8453).
• --chain ethereum: ethereum mainnet (1).
• --chain base-sepolia: base sepolia testnet (84532).

procedure

step 1: read pool state (no write, no key required)

input: token0 (symbol or address), token1 (symbol or address), chain, optional rpc url.

command:

npx tsx src/pool-info.ts \
  --token0 ETH \
  --token1 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \
  --chain base \
  --rpc $BASE_RPC_URL

output: pool id, sqrtpricex96, tick, liquidity, fee (in bps), token0/token1 symbols and decimals. if multiple pools exist for the pair, auto-selects by highest liquidity. to specify a pool, add --fee 500 or --tick-spacing 1.

edge cases handled:

• no pool found for pair on this chain: error with suggestion to check addresses.
• rpc unreachable or times out (>30s default): error with fallback to public rpc.
• empty pool (zero liquidity): returns pool id but notes liquidity = 0. swap will fail unless liquidity is added.

---

step 2: get swap quote (no write, no key required)

input: token-in (symbol or address), token-out (symbol or address), amount (wei for erc20, raw decimals for eth), chain, optional rpc url.

command:

npx tsx src/quote.ts \
  --token-in ETH \
  --token-out 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \
  --amount 10000000000000000 \
  --chain base \
  --rpc $BASE_RPC_URL

output: expected output amount (in wei, raw decimals), gas estimate (in wei), slippage-adjusted minimum output amount. all amounts are bigint, no floating point.

edge cases handled:

• amount exceeds uint128 max: error with suggestion to use smaller amount.
• insufficient liquidity in pool: quote fails with "insufficient liquidity" message.
• rpc timeout: returns error, suggest retry or fallback rpc.

---

step 3: approve tokens for swap (write, requires PRIVATE_KEY)

input: token address (erc20 only, not eth), chain, optional rpc url, optional --json for json output.

command:

PRIVATE_KEY=0x... npx tsx src/approve.ts \
  --token 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \
  --chain base \
  --rpc $BASE_RPC_URL \
  --json

procedure (two-step permit2 flow):

1. check erc20 allowance to permit2. if zero, send approval tx (erc20.approve(permit2, uint256.max)).
2. check permit2 allowance to universalrouter. if zero, send approval tx (permit2.approve(token, universalrouter, uint160.max, uint48 expiry)).
3. return tx hashes and final allowances.

output: json object with tx hashes, allowance values, and status. if already approved, returns "already approved" and skips both txs.

edge cases handled:

• wallet has zero balance: approve still succeeds (allowance set, but swap will later fail due to insufficient balance).
• rpc is write-restricted (infura free tier): error with message to use a paid endpoint.
• transaction reverts: returns revert reason (e.g., "insufficient gas").
• private key invalid: error immediately, key not leaked to logs.

---

step 4: execute exact-input swap (write, requires PRIVATE_KEY)

input: token-in (symbol or address), token-out (symbol or address), amount (wei), slippage (bps, default 50 = 0.5%), chain, optional rpc url, optional --auto-approve, optional --recipient <address>, optional --json.

command:

PRIVATE_KEY=0x... npx tsx src/swap.ts \
  --token-in ETH \
  --token-out 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \
  --amount 10000000000000000 \
  --slippage 50 \
  --chain base \
  --rpc $BASE_RPC_URL \
  --json

with auto-approval (runs approve step 3 if needed):

PRIVATE_KEY=0x... npx tsx src/swap.ts \
  --token-in 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \
  --token-out ETH \
  --amount 25000000 \
  --slippage 100 \
  --auto-approve \
  --chain base \
  --rpc $BASE_RPC_URL

procedure:

1. if --auto-approve is set and token-in is erc20, run approve step (step 3) first.
2. call quote.ts to get expected output amount and gas estimate.
3. calculate minimum output: expected_output * (10000 - slippage) / 10000. slippage in bps (50 = 0.5%).
4. encode swap action: v4_swap_exact_in_single + settle_all + take_all (see v4 encoding reference).
5. send transaction via universalrouter. recipient defaults to connected wallet; override with --recipient.
6. wait for tx confirmation (30 second timeout).
7. return tx hash, amounts in / out, actual slippage incurred.

output: json object with tx hash, token-in amount, token-out amount, gas used (wei), effective price. if --json not set, human-readable text summary.

edge cases handled:

• insufficient balance: tx reverts with "insufficient balance" message.
• slippage too tight: tx reverts with "slippage exceeded" (minimum output > actual output).
• pool has no liquidity: quote fails or swap reverts with "insufficient liquidity".
• recipient address invalid (not checksummed, wrong length): error before sending tx.
• transaction timeout (no confirmation after 30s): returns error and tx hash for manual verification.
• private key invalid or missing: error, key never leaked.
• rpc endpoint rate-limited: retry up to 3 times with exponential backoff (1s, 2s, 4s).

---

step 5: optional - set recipient address (swap only)

input: --recipient <0x...> flag on swap.ts.

output: tokens sent to recipient instead of connected wallet. if not set, defaults to wallet derived from private key.

---

decision points

if reading pool state only (pool-info.ts):

• no private key required. use if agent only needs to discover pools or check prices.

if quoting swap amounts (quote.ts):

• no private key required. use to predict output before committing to a swap. quote is free and reads on-chain state via simulation.

if approving tokens (approve.ts):

• requires PRIVATE_KEY env var. use before first swap with a new erc20 token. skips if already approved. eth does not need approval. two-step flow: erc20 -> permit2, then permit2 -> universalrouter.

if executing swap without auto-approval (swap.ts, no --auto-approve):

• requires PRIVATE_KEY env var. assumes token-in (if erc20) is already approved. if not approved, tx reverts with "insufficient allowance". run approve.ts first or use --auto-approve flag.

if executing swap with auto-approval (swap.ts, --auto-approve):

• requires PRIVATE_KEY env var. runs approve.ts internally if token-in is erc20 and not yet approved. skips approval if already approved. eth does not trigger approval step.

if token-in is ETH:

• no approval needed. skip approve.ts entirely. swap proceeds directly.

if token-in is ERC20:

• approval required. check with pool-info first, then call approve.ts, then call swap.ts. or use --auto-approve on swap.ts to combine steps 2-3.

if multiple pools exist for a token pair:

• pool-info.ts auto-selects the pool with highest liquidity. to specify a different pool, pass --fee <bps> (e.g., --fee 500 for 0.5% fee) or --tick-spacing <spacing>.

if quote fails:

• pool exists but swap amount is too large or pool lacks liquidity. reduce amount or check pool liquidity with pool-info.ts. if pool is empty, liquidity may have been removed.

if swap reverts on chain:

• common causes: (1) insufficient balance, (2) slippage exceeded (actual output < minimum output), (3) insufficient allowance (erc20 not approved), (4) pool has no liquidity. check wallet balance with web3.eth.getBalance(), increase --slippage to relax bounds, ensure approval is complete, or choose a different pool.

if private key is missing:

• error is thrown before any network call. set PRIVATE_KEY env var. example: export PRIVATE_KEY=0x123abc... (never paste in chat or commit to git).

if rpc endpoint is unreachable:

• scripts fall back to a public rpc if configured, or error and suggest passing --rpc <url>. timeout is 30 seconds per call.

---

output contract

pool-info.ts output (stdout or --json):

{
  "poolId": "0x...",
  "token0": "0x...",
  "token1": "0x...",
  "fee": 500,
  "tickSpacing": 1,
  "sqrtPriceX96": "1234567890...",
  "tick": 42000,
  "liquidity": "9876543210...",
  "symbol0": "ETH",
  "symbol1": "USDC",
  "decimals0": 18,
  "decimals1": 6
}

quote.ts output (stdout or --json):

{
  "amountIn": "10000000000000000",
  "amountOut": "12345678901",
  "amountOutMinimum": "12250000000",
  "gasEstimate": "350000",
  "executionPrice": "1.2345"
}

approve.ts output (stdout or --json):

{
  "token": "0x...",
  "permit2AllowanceTx": "0x...",
  "universalRouterAllowanceTx": "0x...",
  "status": "approved",
  "erc20ToPermit2": "115792089237316195423570985008687907853269984665640564039457584007913129639935",
  "permit2ToUniversalRouter": "115792089237316195423570985008687905694156674177411857430378968448384"
}

swap.ts output (stdout or --json):

{
  "transactionHash": "0x...",
  "blockNumber": 12345678,
  "from": "0x...",
  "to": "0x...",
  "amountIn": "10000000000000000",
  "amountOut": "12300000000",
  "executionPrice": "1.23",
  "gasUsed": "325000",
  "gasPrice": "50000000000",
  "slippageIncurred": "0.4%"
}

all amounts are strings (bigint), no floating point. gas values in wei. slippage as percentage string.

error responses (any script):

{
  "error": "descriptive message",
  "code": "ERROR_CODE",
  "suggestion": "how to fix"
}

or plain text to stderr if --json not set.

---

outcome signal

pool-info.ts succeeds when:

• script prints pool id, addresses, fee, tick, liquidity, and token symbols. if running without --json, human-readable summary appears. exit code 0.

quote.ts succeeds when:

• script prints expected output amount, minimum output (with slippage applied), and gas estimate. numbers are in wei, no decimals. exit code 0.

approve.ts succeeds when:

• both approval transactions are mined and confirmed. script prints tx hashes and final allowance amounts. if already approved, script prints "already approved" and exits with code 0 (no txs sent).
• user can verify on etherscan or block explorer: token contract shows permit2 allowance = uint256.max for token, permit2 contract shows universalrouter allowance = uint160.max.

swap.ts succeeds when:

• transaction is mined and confirmed. script prints tx hash, amountIn, amountOut, execution price, and gas used. exit code 0.
• user can verify on etherscan: tx shows "success", logs include swap event with input/output amounts. token balances updated: token-in decreased, token-out increased. actual amount out >= minimum output (no slippage violation).
• if --recipient was used, tokens appear in recipient wallet. if not, tokens appear in connected wallet.

any script fails when:

• exit code is non-zero. error message printed to stderr. if --json, error response includes code and suggestion. user should check:
  • PRIVATE_KEY is set (write operations only).
  • rpc endpoint is reachable (check --rpc or env var).
  • token addresses are valid checksummed hex strings.
  • amounts are within uint128 bounds.
  • slippage is 0-10000 bps.
  • wallet has sufficient balance (for swaps) or allowance (for approvals).

---

notes

v4 architecture:

• singleton poolmanager holds all pools in one contract. each pool identified by poolId = keccak256(abi.encode(currency0, currency1, fee, tickspacing, hooks)).
• state read via stateview contract, which wraps poolmanager storage reads (safe, read-only).
• swaps route through universalrouter -> poolmanager via v4_swap_exact_in_single action.
• approvals follow two-step permit2 pattern: erc20 -> permit2, then permit2 -> universalrouter. eth bypass both.
• currency ordering: currency0 < currency1 by numeric value. eth = address(0), always comes first.

security reminders:

• PRIVATE_KEY must be in environment variable only. never paste in cli, chat, or logs.
• all scripts validate inputs: addresses (checksummed or lowercased, correct length), amounts (bigint, no overflow), slippage (0-10000 bps).
• no eval(), exec(), or shell commands. pure typescript with strict types.
• ci tests ensure PRIVATE_KEY is never printed to stdout/stderr.

testing:

npm run test:unit      # unit tests, no network
npm run test:fork      # fork tests, requires local anvil
npm run test:testnet   # base sepolia reads
npm run test:mainnet   # mainnet smoke tests (read-only)
npm run security       # static security scan

references:

• v4 encoding reference: references/v4-encoding.md
• contract addresses: references/addresses.md
• v4 architecture: references/v4-architecture.md

---

original author: clawhub.