Skip to main content

​
What You’ll Accomplish

By the end of this guide, you’ll have:
  • ✅ Installed the avnu SDK
  • ✅ Fetched the best swap quote
  • ✅ Executed a token swap on Starknet

​
Prerequisites

Download from nodejs.org

​
Step 1: Install the SDK

npm install @avnu/avnu-sdk

​
Step 2: Initialize Your Account

import { RpcProvider, Account } from 'starknet';

// Setup provider & account from starknet.js
const provider = new RpcProvider({
  nodeUrl: 'https://rpc.starknet.lava.build:443'
});

const account = new Account(
  provider,
  'YOUR_ACCOUNT_ADDRESS',
  'YOUR_PRIVATE_KEY'
);

// Or use hook from starknet-react
const { account } = useAccount();
Security Note: Never hardcode private keys in production.

​
Step 3: Fetch Swap Quotes

import { getQuotes } from '@avnu/avnu-sdk';
import { parseUnits } from 'ethers';

const ethAddress = "0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7";
const strkAddress = "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d";

const quotes = await getQuotes({
  sellTokenAddress: ethAddress,
  buyTokenAddress: strkAddress,
  sellAmount: parseUnits('0.001', 18), // 0.001 ETH
  takerAddress: account.address,
  size: 3, // Get top 3 quotes (optional, default: 1)
  excludeSources: [], // Exclude specific DEXs (optional)
});

console.log('Best quote:', quotes[0]);
console.log('Estimated output:', quotes[0].buyAmount);
console.log('Gas fees:', quotes[0].gasFees);
console.log('Route:', quotes[0].routes);
Optional Parameters:
  • size: Number of quotes to return (default: 1)
  • excludeSources: Array of source names to exclude
  • integratorFees: Your integration fees in bps
  • integratorFeeRecipient: Address to receive fees
  • integratorName: Your platform name
  • onlyDirect: if you want only direct routes

​
Step 4: Execute the Swap

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

const result = await executeSwap({
  provider: account,
  quote: quotes[0],
  slippage: 0.001, // 0.1% slippage tolerance
});

console.log('Transaction hash:', result.transactionHash);
Default Behavior:
  • executeApprove: true - Automatically approves token spending if needed
  • slippage - Required parameter for price protection
  • Reverts if price moves beyond slippage tolerance

​
Complete Example

import { RpcProvider, Account } from 'starknet';
import { getQuotes, executeSwap } from '@avnu/avnu-sdk';
import { parseUnits, formatUnits } from 'ethers';

const ethAddress = "0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7";
const strkAddress = "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d";

async function main() {
  // Setup provider & account from starknet.js
  const provider = new RpcProvider({
    nodeUrl: 'https://rpc.starknet.lava.build:443'
  });

  const account = new Account(
    provider,
    process.env.ACCOUNT_ADDRESS!,
    process.env.PRIVATE_KEY!
  );

  // Fetch quotes
  const quotes = await getQuotes({
    sellTokenAddress: ethAddress,
    buyTokenAddress: strkAddress,
    sellAmount: parseUnits('0.001', 18),
    takerAddress: account.address,
  });

  console.log(`Buying ${formatUnits(quotes[0].buyAmount, 18)} STRK`);

  // Execute swap
  const result = await executeSwap({
    provider: account,
    quote: quotes[0],
    slippage: 0.001, // 0.1%
  });

  // Wait for confirmation
  await provider.waitForTransaction(result.transactionHash);
  console.log('✅ Done:', result.transactionHash);
}

main().catch(console.error);

​
Next Steps

Paymaster

Sponsor gas or multi-token gas payments

API Reference

Complete REST API docs

DCA Orders

Add automated recurring buys

​
Resources

API Reference

REST API documentation

SDK

TypeScript/JavaScript SDK

Support

Telegram community