avnu Developers

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

Node.js 22+ installed

Step 1: Install the SDK

npm install @avnu/avnu-sdk

yarn add @avnu/avnu-sdk

pnpm add @avnu/avnu-sdk

Step 2: Initialize Your Account

Every execute* method takes a starknet.js account. In a script or backend, build it from a private key:

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

In a dapp, build it around the connected wallet instead. Your wallet-connection layer (get-starknet, @starknet-start/react, …) exposes the wallet-standard object and the connected address — note that hook-based libraries no longer return a ready-made account object, only these two:

import { WalletAccountV6 } from 'starknet';

// walletProvider: the wallet-standard object (e.g. the `connector` from wallet hooks)
// address: the connected address
const account = new WalletAccountV6({ provider, walletProvider, address });

This constructor is the intended API: WalletAccountV6.connect / connectSilent are thin wrappers that fetch the address from the wallet and call it (use connectSilent when you don’t already have the address — no prompt if the dapp is authorized). It subscribes to wallet events, so call account.unsubscribeChange() when you drop or replace the instance.

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

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

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

async function main() {
  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 with integration fees
  const quotes = await getQuotes({
    sellTokenAddress: ethAddress,
    buyTokenAddress: strkAddress,
    sellAmount: parseUnits('0.001', 18),
    takerAddress: account.address,
    integratorFees: 10n, // 0.1% fee (10 bps)
    integratorFeeRecipient: '0xYOUR_FEE_RECIPIENT',
    integratorName: 'MyDApp',
  });

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

  await provider.waitForTransaction(result.transactionHash);
  console.log('✅ Swap complete:', result.transactionHash);
}

main().catch(console.error);

ACCOUNT_ADDRESS=0x...
PRIVATE_KEY=0x...

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

Getting Started

Your First Swap

What You’ll Accomplish

Prerequisites

Step 1: Install the SDK

Step 2: Initialize Your Account

Step 3: Fetch Swap Quotes

Step 4: Execute the Swap

Complete Example

Next Steps

Paymaster

API Reference

DCA Orders

Resources

API Reference

SDK

Support

​What You’ll Accomplish

​Prerequisites

​Step 1: Install the SDK

​Step 2: Initialize Your Account

​Step 3: Fetch Swap Quotes

​Step 4: Execute the Swap

​Complete Example

​Next Steps

Paymaster

API Reference

DCA Orders

​Resources

API Reference

SDK

Support

What You’ll Accomplish

Prerequisites

Step 1: Install the SDK

Step 2: Initialize Your Account

Step 3: Fetch Swap Quotes

Step 4: Execute the Swap

Complete Example

Next Steps

Resources