Uniswap V3 Swap

Uniswap V3 Swap — Generalized Token Swaps on Base

Swap any ERC-20 token pair on Uniswap V3. This skill teaches the agent to discover the right pool, quote the expected output, construct the swap calldata, and execute via keypo-wallet — for any token pair, not just predetermined ones.

Contract Addresses

Base Sepolia (chain 84532)

Base Mainnet (chain 8453)

Known Testnet Tokens (Base Sepolia)

For tokens not listed here, ask the user for the contract address, or use the contract-learner skill to look up a token by address.

Swap Workflow

Follow these steps in order. Each step is a separate cast call or cast calldata command. Do not skip steps — the agent must gather information before constructing the transaction.

Step 1: Resolve Token Addresses and Decimals

Determine the tokenIn and tokenOut contract addresses. If the user says "ETH", use the WETH address — Uniswap V3 only works with ERC-20 tokens, not native ETH.

For each token, confirm its decimals:

cast call <token-address> "decimals()(uint8)" --rpc-url https://sepolia.base.org

You need decimals to convert human-readable amounts (e.g. "0.001 ETH", "50 USDC") to raw integers:

• 0.001 ETH → 1000000000000000 (0.001 × 10^18)
• 50 USDC → 50000000 (50 × 10^6)

If you don't know a token's address, ask the user. Do not guess token addresses.

Step 2: Find a Pool

Uniswap V3 pools are keyed by (tokenA, tokenB, fee). The fee tiers are:

Query the factory for each fee tier until you find a pool (non-zero address):

# Try 500 first (most common for major pairs)
cast call <FACTORY> "getPool(address,address,uint24)(address)" <tokenIn> <tokenOut> 500 --rpc-url https://sepolia.base.org

# If zero, try 3000
cast call <FACTORY> "getPool(address,address,uint24)(address)" <tokenIn> <tokenOut> 3000 --rpc-url https://sepolia.base.org

# If zero, try 10000
cast call <FACTORY> "getPool(address,address,uint24)(address)" <tokenIn> <tokenOut> 10000 --rpc-url https://sepolia.base.org

# If zero, try 100
cast call <FACTORY> "getPool(address,address,uint24)(address)" <tokenIn> <tokenOut> 100 --rpc-url https://sepolia.base.org

A return value of 0x0000000000000000000000000000000000000000 means no pool exists at that fee tier. If no pool exists at any fee tier, tell the user there is no Uniswap V3 liquidity for this pair on this chain.

On testnets, liquidity may be very thin or nonexistent for many pairs. Common testnet pairs with liquidity: WETH/USDC.

Step 3: Check Pool Liquidity

Once you find a pool address, verify it has liquidity:

cast call <pool-address> "liquidity()(uint128)" --rpc-url https://sepolia.base.org

If liquidity is 0, the pool exists but has no liquidity — the swap will fail. Tell the user and try the next fee tier.

Step 4: Get a Quote

Use QuoterV2 to simulate the swap and get the expected output amount. This is a read-only call — no gas needed.

# For exact input (you know how much you're putting in):
cast call <QUOTER_V2> \
  "quoteExactInputSingle((address,address,uint256,uint24,uint160))(uint256,uint160,uint32,uint256)" \
  "(<tokenIn>,<tokenOut>,<amountIn>,<fee>,0)" \
  --rpc-url https://sepolia.base.org

The tuple parameter order is: (tokenIn, tokenOut, amountIn, fee, sqrtPriceLimitX96). Set sqrtPriceLimitX96 to 0 for no price limit.

The return values are: (amountOut, sqrtPriceX96After, initializedTicksCrossed, gasEstimate).

Convert amountOut to human-readable using the output token's decimals and show it to the user before executing. For example: "Swapping 0.001 WETH → expected ~2.34 USDC. Proceed?"

If the quote call reverts, the pool likely has insufficient liquidity for the requested amount. Try a smaller amount or a different fee tier.

Step 5: Check Balance and Allowance

Before executing, verify the wallet has enough of the input token:

# Check tokenIn balance
cast call <tokenIn> "balanceOf(address)(uint256)" <wallet-address> --rpc-url https://sepolia.base.org

# Check current allowance for the SwapRouter
cast call <tokenIn> "allowance(address,address)(uint256)" <wallet-address> <SWAP_ROUTER> --rpc-url https://sepolia.base.org

If the balance is insufficient, tell the user. If the allowance is less than amountIn, you'll need to approve in the same batch (see Step 6).

Step 6: Construct and Execute the Swap

Case A: TokenIn is an ERC-20 (already have the token)

If allowance is sufficient, just swap:

SWAP_DATA=$(cast calldata \
  "exactInputSingle((address,address,uint24,address,uint256,uint256,uint160))" \
  "(<tokenIn>,<tokenOut>,<fee>,<recipient>,<amountIn>,<amountOutMinimum>,0)")

keypo-wallet send --key <key-name> --to <SWAP_ROUTER> --data $SWAP_DATA

If allowance is insufficient, approve + swap in one batch:

APPROVE_DATA=$(cast calldata "approve(address,uint256)" <SWAP_ROUTER> <amountIn>)

SWAP_DATA=$(cast calldata \
  "exactInputSingle((address,address,uint24,address,uint256,uint256,uint160))" \
  "(<tokenIn>,<tokenOut>,<fee>,<recipient>,<amountIn>,<amountOutMinimum>,0)")

echo "[
  {\"to\": \"<tokenIn>\", \"value\": \"0\", \"data\": \"$APPROVE_DATA\"},
  {\"to\": \"<SWAP_ROUTER>\", \"value\": \"0\", \"data\": \"$SWAP_DATA\"}
]" | keypo-wallet batch --key <key-name> --calls -

Case B: Swapping from native ETH

Native ETH must be wrapped to WETH first. Then approve + swap:

DEPOSIT_DATA=$(cast calldata "deposit()")

APPROVE_DATA=$(cast calldata "approve(address,uint256)" <SWAP_ROUTER> <amountIn>)

SWAP_DATA=$(cast calldata \
  "exactInputSingle((address,address,uint24,address,uint256,uint256,uint160))" \
  "(<WETH>,<tokenOut>,<fee>,<recipient>,<amountIn>,<amountOutMinimum>,0)")

echo "[
  {\"to\": \"<WETH>\", \"value\": \"<amountIn>\", \"data\": \"$DEPOSIT_DATA\"},
  {\"to\": \"<WETH>\", \"value\": \"0\", \"data\": \"$APPROVE_DATA\"},
  {\"to\": \"<SWAP_ROUTER>\", \"value\": \"0\", \"data\": \"$SWAP_DATA\"}
]" | keypo-wallet batch --key <key-name> --calls -

The deposit() call wraps ETH → WETH. The value field on the deposit call must equal amountIn (in wei). All three calls execute atomically.

Case C: Swapping to native ETH

Swap tokenIn → WETH, then unwrap. Set the swap recipient to the wallet's own address, then unwrap:

SWAP_DATA=$(cast calldata \
  "exactInputSingle((address,address,uint24,address,uint256,uint256,uint160))" \
  "(<tokenIn>,<WETH>,<fee>,<wallet-address>,<amountIn>,<amountOutMinimum>,0)")

WITHDRAW_DATA=$(cast calldata "withdraw(uint256)" <expectedWethOut>)

echo "[
  {\"to\": \"<tokenIn>\", \"value\": \"0\", \"data\": \"$APPROVE_DATA\"},
  {\"to\": \"<SWAP_ROUTER>\", \"value\": \"0\", \"data\": \"$SWAP_DATA\"},
  {\"to\": \"<WETH>\", \"value\": \"0\", \"data\": \"$WITHDRAW_DATA\"}
]" | keypo-wallet batch --key <key-name> --calls -

Step 7: Verify the Result

After the transaction succeeds, check the output token balance:

keypo-wallet balance --key <key-name> --token <tokenOut>

Or for native ETH:

keypo-wallet balance --key <key-name>