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

# Get Swap Quotes

> Fetch optimized swap quotes across all Starknet liquidity sources

## Overview

The quotes endpoint returns the best available swap routes with unique quote IDs for execution. Each quote includes:

* Optimized routing across multiple DEXs
* Gas estimation and fees
* Slippage protection

## Request

<ParamField query="sellTokenAddress" type="string" required>
  Token address to sell (hex format)
</ParamField>

<ParamField query="buyTokenAddress" type="string" required>
  Token address to buy (hex format)
</ParamField>

<ParamField query="sellAmount" type="string">
  The amount of token user wants to sell.
  Either `sellAmount` or `buyAmount` required
</ParamField>

<ParamField query="buyAmount" type="string">
  The exact amount of token user wants to buy.
  Either `sellAmount` or `buyAmount` required
</ParamField>

<ParamField query="takerAddress" type="string">
  Address that will execute the swap
</ParamField>

<ParamField query="size" type="integer">
  Maximum number of quotes to return (range: 1-5)
</ParamField>

<ParamField query="integratorFees" type="string">
  Fee in basis points (e.g., "30" for 0.3%). When specified, `integratorFeeRecipient` and `integratorName` are required.
</ParamField>

<ParamField query="integratorFeeRecipient" type="string">
  Address to receive integrator fees. Required when `integratorFees` is specified.
</ParamField>

<ParamField query="integratorName" type="string">
  Your integration identifier for tracking
</ParamField>

<ParamField query="onlyDirect" type="boolean">
  If true, only return direct swap routes (no multi-hop)
</ParamField>

## Response

<ResponseField name="quoteId" type="string" required>
  Unique identifier for executing this quote (UUID)
</ResponseField>

<ResponseField name="sellTokenAddress" type="string" required>
  Token address being sold
</ResponseField>

<ResponseField name="sellAmount" type="string" required>
  Amount of token to sell (hex format)
</ResponseField>

<ResponseField name="sellAmountInUsd" type="number" required>
  USD value of sell amount
</ResponseField>

<ResponseField name="buyTokenAddress" type="string" required>
  Token address being purchased
</ResponseField>

<ResponseField name="buyAmount" type="string" required>
  Amount of token to receive (hex format). Already includes all fees.
</ResponseField>

<ResponseField name="buyAmountInUsd" type="number" required>
  USD value of buy amount
</ResponseField>

<ResponseField name="fee" type="object" required>
  Fee breakdown for the swap

  <Expandable title="Fee Object">
    <ResponseField name="feeToken" type="string" required>
      Token address used for fees
    </ResponseField>

    <ResponseField name="avnuFees" type="string" required>
      Platform fees (hex format)
    </ResponseField>

    <ResponseField name="avnuFeesInUsd" type="number" required>
      Platform fees in USD
    </ResponseField>

    <ResponseField name="avnuFeesBps" type="string" required>
      Platform fees in basis points
    </ResponseField>

    <ResponseField name="integratorFees" type="string" required>
      Integrator fees (hex format)
    </ResponseField>

    <ResponseField name="integratorFeesInUsd" type="number" required>
      Integrator fees in USD
    </ResponseField>

    <ResponseField name="integratorFeesBps" type="string" required>
      Integrator fees in basis points
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="chainId" type="string" required>
  Network identifier (e.g., "0x534e5f4d41494e")
</ResponseField>

<ResponseField name="blockNumber" type="string">
  Block at which quote was generated (hex format)
</ResponseField>

<ResponseField name="expiry" type="number">
  Unix timestamp when quote expires in seconds
</ResponseField>

<ResponseField name="routes" type="array" required>
  Swap routing paths with protocol details

  <Expandable title="Route Object">
    <ResponseField name="name" type="string" required>
      DEX protocol identifier (e.g., "JediSwap", "Ekubo")
    </ResponseField>

    <ResponseField name="address" type="string" required>
      Smart contract address
    </ResponseField>

    <ResponseField name="percent" type="number" required>
      Allocation percentage (1 = 100%)
    </ResponseField>

    <ResponseField name="sellTokenAddress" type="string" required>
      Input token for this route
    </ResponseField>

    <ResponseField name="buyTokenAddress" type="string" required>
      Output token for this route
    </ResponseField>

    <ResponseField name="routes" type="array">
      Nested routing steps (for multi-hop swaps)
    </ResponseField>

    <ResponseField name="alternativeSwapCount" type="integer" required>
      Number of alternative swaps available
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="gasFees" type="string" required>
  Estimated gas cost in STRK (hex format)
</ResponseField>

<ResponseField name="gasFeesInUsd" type="number">
  Gas fees converted to USD
</ResponseField>

<ResponseField name="priceImpact" type="number" required>
  Price impact in basis points (e.g., 20 = 0.2%). Negative value indicates loss. Divide by 100 to get percentage.
</ResponseField>

<ResponseField name="sellTokenPriceInUsd" type="number">
  Current market price of sell token in USD
</ResponseField>

<ResponseField name="buyTokenPriceInUsd" type="number">
  Current market price of buy token in USD
</ResponseField>

<ResponseField name="estimatedSlippage" type="number">
  Projected slippage percentage
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://starknet.api.avnu.fi/swap/v3/quotes?sellTokenAddress=0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7&buyTokenAddress=0x4718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d&sellAmount=0x2386f26fc10000"
  ```

  ```typescript TypeScript theme={null}
  const params = new URLSearchParams({
    sellTokenAddress: '0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7',
    buyTokenAddress: '0x4718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d',
    sellAmount: '0x2386f26fc10000'
  });

  const response = await fetch(`https://starknet.api.avnu.fi/swap/v3/quotes?${params}`);

  const quotes = await response.json();
  console.log('Quote:', quotes);
  ```

  ```python Python theme={null}
  import requests

  params = {
      'sellTokenAddress': '0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7',
      'buyTokenAddress': '0x4718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d',
      'sellAmount': '0x2386f26fc10000'
  }

  response = requests.get(
      'https://starknet.api.avnu.fi/swap/v3/quotes',
      params=params,
  )

  quotes = response.json()
  print('Quote:', quotes)
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  [
    {
      "quoteId": "69ee30c9-5051-479e-9366-bde0584a2614",
      "sellTokenAddress": "0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
      "sellAmount": "0x2386f26fc10000",
      "sellAmountInUsd": 28.2265,
      "buyTokenAddress": "0x4718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d",
      "buyAmount": "0xd005a71ea99678000",
      "buyAmountInUsd": 28.25618,
      "fee": {
        "feeToken": "0x4718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d",
        "avnuFees": "0xda475abf000",
        "avnuFeesInUsd": 0.000002,
        "avnuFeesBps": "0xf",
        "integratorFees": "0x0",
        "integratorFeesInUsd": 0.0,
        "integratorFeesBps": "0x0"
      },
      "chainId": "0x534e5f4d41494e",
      "blockNumber": "0x3ca1b4",
      "expiry": null,
      "routes": [
        {
          "name": "Nostra",
          "address": "0x49ff5b3a7d38e2b50198f408fa8281635b5bc81ee49ab87ac36c8324c214427",
          "percent": 0.55,
          "sellTokenAddress": "0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
          "buyTokenAddress": "0x4718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d",
          "routes": [],
          "alternativeSwapCount": 0
        },
        {
          "name": "Ekubo",
          "address": "0x5dd3d2f4429af886cd1a3b08289dbcea99a294197e9eb43b0e0325b4b",
          "percent": 0.45,
          "sellTokenAddress": "0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
          "buyTokenAddress": "0x4718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d",
          "routes": [],
          "alternativeSwapCount": 0
        }
      ],
      "gasFees": "0x19b1b3cb5956130",
      "gasFeesInUsd": 0.013633,
      "priceImpact": 10.51,
      "sellTokenPriceInUsd": 2825.618,
      "buyTokenPriceInUsd": 0.117692,
      "estimatedSlippage": 0.00032
    }
  ]
  ```
</ResponseExample>

## Best Practices

<AccordionGroup>
  <Accordion title="Quote Expiration">
    With Starknet's block time of \~2 seconds, quotes become stale after just 1 block. Refresh quotes every 2-3 blocks before execution.
  </Accordion>

  <Accordion title="Error Handling">
    Handle cases where no routes are available due to insufficient liquidity.
  </Accordion>
</AccordionGroup>