> ## 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.

# Overview

> Best-price swaps across all Starknet liquidity

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.

<Card title="Complete Tutorial" icon="book-open" href="/get-started/first-swap">
  Build a working swap implementation in 5 minutes →
</Card>

## 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

```typescript theme={null}
// 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.

<AccordionGroup>
  <Accordion title="The Complexity Problem" icon="brain">
    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.
  </Accordion>

  <Accordion title="Why Trust avnu?" icon="shield-check">
    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.
  </Accordion>

  <Accordion title="Smart Routing Example" icon="route">
    **Trade:** 10 ETH → USDC

    **Naive 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
  </Accordion>
</AccordionGroup>

## SDK Integration

<CodeGroup>
  ```typescript Complete Example theme={null}
  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);
  ```

  ```typescript Exclude Sources theme={null}
  const quotes = await getQuotes({
    sellTokenAddress: ethAddress,
    buyTokenAddress: usdcAddress,
    sellAmount: parseUnits('1', 18),
    takerAddress: account.address,
    excludeSources: ['10kSwap', 'SithSwap'],
  });
  ```
</CodeGroup>

## Understanding Quote Response

```typescript theme={null}
{
  "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

<Warning>
  **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.
</Warning>

## Advanced Features

<CardGroup cols={1}>
  <Card title="Integrator Fees" icon="coins" href="/docs/swap/add-fees">
    Earn revenue on every swap through your integration
  </Card>
</CardGroup>

## API Reference

<Card title="REST API Documentation" icon="code" href="/api/swap">
  Complete HTTP endpoint reference, authentication, and request/response formats
</Card>