avnu Developers

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

QuoteRequest

required

Quote request parameters

Show QuoteRequest properties

string

required

Token address to sell (hex format)

string

required

Token address to buy (hex format)

bigint

Amount to sell in smallest unit. Either sellAmount or buyAmount required.

bigint

Amount to buy in smallest unit. Either sellAmount or buyAmount required.

string

Address that will execute the swap

number

default:1

Number of quotes to return (1-5)

string[]

Array of source names to exclude from routing

bigint

Fee in basis points (e.g., 30n for 0.3%)

string

Address to receive integrator fees (required when integratorFees is set)

string

Your integration identifier for tracking

AvnuOptions

Optional SDK configuration

Show AvnuOptions properties

string

Custom API base URL (default: https://starknet.api.avnu.fi)

string

Custom Impulse API base URL for market data (default: https://starknet.impulse.avnu.fi)

AbortSignal

AbortSignal to cancel the request

string

Public key for response verification

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

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

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

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

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

Use the avnu Token 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:

import { fetchTokens } from '@avnu/avnu-sdk';

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

Always use fresh quotes

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.

Use bigint for amounts

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

Handle no routes case

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

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

Set integrator name

Always include your app name for better support:

const quotes = await getQuotes({
  // ... other params
  integratorName: 'MyDeFiApp'
});

Execute Swap

Execute the swap using a quote

Developer Docs

Get Quotes

Overview

SDK Method

Parameters

Returns

Quote Interface

Fee Interface

Route Interface

Example

Quote Response

Best Practices

Execute Swap

​Overview

​SDK Method

​Parameters

​Returns

​Quote Interface

​Fee Interface

​Route Interface

​Example

​Quote Response

​Best Practices

​Related

Execute Swap

Overview

SDK Method

Parameters

Returns

Quote Interface

Fee Interface

Route Interface

Example

Quote Response

Best Practices

Related