Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.avnu.fi/llms.txt

Use this file to discover all available pages before exploring further.

avnu aggregates every liquidity source on Starknet (AMMs, CLOBs, and market makers) and uses competing solver algorithms to find the best execution path for your trade. Each solver tackles a complex optimization problem: splitting trades across hundreds of potential routes while balancing price impact, gas costs, slippage dynamics, and transaction success probability. We run multiple strategies in parallel, benchmark against direct market maker quotes, and select the solution that maximizes your net output.

Complete Tutorial

Build a working swap implementation in 5 minutes →

​
SDK Methods

​
Data Fetching

  • getQuotes(request) - Fetch optimized swap quotes

​
Simple Integration

  • executeSwap(params) - Complete swap with automatic approvals

​
Advanced Integration

  • quoteToCalls(quote, slippage, takerAddress) - Build swap calls for custom execution
// Simple integration
const quotes = await getQuotes({ ... });
const result = await executeSwap({
  provider: account,
  quote: quotes[0],
  slippage: 100 // 1%
});

// Advanced: compose with other operations
const { calls: swapCalls } = await quoteToCalls({
  quoteId: quote.quoteId,
  slippage,
  takerAddress: account.address,
});
const otherCalls = [...];
await account.execute([...swapCalls, ...otherCalls]);

​
How Solvers Work

Finding the optimal trade route on Starknet is a complex challenge. With tens of thousands of liquidity pools, varying gas costs, and fragmented liquidity across AMMs, CLOBs, and market makers, identifying the absolute best price is a non-trivial mathematical problem.
For every trade, the solver must navigate a vast search space:
  • Fragmented Liquidity: Liquidity is split across multiple protocols and pools.
  • Gas vs. Price: A better price might cost more in gas. The solver must calculate the net benefit.
  • Multi-Hop Routing: Direct swaps aren’t always best. Sometimes routing through 2 or 3 intermediate tokens yields a higher output.
  • Real-Time Constraints: Market conditions change in milliseconds.
This is an NP-hard optimization problem. There is no simple formula to solve it. It requires sophisticated infrastructure to explore millions of possibilities in real-time.
We have spent years building and refining our solver infrastructure to handle this complexity for you.
  • Comprehensive Aggregation: We integrate every significant liquidity source on Starknet.
  • Advanced Optimization: Our solvers run competing strategies in parallel to find the global maximum for your trade.
  • Battle-Tested: We power a significant portion of Starknet’s trading volume, ensuring reliability and execution quality.
  • Zero Maintenance: You get best-in-class execution without maintaining your own indexers or routing logic.
Trade: 10 ETH → USDCNaive approach (single pool):
  • Output: 32,450 USDC
  • Price impact: 0.8%
avnu Solver (optimized split):
  • Splits trade across multiple pools (e.g., 60% Pool A, 40% Pool B)
  • Uses multi-hop routes when beneficial
  • Output: 32,612 USDC
  • Price impact: 0.3%
Result: +$162 better execution

​
SDK Integration

import { RpcProvider, Account } from 'starknet';
import { getQuotes, executeSwap } from '@avnu/avnu-sdk';
import { parseUnits } from 'ethers';

const provider = new RpcProvider({
  nodeUrl: 'https://rpc.starknet.lava.build:443'
});

const account = new Account(
  provider,
  process.env.ACCOUNT_ADDRESS!,
  process.env.PRIVATE_KEY!
);

const ethAddress = "0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7";
const usdcAddress = "0x053c91253bc9682c04929ca02ed00b3e423f6710d2ee7e0d5ebb06f3ecf368a8";

// Fetch solver-optimized quotes
const quotes = await getQuotes({
  sellTokenAddress: ethAddress,
  buyTokenAddress: usdcAddress,
  sellAmount: parseUnits('1', 18),
  takerAddress: account.address,
});

console.log('Solver route:');
quotes[0].routes.forEach(route => {
  console.log(`  ${route.percent}% via ${route.name}`);
});

// Execute with optimized routing
const result = await executeSwap({
  provider: account,
  quote: quotes[0],
  slippage: 0.001
});

await provider.waitForTransaction(result.transactionHash);
console.log('✅ Swap complete:', result.transactionHash);

​
Understanding Quote Response

{
  "blockNumber": "0x0",
  "quoteId": "abc123",
  "sellTokenAddress": "0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
  "sellAmount": "1000000000000000000",
  "buyAmount": "3250450000",          // Optimized output
  "buyAmountInUsd": 3250.45,
  "sellAmountInUsd": "3251",
  "priceImpact": 20,             // 0.2% price impact
  "gasFees": "0x1234", 
  "gasFeesInUsd": 0.15,
  "fee": {
      "feeToken": "0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
      "avnuFees": "0x1234",
      "avnuFeesInUsd": 0.012,
      "avnuFeesBps": 15,
      "integratorFees": "0x0",
      "integratorFeesInUsd": 0,
      "integratorFeesBps": 0
  },
  "routes": [
    {
      "percent": 60,
      "name": "JediSwap",
      "sellAmount": "600000000000000000",
      "buyAmount": "1950270000"
    },
    {
      "percent": 40,
      "name": "Ekubo",
      "sellAmount": "400000000000000000",
      "buyAmount": "1300180000"
    }
  ]
}
Key metrics:
  • buyAmount: Maximum output after solver optimization
  • priceImpact: Price impact in basis points (20 = 0.2%), divide by 100 for percentage
  • gasFeesInUsd: Total gas cost including all hops
  • routes: How the solver split your trade
Quote Expiration: With Starknet’s block time of ~2 seconds, quotes become stale after just 1 block. The more blocks that pass, the higher the probability your quote is outdated. Refresh quotes every block before execution to ensure accuracy.

​
Advanced Features

Integrator Fees

Earn revenue on every swap through your integration

​
API Reference

REST API Documentation

Complete HTTP endpoint reference, authentication, and request/response formats