> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onebalance.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Slippage Tolerance Overview

> Learn how slippage tolerance works in OneBalance to reduce quote refunds and improve transaction success rates.

Slippage tolerance helps reduce quote refunds by allowing price movement during cross-chain execution. Configure tolerance levels to balance transaction success rates with price protection.

## What is Slippage Tolerance?

Slippage tolerance defines the acceptable price movement between quote generation and execution. When prices move beyond your tolerance, the transaction will fail rather than execute at an unfavorable rate.

**Key Benefits:**

* **Fewer Refunds** - Transactions succeed despite minor price movements
* **Better UX** - Users can retry with adjusted parameters instead of failed quotes
* **Cost Efficiency** - Reduces wasted gas from failed transactions

<Warning>
  Slippage tolerance is **optional** and maintains backward compatibility with existing integrations.
</Warning>

## How It Works

OneBalance accepts slippage tolerance as a positive integer in basis points:

<CardGroup cols={3}>
  <Card title="Basis Points" icon="percent">
    * 50 = 0.5%
    * 100 = 1%
    * 1000 = 10%
  </Card>

  <Card title="Price Protection" icon="shield">
    Transactions fail if price moves beyond tolerance rather than executing at unfavorable rates
  </Card>

  <Card title="Automatic Retry" icon="refresh-cw">
    Failed transactions can retry with higher tolerance for better success rates
  </Card>
</CardGroup>

## Quick Example

Add slippage tolerance to any quote request:

```json Basic Usage theme={null}
{
  "from": {
    "account": {
      "sessionAddress": "0x...",
      "adminAddress": "0x...",
      "accountAddress": "0x..."
    },
    "asset": { "assetId": "ob:usdc" },
    "amount": "1000000"
  },
  "to": {
    "asset": { "assetId": "ob:eth" }
  },
  "slippageTolerance": 100
}
```

## Supported Endpoints

Slippage tolerance works with all quote endpoints:

<CardGroup cols={2}>
  <Card title="Unified Quotes" icon="arrow-up-down" href="/api-reference/quotes/get-quote">
    Regular swaps and transfers between any assets
  </Card>

  <Card title="Contract Calls" icon="code" href="/api-reference/quotes/prepare-call-quote">
    Smart contract interactions with automatic token routing
  </Card>

  <Card title="Multi-Chain" icon="globe" href="/api-reference/quotes/get-quote-v3">
    Multi-account operations including Solana
  </Card>

  <Card title="Legacy Endpoints" icon="archive">
    V2 execute-quote and call-quote endpoints
  </Card>
</CardGroup>

## When to Use Slippage Tolerance

### High-Volume Applications

Applications processing many transactions should implement slippage tolerance to reduce operational overhead from failed quotes.

### Volatile Market Conditions

During high volatility periods, slippage tolerance prevents unnecessary transaction failures from minor price movements.

### User-Facing Applications

Give users control over their risk tolerance by allowing them to configure slippage levels.

## Common Use Cases

<Tabs>
  <Tab title="Stablecoin Swaps">
    ```typescript theme={null}
    // Low slippage for stable assets
    const request = {
      from: { asset: { assetId: 'ob:usdc' }, amount: '1000000' },
      to: { asset: { assetId: 'ob:usdt' } },
      slippageTolerance: 10 // 0.1% for stablecoins
    };
    ```
  </Tab>

  <Tab title="Major Token Swaps">
    ```typescript theme={null}
    // Medium slippage for major tokens
    const request = {
      from: { asset: { assetId: 'ob:eth' }, amount: '1000000000000000000' },
      to: { asset: { assetId: 'ob:usdc' } },
      slippageTolerance: 100 // 1% for ETH
    };
    ```
  </Tab>

  <Tab title="Volatile Assets">
    ```typescript theme={null}
    // Higher slippage for volatile tokens
    const request = {
      from: { asset: { assetId: 'eip155:1/erc20:0x...' }, amount: '1000000' },
      to: { asset: { assetId: 'ob:eth' } },
      slippageTolerance: 300 // 3% for volatile tokens
    };
    ```
  </Tab>
</Tabs>

## Integration Patterns

### Basic Implementation

Simply add the parameter to existing quote requests:

```typescript theme={null}
// Add to existing quote request
const existingRequest = {
  // ... your existing quote parameters
};

const withSlippage = {
  ...existingRequest,
  slippageTolerance: 100 // 1%
};
```

### Dynamic Adjustment

Implement retry logic with increasing slippage:

```typescript theme={null}
async function executeWithRetry(baseRequest: QuoteRequest) {
  const slippageValues = [50, 100, 200]; // 0.5%, 1%, 2%
  
  for (const slippage of slippageValues) {
    try {
      const quote = await getQuote({
        ...baseRequest,
        slippageTolerance: slippage
      });
      
      return await executeQuote(quote);
    } catch (error) {
      if (error.code === 'QUOTE_REFUNDED' && slippage < 200) {
        continue; // Try next slippage level
      }
      throw error;
    }
  }
}
```

## Technical Details

### Validation

* Must be a positive integer greater than 0
* Recommended maximum: 1000 basis points (10%)
* No minimum enforced, but very low values may cause frequent failures

### Processing

* Converted internally when sending to routing providers
* Applied during execution, not quote generation
* Maintains quote structure for tamper-proof signatures

## Next Steps

<CardGroup cols={2}>
  <Card title="Examples" icon="file-code" href="/guides/slippage/examples">
    Working code examples for different scenarios and asset types
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/guides/slippage/troubleshooting">
    Common issues and solutions for slippage tolerance implementation
  </Card>
</CardGroup>

<Tip>
  Start with 100 basis points (1%) for most use cases. Adjust based on asset volatility and user preferences.
</Tip>