agent.liquidity opens, adds to and removes liquidity positions on Metric and Uniswap v4 through one call. Each change is one operation; each token approval it needs (an ERC-20 approval of the budget, through Permit2 for Uniswap v4) runs first as its own operation and the change continues after it. Circuit builds and bounds the calls; never send raw LP calldata.
agent.liquidity.positions.change({ network, action }) changes a position. action.kind is open (module, pool, range, budgets, slippagePercent), add (module, position, budgets, slippagePercent) or remove (module, position, percent; 100 closes it). module is metric or uniswap-v4. A Metric pool is { pool }, a green-tier pool from Metric’s metadata; a Uniswap v4 pool is the hookless, static-fee pool key from agent.data.pools. range is { lowerPercent, upperPercent }, offsets from the pool’s current price rounded outward to whole Metric bins or Uniswap ticks; a range touching the current price needs both pool tokens. budgets are [{ token, amount }] spend ceilings in whole tokens by pool token (the native coin is the zero address); a pool token left out is not spent. position is the position field of the session’s supplied holdings: <pool>/<salt> for Metric, the NFT id for Uniswap v4 (a paper Uniswap v4 position reads p<poolId>.<tickLower>.<tickUpper>). For an agent, percent is of what the session holds, so 100 removes exactly the session’s share and never another holder’s. A Uniswap v4 removal carries 1% slippage floors on both tokens; a Metric removal is priced by the pool’s oracle and has no onchain floor, and a partial removal that would leave a bin below the pool’s minimum shares is refused.
Paper sessions run the same call at live pool state: a paper open or add spends the sized amounts from the paper balance, and a remove returns the position’s share of the live pool. A paper position never touches the pool, so it neither moves the price nor dilutes other liquidity, and it can only go into Metric bins that already hold liquidity. Paper positions are one per pool (Metric) or per pool and range (Uniswap v4), so opening the same again adds to it. Paper Uniswap v4 positions value principal only and earn no trading fees; paper Metric positions earn the fees that compound into their bins. Backtests do not replay liquidity.