Cetus

Cetus’s Aggregator V3 SDK separates input caps from slippage limits

Last updated - 2026 Oct 13

Cetus’s Aggregator V3 SDK separates quote-based slippage limits from a maximum balance for the coin that an integration supplies as input. In fixed-input mode, slippage bounds acceptable output relative to the quote. The routerSwapWithMaxAmountIn method adds on-chain validation of the supplied coin’s balance. A route’s amountIn doesn’t itself impose that balance cap. These controls matter when an application builds a Sui programmable transaction block and keeps swap output available for another command. The choice between that capped builder, routerSwap, and the automatic fastRouterSwap helper turns on coin preparation and output handling.

The capped V3 builder checks the supplied coin’s balance, so a smaller quoted input doesn’t automatically shrink an oversized coin.

Does amountIn limit the coin supplied to routerSwap?

No, the route’s amountIn records the quoted input amount, while the caller-provided coin determines the balance that routerSwap receives. In fixed-input mode, this method consumes the supplied coin’s whole balance. Passing a larger coin therefore changes the input that enters execution. Setting a smaller amount in the route request isn’t a substitute for preparing an appropriately sized coin.

A coin object is distinct from the wallet’s total holding of that token. The application chooses which object to pass, including a coin created by an earlier command. Sui coin splitting can prepare a smaller input within the same programmable transaction block. That preparation doesn’t inherently require a separate transaction. The relevant balance belongs to the selected coin, even when the wallet holds other coins of the same type.

Slippage sets a minimum output for fixed-input swaps

A slippage value of 0.01 represents a 1% tolerance, expressed as a decimal fraction in the SDK. For a fixed-input swap, the builder uses the quote to calculate an acceptable minimum output. The threshold doesn’t increase with a larger supplied input coin, so it doesn’t guarantee the same percentage bound on the exchange rate. It doesn’t set an independent ceiling on the balance of an externally supplied input coin.

View image file

The starting quote can already reflect limited liquidity or the size of the requested trade. Concentrated liquidity affects that starting price where the route uses those pools. A narrow tolerance can accompany an unfavorable quote because slippage measures movement from that quote. Comparing the quote with a reference market price answers a different question about the starting rate.

The capped builder validates the input coin’s balance

The maxAmountIn parameter gives routerSwapWithMaxAmountIn an explicit ceiling for its caller-provided input coin. This makes the capped method relevant when an application receives a coin from another operation.

The transaction aborts on-chain when the provided input coin’s balance exceeds maxAmountIn . The validation checks the coin’s balance before the swap proceeds. It doesn’t automatically trim an oversized object to match the quote. An application that needs a smaller input must prepare that smaller coin.

This ceiling applies to the selected input object. It doesn’t establish a spending budget across the wallet, or cap other commands and transaction gas.

The SDK accepts maxAmountIn as a BN integer amount. Its units must match the balance of the input coin. A displayed token amount needs conversion using that token’s decimals before it becomes the cap. Treating a display value as an integer coin balance can change the limit by orders of magnitude. A token-amount ceiling also carries no fixed dollar value as the asset’s market price changes.

Quote direction changes where the tolerance is applied

With byAmountIn: true , the route request fixes the input amount and quotes an output amount. With byAmountIn: false , it fixes the desired output and quotes the required input. Slippage therefore affects different sides of those calculations. In the first mode, the allowance reduces acceptable output. In the second, it increases the calculated input allowance. The SDK also accounts for any configured overlay fee when calculating those amount limits.

For a fixed-output quote, fastRouterSwap prepares the input coin using the slippage-adjusted allowance. For caller-supplied fixed-output swaps in SDK 1.6.1, the coin’s balance sets the available input. The builder doesn’t independently enforce the calculated slippage allowance. The capped variant validates that balance against maxAmountIn . That validation measures the coin entering the swap, rather than calculating only the amount eventually spent. Fixed-output execution can leave unused input, so the fixed-input whole-balance rule doesn’t describe that mode.

View image file

Can a swap’s output stay inside the same programmable transaction block?

Yes, routerSwap and routerSwapWithMaxAmountIn return a target coin argument that another command can use inside the same programmable transaction block, or PTB. Sui executes the commands in order and lets later commands use earlier results. The application’s remaining commands must use or transfer the returned coin appropriately.

During construction, that returned argument identifies an intended transaction result. The builder call hasn’t established that a swap has completed on-chain.

View image file

A failing command prevents the PTB’s command effects from committing. This also couples the swap to later commands: a swap that satisfies its own limits won’t commit if another command fails. Composition avoids a separate transaction simply to pass the output onward.

V3 package data connects the route to the swap build

The V3 caller-supplied builders require the route’s packages map to contain the Aggregator V3 package entry. That information identifies the contract package used to construct the swap. Retaining only amountIn and amountOut loses part of the required route data. A reduced object can look adequate for displaying a quote and still fail the builder’s package check.

Package validation can reject a build before submission; an input-cap violation rejects execution on-chain. Increasing slippage won’t supply a missing package entry. The route response also reports insufficientLiquidity and any routing error, which describe whether routing produced usable trade data. Preserve the response’s quote mode, amounts, and execution data together. These fields describe the requested route; they don’t establish that a transaction has succeeded.

What readers ask about Cetus