Gamma

Gamma limit orders use pool tick spacing to set price boundaries

Gamma limit orders use pool tick spacing to translate target prices into narrow liquidity ranges. An entered price may round to a permitted tick, and the order must sit on the correct side of the pool’s current price. Conversion occurs as swaps move through that range, so its boundaries, the chosen token, and the execution state all affect what the order means.

Price precision starts with the selected pool and quote direction. A single-price order concentrates conversion in one permitted interval. Scale orders spread it across several intervals, adding constraints on order count and token allocation.

Pool liquidity and the swap hook work together

The order manager supplies one token as liquidity in a narrow pool range, while the swap hook handles execution after qualifying price movement. Swappers trade against that liquidity as the pool price enters the interval. The position gradually exchanges its starting token for the other currency. Once the price passes the relevant outer boundary, the hook can remove the converted position. Price movements in other pools don’t trigger this position’s execution hook.

A liquidity provider (LP) vault manages capital across its strategy’s positions over time. A limit order uses a defined range for a particular token conversion. Both involve concentrated liquidity, but their practical settings differ: the order’s boundaries express where conversion should occur. Its existence doesn’t imply that market activity will reach those boundaries.

Single-price and scale orders allocate tokens differently

A single-price order assigns tokens to one narrow interval, whereas a scale order distributes a total allocation across several intervals within selected bounds.

One target interval

The single-order call takes a target tick and the token amount. The manager derives the lower and upper boundaries from that tick, the pool’s spacing, and the input currency. Even this concentrated order occupies an interval. The target identifies a boundary of that interval; it doesn’t turn the whole position into liquidity at a mathematical point.

Several target intervals

Scale orders add a requested count and a size distribution. Changing the distribution changes how much capital each interval receives. Changing the count changes how many individual intervals the manager creates. More intervals require enough room between the bounds, and each constituent order remains subject to the applicable funding constraints.

Tick spacing sets the usable boundary grid

The pool’s spacing limits which ticks can serve as liquidity boundaries; its spot price can still move between those boundaries as swaps consume available liquidity. A tick is an index on a multiplicative price scale. At tick t, Uniswap v4’s raw token1-to-token0 price ratio follows 1.0001 ^t . The raw ratio uses the currencies’ smallest units. Token decimals determine how that ratio translates into the price shown per whole token.

Let s denote the pool’s tick spacing. Usable position boundaries lie at integer multiples of s. Moving between adjacent usable boundaries multiplies the raw price by 1.0001 ^s . Larger spacing therefore means coarser choices in proportional price terms. It doesn’t establish a fixed gap measured in a fiat currency, and it doesn’t describe every price at which swaps can trade inside the interval.

Token ordering and decimals give a tick its meaning

The same tick index needs the pool’s currency order and token decimals before it can express a meaningful target price in the units that a reader expects.

The quote direction

Uniswap v4 orders its pool currencies by address and expresses the raw ratio in token1 units per token0 unit, so interpreting a buy or sell label requires both the supplied token and the quote direction. A display that uses the opposite quote shows the reciprocal price, so increasing tick indices correspond to decreasing prices in that inverted view.

The token units

Each currency’s decimal scale converts raw units into whole tokens. For the token1-per-token0 quote, multiply the raw ratio by 10 ^d0-d1 , where d0 and d1 are the respective decimal counts. Ignoring that adjustment can produce a price with the wrong magnitude. Extra decimal places in a display don’t create extra usable ticks or change the pool’s permitted boundaries.

Why can’t I place an order at my exact target price?

The target may fall between spacing multiples, or its rounded interval may lie too close to the current pool price for the selected input token. Gamma’s tick logic rounds token0 targets downward and token1 targets upward to the permitted grid. It also rounds the current tick for the selected direction. A target that passes an initial above-or-below comparison can therefore fail the subsequent spacing check. The accepted lower and upper ticks describe the position that the manager will create.

View image file

Token0 orders require a target above the current tick. Token1 orders require one below it. Those conditions place the starting currency outside the active conversion range. Price movement before transaction execution can change whether a request satisfies the conditions, even when its earlier preview was valid. Repeating the same request without refreshing the pool state doesn’t resolve that dependency.

Range width limits the number of scale orders

The width remaining after boundary rounding limits how many separate scale orders can fit inside the chosen range. A narrower interval can invalidate a requested count.

Space for separate positions

Gamma’s scale-order tick validation requires at least two constituent orders. Once the endpoints align to spacing s, the number of available spacing intervals equals the upper tick minus the lower tick, divided by s. The requested count can’t exceed that capacity. Rounding the endpoints inward may reduce the available room or collapse the range entirely.

The manager’s count setting

The manager also applies its configurable maxOrderLimit to a scale-order request. A range with enough tick intervals can still exceed that setting. Gamma’s Python software development kit (SDK) exposes a count-range query for selected price bounds; the creation transaction still evaluates its actual parameters and pool state.

Pool eligibility and funding constrain order acceptance

The Uniswap v4 order manager requires an enabled pool, the matching hook, and a funded input amount before it can accept a price-aligned order. Its creation path also requires an unpaused manager. Adding an order to a position awaiting keeper execution reverts. A nonzero amount must satisfy the configured minimum for the supplied currency. ERC-20 inputs need sufficient allowance for the manager’s token transfer. Scale-order allocation matters here because dividing a total amount changes individual order sizes. Increasing the deposit can address an amount constraint, while the pool’s spacing continues to govern price boundaries. The manager’s currency minimums and order-count limit can change through configuration.

Pool swaps determine the execution opportunity

A qualifying swap in the selected pool gives the hook its execution opportunity, even if another market has already traded through a visually similar target price. The hook records the tick before the swap and reads it again afterward. It passes that movement and its direction to the order manager. Token0 conversion completes toward the upper boundary; token1 conversion completes toward the lower boundary. Merely entering the position’s range can leave both currencies in the liquidity position. Removing a fully converted position ends its exposure to later swaps through that range. Some eligible positions can require keeper follow-up when the swap crosses more eligible positions than the configured execution limit permits.

Keeper follow-up depends on the later pool price

The configurable execution limit bounds how many eligible positions the manager processes during a swap. It marks excess positions for an authorized keeper, so a boundary crossing can precede removal.

Keeper execution rechecks the current tick. Token0 positions need a tick at or above their upper boundary; token1 positions need one below their lower boundary, and either position must still retain liquidity and carry the waiting flag. If those conditions no longer hold, the keeper call clears that flag instead of forcing execution at an unsuitable state.

A position that remains in the pool can exchange back toward its starting currency if swaps reverse through its range. Clearing the waiting flag doesn’t itself cancel the liquidity or transfer tokens to its owner. The later pool state therefore affects delayed execution, and a past crossing alone doesn’t preserve a completed conversion while the position remains open.

Range prices and claim amounts describe different results

A target boundary identifies one edge of the conversion interval, while the withdrawn principal reflects the tokens that the position actually converts across that interval. The amount also follows the liquidity calculation and integer rounding.

The claim calculation deducts the hook fee from accrued liquidity fees. Principal and earned fees occupy separate accounting fields. Fees can involve both pool currencies, so their token units remain relevant to the final transfer.

Network gas adds another cost to submitted transactions. A narrow range can improve control over where conversion occurs, without fixing the net economic value after those transaction costs.

The claim callback includes a fallback that redirects an unsuccessful user payout to the treasury. A successful claim transaction therefore doesn’t always establish receipt by the intended wallet. Its FailedTransferSentToTreasury event identifies that fallback path.