SwapDeposit

Convert a single-token holding into a balanced LP position in one shot. SwapDeposit is a mutating dispatch primitive that internally swaps an optimal fraction of the input, then deposits the resulting two-sided balance. V2/V3 only — see the architectural reason below.

When to use SwapDeposit vs (Swap + AddLiquidity)

The pair Swap then AddLiquidity gives you control over the swap fraction. SwapDeposit does it in one shot with the optimal fraction computed internally — closed-form for V2 (a quadratic accounting for the 0.3% fee), numeric optimization on [0.35, 0.65] for V3 (scipy.optimize.minimize, Nelder-Mead). Use the pair when you want a custom fraction; use SwapDeposit when you want zero dust and don’t care about the exact split.

When to use SwapDeposit vs OptimalDepositSplit

SwapDeposit executes the swap-and-deposit. OptimalDepositSplit is the non-mutating projection — it runs the same V2 closed-form solve and returns the optimal split as a typed dataclass without touching the pool. Pair them when you want a preview-then-execute flow: project with OptimalDepositSplit, decide whether to act, then call SwapDeposit. The two share the V2 solve at SwapDeposit._calc_univ2_deposit_portion.

Signature at a glance

Protocol	Required call shape
Uniswap V2	SwapDeposit().apply(lp, token_in, user_nm, amount_in)
Uniswap V3	SwapDeposit().apply(lp, token_in, user_nm, amount_in, lwr_tick, upr_tick)
Balancer	❌ Not supported — see “Why no Balancer/Stableswap section” below
Stableswap	❌ Not supported

Common parameters

Parameter	Type	Description
lp	Exchange	Initialized V2 or V3 pool with active liquidity.
token_in	ERC20	The single token the user holds and wants to deposit on both sides.
user_nm	str	Account name receiving the resulting LP credit.
amount_in	float	Total quantity of token_in available to spend (swap + deposit combined).

Protocol Variants

Uniswap V2

The dispatcher solves a closed-form quadratic for the optimal swap fraction alpha, accounting for V2’s 0.3% fee, then runs:

1. Swap alpha * amount_in of token_in for the other token.
2. lp.quote(...) the matching amount of token_in against the post-swap reserves.
3. lp.add_liquidity(user_nm, balance0, balance1, balance0, balance1) to mint LP shares.

Parameter	Type	Notes
(no extras)	—	Common parameters only.

from defipy import SwapDeposit

# Hold 1000 DAI; want a balanced ETH/DAI LP position
deposited = SwapDeposit().apply(lp, dai, "user", 1000)
# Returns the total `token_in`-denominated value deposited (swap leg + deposit leg)

The closed-form quadratic lives at SwapDeposit._calc_univ2_deposit_portion. It’s the same math the read-only OptimalDepositSplit primitive composes against — same alpha, no mutation.

Uniswap V3

V3 doesn’t admit a closed-form solution because the in-range liquidity-to-amount relationship varies with the sqrt-price across the range. The dispatcher uses scipy.optimize.minimize(method='Nelder-Mead', bounds=[(0.35, 0.65)]) to find the optimal swap fraction numerically, then:

1. Swap that fraction of token_in.
2. Compute the in-range liquidity L from the post-swap balance using UniV3Helper.calc_Lx / calc_Ly.
3. lp.mint(user_nm, lwr_tick, upr_tick, L) to mint the position.

Parameter	Type	Notes
lwr_tick	int	Lower tick of the position. Must be tick_spacing-aligned.
upr_tick	int	Upper tick.

from defipy import SwapDeposit, UniV3Utils

tick_spacing = 60
lwr_tick = UniV3Utils.getMinTick(tick_spacing)
upr_tick = UniV3Utils.getMaxTick(tick_spacing)

deposited = SwapDeposit().apply(lp, dai, "user", 1000, lwr_tick, upr_tick)

Numerical solve, not closed-form

The V3 solve is bounded to [0.35, 0.65] and stops at tol=1e-8. For tight ranges or extreme sqrt-prices, the optimum can sit at a boundary — there’s no warning emitted, but the dust will be larger than the V2 closed-form gives. Spot-check the residual if you’re scripting against thin ranges.

Why no Balancer/Stableswap section

SwapDeposit exists because V2/V3 deposits at the pool level need balanced two-sided amounts — providing a single token requires a manual swap step first. Balancer and Stableswap don’t have this constraint: AddLiquidity already accepts a single-token-in call shape and the pool math handles the imbalance against the invariant directly. There’s no swap-then-deposit pattern to abstract because the underlying primitive already does what you’d want.

The dispatcher reflects this — the defipy.process.deposit namespace re-exports only uniswappy.process.deposit.SwapDeposit, so calling SwapDeposit().apply(lp, ...) against a BalancerExchange or StableswapExchange will fail at the version check (no .version attribute on those exchanges). Use AddLiquidity for those protocols.

How SwapDeposit interacts with the rest of the pipeline

1. Join → AddLiquidity — pool initialized.
2. Pre-deposit projection — OptimalDepositSplit (V2 only) projects the same alpha SwapDeposit will use, plus the resulting balance, without mutating.
3. SwapDeposit — execute the zap-in (this primitive).
4. Post-deposit analytics — AnalyzePosition decomposes the resulting position over time.

See also

• Swap — the swap leg, used standalone
• AddLiquidity — the deposit leg, also handles Balancer/Stableswap single-asset adds
• WithdrawSwap — the inverse zap-out (V2/V3 only)
• OptimalDepositSplit — non-mutating V2 projection of the same solve
• Tutorials → Uniswap V2 — Swap & Deposit — runnable walkthrough
• The Primitive Contract — cross-cutting invariants