# How Slippage Calculation Works in Osmosis Swap Transactions

> Understand how slippage calculation works in Osmosis swaps. Learn about percentage tolerance, input/output adjustments, and rounding for exact token units.

- Repository: [Jon Ator/osmosis-agent-toolkit](https://github.com/jonator/osmosis-agent-toolkit)
- Tags: deep-dive
- Published: 2026-03-05

---

**Slippage calculation in Osmosis swap transactions applies a user-specified percentage tolerance to adjust the maximum input amount (for exact-out swaps) or minimum output amount (for exact-in swaps), using ceiling and floor rounding to maintain integer token units.**

The `osmosis-agent-toolkit` provides a TypeScript interface for executing swaps on the Osmosis decentralized exchange. Understanding how slippage calculation works is essential for protecting trades against price movements between quote retrieval and transaction broadcast. The toolkit implements distinct formulas for exact-in and exact-out swap directions, with a default tolerance of 0.5% when users do not specify otherwise.

## Understanding Slippage in Decentralized Exchanges

Slippage represents the difference between the expected price of a trade and the actual price when the transaction executes. In automated market maker (AMM) environments like Osmosis, prices shift as liquidity pools rebalance. When a user requests a swap quote from the Osmosis Sidecar Query Server (SQS), the response reflects the pool state at that exact moment. By the time the transaction reaches the chain, market conditions may have changed, potentially resulting in unfavorable execution prices without proper slippage protection.

## How Slippage Calculation Works in the Osmosis Agent Toolkit

The toolkit processes slippage differently depending on whether the user specifies the input amount (exact-in) or the desired output amount (exact-out). Both calculations occur in [`packages/core/src/tx/swap.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/tx/swap.ts) before constructing the final transaction message.

### Quote-Derived Amounts

Before applying slippage calculations, the toolkit retrieves raw amounts from the Osmosis SQS:

- **Exact-in quotes** (`SidecarOutGivenInQuoteResponse`) provide `amount_out` — the expected tokens received
- **Exact-out quotes** (`SidecarInGivenOutQuoteResponse`) provide `amount_in` — the expected tokens required

These values represent the zero-slippage scenario and serve as the baseline for tolerance calculations.

### Exact-Out Swaps: Calculating Maximum Input

When executing an exact-out swap (where the user knows how much they want to receive), slippage calculation determines the **maximum** amount of input tokens the user is willing to spend. This protects against the input token becoming more expensive relative to the output.

According to [`packages/core/src/tx/swap.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/tx/swap.ts) lines 17-19, the formula is:

```typescript
tokenInMaxAmount = Math.ceil(amount_in * (1 + slippagePercent / 100))

```

The `Math.ceil` operation ensures the value rounds up to the nearest whole token unit, preventing transaction failures due to fractional amounts while ensuring the user never spends more than the calculated maximum.

### Exact-In Swaps: Calculating Minimum Output

For exact-in swaps (where the user specifies how much to spend), slippage calculation establishes the **minimum** amount of output tokens the user will accept. This guards against the output token losing value before execution.

As implemented in [`packages/core/src/tx/swap.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/tx/swap.ts) lines 52-54:

```typescript
tokenOutMinAmount = Math.floor(amount_out * (1 - slippagePercent / 100))

```

The `Math.floor` operation rounds down to ensure the user receives at least the calculated minimum, accounting for the conservative nature of slippage protection.

## Default Slippage Tolerance Settings

The toolkit provides sensible defaults when users omit slippage parameters. Both swap directions default to **0.5%** tolerance:

- **Exact-out transactions**: `SendSwapInGivenOutQuoteTxTool` in [`packages/core/src/tools/swap.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/tools/swap.ts) (lines 38-42) uses `params.slippageTolerancePercent ?? 0.5`
- **Exact-in transactions**: `SendSwapOutGivenInQuoteTxTool` in [`packages/core/src/tools/swap.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/tools/swap.ts) (lines 91-95) applies the same default

These defaults strike a balance between protection against normal market volatility and transaction success rates.

## Implementation Details and Code Examples

### Exact-Out Swap with Custom Slippage

When executing a swap where you specify the desired output amount, apply custom slippage tolerance as follows:

```typescript
import { SwapQuoteInGivenOutTool, SendSwapInGivenOutQuoteTxTool } from '@osmosis-agent-toolkit/core';

// 1. Retrieve quote for exact-out swap
const quoteTool = new SwapQuoteInGivenOutTool(sqsClient, memory);
const quote = await quoteTool.call({
  tickerIn: 'OSMO',
  amountOut: '100',   // Want to receive 100 OSMO
  tickerOut: 'ATOM',
});

// 2. Execute with 1% slippage tolerance
const sendTool = new SendSwapInGivenOutQuoteTxTool(account, memory);
const { txHash } = await sendTool.call({
  quoteId: quote.id,
  slippageTolerancePercent: 1,  // 1% maximum slippage
});

console.log('Transaction hash:', txHash);

```

The `SendSwapInGivenOutQuoteTxTool` internally calls `makeSwapExactAmountOutEncodeObject`, which calculates `tokenInMaxAmount` using `Math.ceil(quote.amount_in * 1.01)`.

### Exact-In Swap with Default Slippage

For standard swaps where you specify the input amount, omit the slippage parameter to use the 0.5% default:

```typescript
import { SwapQuoteOutGivenInTool, SendSwapOutGivenInQuoteTxTool } from '@osmosis-agent-toolkit/core';

// Get quote for spending 50 ATOM
const quoteTool = new SwapQuoteOutGivenInTool(sqsClient, memory);
const quote = await quoteTool.call({
  tickerIn: 'ATOM',
  amountIn: '50',
  tickerOut: 'OSMO',
});

// Execute with default 0.5% slippage
const sendTool = new SendSwapOutGivenInQuoteTxTool(account, memory);
const { txHash } = await sendTool.call({
  quoteId: quote.id,
  // slippageTolerancePercent omitted - defaults to 0.5
});

console.log('Swap executed:', txHash);

```

Here, `makeSwapExactAmountInEncodeObject` applies `Math.floor(quote.amount_out * 0.995)` to determine the minimum acceptable output.

## Key Source Files and Functions

Understanding the complete slippage calculation workflow requires familiarity with these specific files in the `jonator/osmosis-agent-toolkit` repository:

| File | Purpose | Key Sections |
|------|---------|--------------|
| [`packages/core/src/tx/swap.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/tx/swap.ts) | Core transaction encoder that applies slippage formulas to raw quotes. | Token-in maximum calculation (`L17-L19`), token-out minimum calculation (`L52-L54`), `makeSwapExactAmountOutEncodeObject`, `makeSwapExactAmountInEncodeObject`. |
| [`packages/core/src/tools/swap.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/tools/swap.ts) | High-level tool implementations that handle default slippage values and transaction broadcasting. | Default 0.5% tolerance in `SendSwapInGivenOutQuoteTxTool` (`L38-L42`) and `SendSwapOutGivenInQuoteTxTool` (`L91-L95`). |
| [`packages/core/src/queries/sqs/router.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/queries/sqs/router.ts) | Type definitions for SQS quote responses. | `SidecarOutGivenInQuoteResponse` (exact-in quotes), `SidecarInGivenOutQuoteResponse` (exact-out quotes). |
| [`packages/core/src/utils/number.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/utils/number.ts) | Precision utilities for converting human-readable amounts to smallest-unit integers. | `mulPrecision` helper used before slippage calculations. |

These files work sequentially: the query layer retrieves raw amounts, the tool layer applies default tolerances, and the transaction layer encodes the final slippage-protected messages for broadcast.

## Summary

- **Slippage calculation** in the Osmosis Agent Toolkit protects users from price movements between quote retrieval and transaction execution by adjusting acceptable input or output bounds.
- **Exact-out swaps** calculate a **maximum input amount** using `Math.ceil(amount_in * (1 + slippage/100))` to prevent over-spending.
- **Exact-in swaps** calculate a **minimum output amount** using `Math.floor(amount_out * (1 - slippage/100))` to guarantee minimum receipts.
- **Default tolerance** is **0.5%** when not specified, applied in `SendSwapInGivenOutQuoteTxTool` and `SendSwapOutGivenInQuoteTxTool`.
- Core implementation resides in [`packages/core/src/tx/swap.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/tx/swap.ts), with formulas at lines 17-19 and 52-54.

## Frequently Asked Questions

### What is the default slippage tolerance in osmosis-agent-toolkit?

The default slippage tolerance is **0.5%** (0.5 percent). This value is automatically applied when executing swaps through `SendSwapInGivenOutQuoteTxTool` or `SendSwapOutGivenInQuoteTxTool` if the caller does not explicitly provide a `slippageTolerancePercent` parameter.

### How does slippage calculation differ between exact-in and exact-out swaps?

For **exact-out swaps** (where you specify the desired output amount), slippage increases the calculated input amount using `Math.ceil(amount_in * (1 + slippage/100))` to set a maximum spend limit. For **exact-in swaps** (where you specify the input amount), slippage decreases the expected output using `Math.floor(amount_out * (1 - slippage/100))` to establish a minimum receipt guarantee.

### Why does the toolkit use Math.ceil and Math.floor for slippage calculations?

The toolkit uses **Math.ceil** for exact-out swaps to round the maximum input amount upward to the nearest whole token unit, ensuring the transaction will not fail due to insufficient input if the price moves against the user. Conversely, **Math.floor** is used for exact-in swaps to round the minimum output amount downward, guaranteeing the user receives at least the calculated minimum even if the pool price shifts unfavorably. Both operations ensure amounts remain integers in the token's smallest unit (e.g., `uatom`).

### Where is the slippage calculation implemented in the source code?

The core slippage formulas are implemented in [`packages/core/src/tx/swap.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/tx/swap.ts) at lines 17-19 (for exact-out swaps calculating `tokenInMaxAmount`) and lines 52-54 (for exact-in swaps calculating `tokenOutMinAmount`). The default 0.5% tolerance values are defined in [`packages/core/src/tools/swap.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/tools/swap.ts) at lines 38-42 and 91-95 within the `SendSwapInGivenOutQuoteTxTool` and `SendSwapOutGivenInQuoteTxTool` classes respectively.