Uniswap V4 🦄

Swap tokens and read pool state on Uniswap V4 via the Universal Router.

Chains: Base (8453), Ethereum (1), Base Sepolia (84532)

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

Decision Tree

1. Read pool state? → src/pool-info.ts (free, no gas, no key)
2. Get swap quote? → src/quote.ts (free, uses on-chain V4Quoter)
3. Approve tokens? → src/approve.ts (write, ~100K gas, needs PRIVATE_KEY)
4. Execute swap? → src/swap.ts (write, ~300-350K gas, needs PRIVATE_KEY)
5. First time with an ERC20? → Run approve first, or use --auto-approve on swap

Scripts Reference

All scripts in src/. Run with npx tsx. Pass --help for usage.

pool-info.ts — Read Pool State (free)

Returns pool ID, sqrtPriceX96, tick, liquidity, fees, token symbols/decimals. Auto-detects the best pool by liquidity (or specify --fee/--tick-spacing).

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

Env: BASE_RPC_URL or ETH_RPC_URL (or pass --rpc)

quote.ts — Quote Swap Amounts (free)

Quotes exact input amounts via the on-chain V4Quoter contract (simulation, no tx). Returns expected output amount and gas estimate.

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

Env: BASE_RPC_URL or ETH_RPC_URL

approve.ts — Set Up Token Approvals (write)

Two-step Permit2 flow: ERC20 → Permit2, then Permit2 → Universal Router. Skips if already approved. Only needed for ERC20 tokens (not ETH).

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

Env: PRIVATE_KEY (required), BASE_RPC_URL

swap.ts — Execute Swap (write)

Exact-input swap via Universal Router. Quotes expected output first, applies slippage, then sends the transaction.

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 (sets up Permit2 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

Options: --slippage <bps> (default 50 = 0.5%), --recipient <addr>, --auto-approve, --json Env: PRIVATE_KEY (required), BASE_RPC_URL

Token Input

• ETH or eth → native ETH (address(0) in V4)
• Contract address → ERC20 token
• Common Base tokens: USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, WETH 0x4200000000000000000000000000000000000006

Environment Variables

* Only required for write operations. Read operations (pool-info, quote) don't need a key.

V4 Architecture Notes

• Singleton PoolManager holds all pools in one contract
• State read via StateView contract (wraps PoolManager storage)
• Swaps: Universal Router → PoolManager via V4_SWAP command
• Approvals: ERC20 → Permit2 → Universal Router (two-step)
• Pool ID: keccak256(abi.encode(currency0, currency1, fee, tickSpacing, hooks))
• Currency ordering: currency0 < currency1 by numeric value. ETH = address(0)
• Action sequence: SWAP_EXACT_IN_SINGLE (0x06) + SETTLE_ALL (0x0c) + TAKE_ALL (0x0f)
• See references/v4-encoding.md for full encoding reference

Error Handling

SECURITY

• PRIVATE_KEY must be provided via an environment variable or secret manager only.

• NEVER paste or send PRIVATE_KEY in chat.

• NEVER commit PRIVATE_KEY (or .env files) to git.

• Treat stdout/stderr as public logs (CI, terminals, chat). CI tests ensure the PRIVATE_KEY value is never printed.

• NEVER pass private keys as CLI arguments (rejected by all scripts)

• Private keys accepted via PRIVATE_KEY env var only

• All inputs validated: addresses (format), amounts (BigInt bounds), slippage (0-10000)

• No eval(), no exec(), no shell commands — pure TypeScript

• BigInt used everywhere for token amounts (no floating point, no overflow)

Testing

npm run test:unit      # Unit tests (no network)
npm run test:fork      # Fork tests (needs: anvil --fork-url https://mainnet.base.org)
npm run test:testnet   # Testnet reads (Base Sepolia)
npm run test:mainnet   # Mainnet smoke tests (read-only)
npm run security       # Security scan

References

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