Skip to main content
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
Slippage tolerance is optional and maintains backward compatibility with existing integrations.

​
How It Works

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

Basis Points

  • 50 = 0.5%
  • 100 = 1%
  • 1000 = 10%

Price Protection

Transactions fail if price moves beyond tolerance rather than executing at unfavorable rates

Automatic Retry

Failed transactions can retry with higher tolerance for better success rates

​
Quick Example

Add slippage tolerance to any quote request:
Basic Usage
{
  "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:

Unified Quotes

Regular swaps and transfers between any assets

Contract Calls

Smart contract interactions with automatic token routing

Multi-Chain

Multi-account operations including Solana

Legacy Endpoints

V2 execute-quote and call-quote endpoints

​
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

  • Stablecoin Swaps
  • Major Token Swaps
  • Volatile Assets
// 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
};

​
Integration Patterns

​
Basic Implementation

Simply add the parameter to existing quote requests: 
// 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: 
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

Examples

Working code examples for different scenarios and asset types

Troubleshooting

Common issues and solutions for slippage tolerance implementation
Start with 100 basis points (1%) for most use cases. Adjust based on asset volatility and user preferences.
⌘I