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. 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).

CODEBLOCK0

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.

CODEBLOCK1

Env: BASE_RPC_URL or INLINECODE26

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).

CODEBLOCK2

Env: PRIVATE_KEY (required), INLINECODE28

swap.ts — Execute Swap (write)

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

CODEBLOCK3

With auto-approval (sets up Permit2 if needed):
CODEBLOCK4

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

Token Input

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

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 V4SWAP command
• Approvals: ERC20 → Permit2 → Universal Router (two-step)
• Pool ID: INLINECODE43
• Currency ordering: currency0 < currency1 by numeric value. ETH = address(0)
• Action sequence: SWAPEXACTINSINGLE (0x06) + SETTLEALL (0x0c) + TAKEALL (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

CODEBLOCK5

References

• - V4 encoding reference: INLINECODE61
• Contract addresses: INLINECODE62
• V4 architecture: INLINECODE63