uniswap-tx-builder

This skill ships with the uniswap-tx-builder MCP — a public, keyless server that builds unsigned Uniswap v3 position transactions and (optionally) simulates them. It never holds keys and never signs. You build calldata here, then sign + broadcast with your own wallet (any signer — a CDP wallet MCP, viem, etc.).

Tools

All build tools return tx = { to, data, value, chainId }, rlp, and a description. value is "0" except build_wrap/build_swap with native ETH (payable). Addresses are 0x…40; positionId/amounts are decimal strings (they exceed JS safe integers).

rlp is the unsigned EIP-1559 (type-2) serialization of tx with nonce, fees and gas zeroed — pass it directly to signing services that populate those at signing time (e.g. a CDP wallet MCP send_transaction). If your signer manages nonces itself, serialize tx instead.

• `simulate` runs an eth_call dry-run. On by default for collect/close — keep it on so

you only ever sign txs that would succeed. Off by default for mint/increase (they need token approvals + balances); pass simulate: true only if those are already in place. For wrap/swap/approve, pass sender (the wallet that will sign) — simulation then runs by default with the correct from and value.

• A simulation failure comes back as an error — do not sign a tx that failed to simulate.
• A successful simulation also returns simulationResult — the actual decoded return value

of the call, not just simulated: true. Use it instead of guessing at expected amounts: build_collect → {amount0, amount1}; build_close → {decreaseLiquidity?: {amount0, amount1}, collect: {amount0, amount1}} (decreaseLiquidity only present when the position had liquidity); build_mint → {tokenId, liquidity, amount0, amount1} (the real tokenId the mint would get); build_increase → {liquidity, amount0, amount1}; build_approve → {approved}. build_wrap/build_swap go through the Universal Router's execute, which has no return value, so those two only ever report simulated (no simulationResult) — call get_swap_quote for the expected swap output rather than reading it off the simulation.

• recipient on wrap/swap defaults to the tx sender (the router's MSG_SENDER placeholder).

Omit it unless the output must go to a different address.

Permit2 payment (build_swap)

The default (non-wrapWei) swap path pays tokenIn via Permit2, which needs the Universal Router to have a sufficient allowance there. You never have to work this out by hand — pass sender and build_swap checks it for you:

• Sufficient standing allowance (from a prior build_approve to Permit2 + an on-chain

Permit2 approval, or an earlier signed permit that's still live) → you get a normal tx back, same as any other build tool.

• Insufficient → instead of a tx, you get back

{ permit2Required: true, typedData, permit, description }. Sign typedData with sender's wallet (e.g. a sign_typed_data call — it's a standard EIP-712 signature, no on-chain transaction involved), then call build_swap again with the exact same args plus permit2: <the returned "permit"> and permit2Signature: <the signature>. That call embeds a PERMIT2_PERMIT command ahead of the swap, so the allowance is set and consumed atomically in the swap's own tx — no separate on-chain Permit2 approval ever needed.

Do no math and don't construct the permit struct yourself — always echo back the permit object exactly as returned; it's tied to the signature and won't validate if altered. The permit is scoped to this one swap (a few minutes' validity), not a standing grant, so there's nothing to revoke afterward. Omit sender (or already have permit2) and this check is skipped entirely — useful if you already know the allowance is sufficient, or already have a permit in hand.

get_pool_state (live spot → range → mint amounts)

The one tool to call right before every mint:

1. rangePct: 2 → suggested.tickLower/tickUpper within ±2% of spot, rounded inward to the

tick spacing (the range never exceeds your stated width).

1. tickLower + tickUpper + balance0 + balance1 (raw wei balances) → `mintAmounts.

amount0Desired/amount1Desired computed from the **live** sqrtPrice ratio, plus limitingSide (which balance caps the position). Feed these straight into build_mint`. It errors if spot has moved outside the range — recompute the range, don't force the mint.

Amounts computed from a stale price revert the mint with "Price slippage check" — always recompute in the same breath as build_mint.

plan_position (human price range → ticks)

When you start from a human price range instead of a ±pct width: priceLower/priceUpper are token1 per token0 in whole-token units, reordered if given high→low, snapped to the fee tier's tick spacing. It reads decimals over RPC to convert amount0/amount1 to wei, but does not compute the range-optimal ratio — use get_pool_state with balances for that.

token0 must be `<` `token1` by address (Uniswap's ordering) for both planning tools. If they aren't, swap the pair and invert the prices — the tools error otherwise.

Signing (your wallet, not this MCP)

Take the returned rlp (for signing services that fill nonce/fees) or tx (for signers that serialize themselves) and sign + broadcast with your own signer. This MCP is keyless, so the only limits that apply are your wallet's (e.g. a CDP Wallet Policy). If your wallet rejects the tx, report it — never try to route around the wallet's policy.

For build_mint and build_increase, your wallet must hold the input tokens and have an ERC-20 approval to the NonfungiblePositionManager beforehand — build that approval with build_approve (spender = the chain's NFPM address) and sign it first. (This is also why build_mint/build_increase's simulate is off by default — the dry-run reverts without an approval in place already.) A Permit2-paid build_swap (no wrapWei, the default payment path for any tokenIn) needs Permit2 to have an allowance for the Universal Router — either a standing one, built the same way (build_approve with spender = Permit2, 0x000000000022D473030F116dDEE9F6B43aC78BA3 on every EVM chain, followed by an on-chain Permit2 approval — a wallet-policy carve-out many setups don't have), or the signed-permit flow in Permit2 payment above, which needs only a sign_typed_data capability scoped to the Permit2 contract and no separate on-chain approval tx at all — prefer this when the wallet's policy doesn't already allowlist calling Permit2 directly. build_wrap/build_swap use the Universal Router v1.2 (0x3fC91A3a…B2b7FAD) — the address wallet policies typically allowlist.

Position lifecycle

• Find positions: get_positions (by owner) → pick a positionId for collect/close/increase.
• Collect fees: build_collect → sign.
• Add liquidity: build_increase → sign (after build_approve-ing the NFPM, if not already).
• Close: build_close → sign. Use the returned position (pair, range, liquidity) to inform

the decision. Pass burn: true if you want the empty NFT gone too.

• Open around spot: get_pool_state (rangePct → ticks, balances → amounts) → build_approve

(NFPM, if not already) → build_mint → sign. If the wallet holds native ETH instead of WETH: get_swap_quote → build_swap with wrapWei (or build_wrap) first, confirm, then recompute amounts and mint.

• Swap tokens: get_swap_quote (amountOut → amountOutMin) → build_swap with sender (not

using wrapWei) → if it comes back permit2Required, sign typedData and call build_swap again with permit2/permit2Signature (see Permit2 payment) → sign the tx. Re-quote immediately before building — a stale quote's amountOutMin can revert the swap.

• Open with a price range: plan_position → get_pool_state (balances → amounts) →

build_approve (NFPM) → build_mint → sign.

• Rebalance = close → mint a recentered range. The mint amounts depend on the tokens

freed by the close, so do the close first, then get_pool_state + build_mint the new range once those balances are realized (typically a later step/cycle). Center the new range on the current price; widen it for volatile pairs, tighten it for stable pairs.

Chains

Supports the chains configured in the MCP (NFPM/factory/Universal Router/WETH9 per chain): Ethereum (1), Optimism (10), Polygon (137), Base (8453), Arbitrum (42161). On Polygon the "wrapped native" is WMATIC. Calling an unconfigured chain returns an "Unsupported chain" error.