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

> Fetch optimized swap quotes using the SDK

## Overview

Get the best quotes from on-chain and off-chain liquidity sources. The SDK automatically converts amounts to the correct format and handles response parsing.

## SDK Method

```typescript theme={null}
getQuotes(
  request: QuoteRequest,
  options?: AvnuOptions
): Promise<Quote[]>
```

## Parameters

<ParamField path="request" type="QuoteRequest" required>
  Quote request parameters

  <Expandable title="QuoteRequest properties">
    <ParamField path="sellTokenAddress" type="string" required>
      Token address to sell (hex format)
    </ParamField>

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

    <ParamField path="sellAmount" type="bigint">
      Amount to sell in smallest unit. Either `sellAmount` or `buyAmount` required.
    </ParamField>

    <ParamField path="buyAmount" type="bigint">
      Amount to buy in smallest unit. Either `sellAmount` or `buyAmount` required.
    </ParamField>

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

    <ParamField path="size" type="number" default={1}>
      Number of quotes to return (1-5)
    </ParamField>

    <ParamField path="excludeSources" type="string[]">
      Array of source names to exclude from routing
    </ParamField>

    <ParamField path="integratorFees" type="bigint">
      Fee in basis points (e.g., 30n for 0.3%)
    </ParamField>

    <ParamField path="integratorFeeRecipient" type="string">
      Address to receive integrator fees (required when integratorFees is set)
    </ParamField>

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

<ParamField path="options" type="AvnuOptions">
  Optional SDK configuration

  <Expandable title="AvnuOptions properties">
    <ParamField path="baseUrl" type="string">
      Custom API base URL (default: `https://starknet.api.avnu.fi`)
    </ParamField>

    <ParamField path="impulseBaseUrl" type="string">
      Custom Impulse API base URL for market data (default: `https://starknet.impulse.avnu.fi`)
    </ParamField>

    <ParamField path="abortSignal" type="AbortSignal">
      AbortSignal to cancel the request
    </ParamField>

    <ParamField path="avnuPublicKey" type="string">
      Public key for response verification
    </ParamField>
  </Expandable>
</ParamField>

## Returns

Returns `Promise<Quote[]>` - Array of quotes sorted by best output first.

### Quote Interface

```typescript theme={null}
interface Quote {
  quoteId: string;
  sellTokenAddress: string;
  sellAmount: bigint;
  sellAmountInUsd: number;
  buyTokenAddress: string;
  buyAmount: bigint;
  buyAmountInUsd: number;
  fee: Fee;
  blockNumber?: number;
  chainId: string;
  expiry?: number | null;
  routes: Route[];
  gasFees: bigint;           // In FRI
  gasFeesInUsd?: number;
  priceImpact: number;       // Basis points (20 = 0.2%), divide by 100 for %
  sellTokenPriceInUsd?: number;
  buyTokenPriceInUsd?: number;
  exactTokenTo?: boolean;
  estimatedSlippage?: number;
}
```

### Fee Interface

```typescript theme={null}
interface Fee {
  feeToken: string;
  avnuFees: bigint;
  avnuFeesInUsd: number;
  avnuFeesBps: bigint;
  integratorFees: bigint;
  integratorFeesInUsd: number;
  integratorFeesBps: bigint;
}
```

### Route Interface

```typescript theme={null}
interface Route {
  name: string;
  address: string;
  percent: number;
  sellTokenAddress: string;
  buyTokenAddress: string;
  routeInfo?: Record<string, string>;
  routes: Route[];              // Nested routes for multi-hop swaps
  alternativeSwapCount: number;
}
```

## Example

<CodeGroup>
  ```typescript Basic Usage theme={null}
  import { getQuotes } from '@avnu/avnu-sdk';
  import { parseUnits } from 'ethers';

  const ETH = "0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7";
  const USDC = "0x053c91253bc9682c04929ca02ed00b3e423f6710d2ee7e0d5ebb06f3ecf368a8";

  const quotes = await getQuotes({
    sellTokenAddress: ETH,
    buyTokenAddress: USDC,
    sellAmount: parseUnits('1', 18),
    takerAddress: account.address,
  });

  console.log('Best quote:', quotes[0].buyAmount);
  console.log('Routes:', quotes[0].routes);
  ```

  ```typescript Multiple Quotes theme={null}
  // Get top 3 quotes to compare
  const quotes = await getQuotes({
    sellTokenAddress: ETH,
    buyTokenAddress: USDC,
    sellAmount: parseUnits('10', 18),
    takerAddress: account.address,
    size: 3,
  });

  quotes.forEach((quote, i) => {
    console.log(`Quote ${i + 1}:`, quote.buyAmount);
  });
  ```

  ```typescript With Integrator Fees theme={null}
  const quotes = await getQuotes({
    sellTokenAddress: ETH,
    buyTokenAddress: USDC,
    sellAmount: parseUnits('1', 18),
    takerAddress: account.address,
    integratorFees: 30n, // 0.3% fee
    integratorFeeRecipient: '0x...',
    integratorName: 'MyDeFiApp',
  });
  ```

  ```typescript Buy Exact Amount theme={null}
  // Specify how much you want to buy instead of sell
  const quotes = await getQuotes({
    sellTokenAddress: ETH,
    buyTokenAddress: USDC,
    buyAmount: parseUnits('1000', 6), // Buy exactly 1000 USDC
    takerAddress: account.address,
  });

  console.log('You need to sell:', quotes[0].sellAmount, 'ETH');
  ```
</CodeGroup>

## Quote Response

```typescript theme={null}
{
  quoteId: "abc123def456",
  sellTokenAddress: "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
  sellAmount: 1000000000000000000n,
  sellAmountInUsd: 3245.12,
  buyTokenAddress: "0x053c91253bc9682c04929ca02ed00b3e423f6710d2ee7e0d5ebb06f3ecf368a8",
  buyAmount: 3250450000n,
  buyAmountInUsd: 3250.45,
  fee: {
    feeToken: "0x053c91253bc9682c04929ca02ed00b3e423f6710d2ee7e0d5ebb06f3ecf368a8",
    avnuFees: 0n,
    avnuFeesInUsd: 0,
    avnuFeesBps: 0n,
    integratorFees: 0n,
    integratorFeesInUsd: 0,
    integratorFeesBps: 0n
  },
  chainId: "0x534e5f4d41494e",
  priceImpact: 0.0016,
  gasFees: 15000n,
  gasFeesInUsd: 0.05,
  routes: [
    {
      name: "JediSwap",
      address: "0x...",
      percent: 60,
      sellTokenAddress: "0x049d...",
      buyTokenAddress: "0x053c...",
      routes: [],
      alternativeSwapCount: 0
    },
    {
      name: "Ekubo",
      address: "0x...",
      percent: 40,
      sellTokenAddress: "0x049d...",
      buyTokenAddress: "0x053c...",
      routes: [],
      alternativeSwapCount: 0
    }
  ]
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use the avnu Token List" icon="list">
    For the most reliable trading experience, always use the avnu Token List to filter for verified tokens. This avoids scams and ensures compatibility.

    **SDK Method:**

    ```typescript theme={null}
    import { fetchTokens } from '@avnu/avnu-sdk';

    // Fetch verified tokens
    const tokens = await fetchTokens({
      tags: ['Verified'],
      page: 0,
      size: 100
    });
    ```
  </Accordion>

  <Accordion title="Always use fresh quotes" icon="clock">
    With Starknet's block time of \~2 seconds, the likelihood of a quote becoming stale increases exponentially with each passing block. For the highest success rate, refresh quotes every block before execution.
  </Accordion>

  <Accordion title="Use bigint for amounts" icon="hashtag">
    The SDK uses native `bigint` for all token amounts. Use `parseUnits()` from ethers to convert decimal amounts:

    ```typescript theme={null}
    import { parseUnits } from 'ethers';

    // Convert 1.5 ETH (18 decimals) to bigint
    const amount = parseUnits('1.5', 18);
    ```
  </Accordion>

  <Accordion title="Handle no routes case" icon="route">
    ```typescript theme={null}
    const quotes = await getQuotes({...});

    if (quotes.length === 0) {
      console.error('No routes found for this token pair');
      return;
    }
    ```
  </Accordion>

  <Accordion title="Set integrator name" icon="tag">
    Always include your app name for better support:

    ```typescript theme={null}
    const quotes = await getQuotes({
      // ... other params
      integratorName: 'MyDeFiApp'
    });
    ```
  </Accordion>
</AccordionGroup>

## Related

<Card title="Execute Swap" icon="play" href="/docs/swap/execute-swap">
  Execute the swap using a quote
</Card>