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.

​
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

getQuotes(
  request: QuoteRequest,
  options?: AvnuOptions
): Promise<Quote[]>

​
Parameters

​
request
QuoteRequest
required
Quote request parameters
​
options
AvnuOptions
Optional SDK configuration

​
Returns

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

​
Quote Interface

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

interface Fee {
  feeToken: string;
  avnuFees: bigint;
  avnuFeesInUsd: number;
  avnuFeesBps: bigint;
  integratorFees: bigint;
  integratorFeesInUsd: number;
  integratorFeesBps: bigint;
}

​
Route Interface

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

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);

​
Quote Response

{
  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

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:
import { fetchTokens } from '@avnu/avnu-sdk';

// Fetch verified tokens
const tokens = await fetchTokens({
  tags: ['Verified'],
  page: 0,
  size: 100
});
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.
The SDK uses native bigint for all token amounts. Use parseUnits() from ethers to convert decimal amounts:
import { parseUnits } from 'ethers';

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

const quotes = await getQuotes({...});

if (quotes.length === 0) {
  console.error('No routes found for this token pair');
  return;
}
Always include your app name for better support:
const quotes = await getQuotes({
  // ... other params
  integratorName: 'MyDeFiApp'
});

Execute Swap

Execute the swap using a quote