avnu

name	avnu
description	Integrate avnu SDK for Starknet DeFi: token swaps with best-price routing, DCA recurring buys, native staking, gasless transactions via paymaster, and market data. Use when building Starknet trading, DEX aggregation, or DeFi automation features.
keywords	["avnu","starknet","defi","swap","dca","staking","paymaster","gasless","l2","dex","aggregator"]
allowed-tools	["Bash","Read","Write","Glob","Grep","Task"]
user-invocable	true

avnu SDK Integration

avnu is the leading DEX aggregator on Starknet, providing optimized swaps across multiple liquidity sources, DCA orders, staking, gasless transactions, and market data APIs.

Installation

npm install @avnu/avnu-sdk starknet

Account Setup

The SDK requires a Starknet account. Two patterns depending on your use case:

Direct Account (Scripts/Backend)

import { Account, RpcProvider } from 'starknet';

const provider = new RpcProvider({
  nodeUrl: process.env.STARKNET_RPC_URL || 'https://rpc.starknet.lava.build'
});

const account = new Account(
  provider,
  process.env.STARKNET_ACCOUNT_ADDRESS!,
  process.env.STARKNET_PRIVATE_KEY!
);

Wallet Account (Frontend/dApps)

import { WalletAccount } from 'starknet';

// User connects their wallet (Argent, Braavos)
const account = await WalletAccount.connect(provider, walletProvider);

Common Token Addresses

const TOKENS = {
  ETH: '0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7',
  STRK: '0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d',
  USDC: '0x053c91253bc9682c04929ca02ed00b3e423f6710d2ee7e0d5ebb06f3ecf368a8',
  USDT: '0x068f5c6a61780768455de69077e07e89787839bf8166decfbf92b645209c0fb8',
};

---

Swap Operations

Get optimized quotes from multiple DEXs and execute swaps with best-price routing.

Get Quotes

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

const quotes = await getQuotes({
  sellTokenAddress: TOKENS.ETH,
  buyTokenAddress: TOKENS.USDC,
  sellAmount: BigInt(1e18), // 1 ETH
  takerAddress: account.address,
  size: 3, // Get top 3 quotes
});

const best = quotes[0];
console.log('Buy amount:', best.buyAmount);
console.log('Price impact:', `${(best.priceImpact / 100).toFixed(2)}%`); // basis points to %
console.log('Gas fees USD:', best.gasFeesInUsd);

Execute Swap

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

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

console.log('Tx hash:', result.transactionHash);

Build Calls Only (for custom execution)

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

const { calls } = await quoteToCalls({
  quote: quotes[0],
  takerAddress: account.address,
  slippage: 0.01,
  includeApprove: true,
});

// Execute manually
const tx = await account.execute(calls);

Slippage Strategies

Token Type	Recommended Slippage
Stablecoins	0.1% - 0.5%
Major tokens (ETH, STRK)	0.5% - 1%
Low liquidity	1% - 3%

See references/swap-guide.md for advanced routing and multi-quote analysis.

---

DCA (Dollar Cost Averaging)

Create recurring buy orders that execute automatically at specified intervals.

Create DCA Order

import { executeCreateDca, createDcaToCalls } from '@avnu/avnu-sdk';
import moment from 'moment';

const dcaOrder = {
  sellTokenAddress: TOKENS.USDC,
  buyTokenAddress: TOKENS.ETH,
  sellAmount: '100000000', // Total 100 USDC (6 decimals)
  sellAmountPerCycle: '10000000', // 10 USDC per execution
  frequency: moment.duration(1, 'day'),
  traderAddress: account.address,
};

const result = await executeCreateDca({
  provider: account,
  order: dcaOrder,
});

console.log('DCA created:', result.transactionHash);

Get User's DCA Orders

import { getDcaOrders, DcaOrderStatus } from '@avnu/avnu-sdk';

const orders = await getDcaOrders({
  traderAddress: account.address,
  status: DcaOrderStatus.ACTIVE,
  page: 0,
  size: 20,
});

orders.content.forEach(order => {
  console.log('Order:', order.orderAddress);
  console.log('Progress:', order.executedTradesCount, '/', order.iterations);
  console.log('Sold:', order.amountSold, '/ Bought:', order.amountBought);
});

Cancel DCA Order

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

const result = await executeCancelDca({
  provider: account,
  orderAddress: '0xorder...',
});

DCA Frequency Options

moment.duration(1, 'hour')   // Hourly
moment.duration(1, 'day')    // Daily
moment.duration(1, 'week')   // Weekly
moment.duration(1, 'month')  // Monthly

See references/dca-guide.md for pricing strategies and order lifecycle.

---

Staking

Stake tokens to earn rewards. Supports STRK and BTC variants.

Stake Tokens

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

const result = await executeStake({
  provider: account,
  poolAddress: '0xpool...',
  amount: BigInt(100e18), // 100 STRK
});

console.log('Staked:', result.transactionHash);

Get Staking Info

import { getUserStakingInfo, getAvnuStakingInfo } from '@avnu/avnu-sdk';

// Get pool info
const stakingInfo = await getAvnuStakingInfo();
console.log('Total staked:', stakingInfo.totalStaked);
console.log('APY:', stakingInfo.apy);

// Get user position
const userInfo = await getUserStakingInfo(
  TOKENS.STRK,
  account.address
);
console.log('Staked:', userInfo.stakedAmount);
console.log('Rewards:', userInfo.pendingRewards);

Claim Rewards

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

// Claim and withdraw
await executeClaimRewards({
  provider: account,
  poolAddress: '0xpool...',
  restake: false,
});

// Claim and restake
await executeClaimRewards({
  provider: account,
  poolAddress: '0xpool...',
  restake: true,
});

Unstake (Two-Step Process)

import { executeInitiateUnstake, executeUnstake } from '@avnu/avnu-sdk';

// Step 1: Initiate unstake (starts cooldown)
await executeInitiateUnstake({
  provider: account,
  poolAddress: '0xpool...',
  amount: BigInt(50e18),
});

// Step 2: After cooldown period (7-21 days), complete withdrawal
await executeUnstake({
  provider: account,
  poolAddress: '0xpool...',
});

See references/staking-guide.md for pool discovery and unbonding periods.

---

Paymaster (Gasless Transactions)

Enable gasless transactions where users pay fees in ERC-20 tokens instead of ETH.

Setup PaymasterRpc

import { PaymasterRpc } from 'starknet';

const paymaster = new PaymasterRpc({
  nodeUrl: 'https://starknet.api.avnu.fi/paymaster/v1',
});

Gasless Swap (User Pays in Token)

import { PaymasterRpc, type PaymasterDetails } from 'starknet';
import { executeSwap } from '@avnu/avnu-sdk';

const paymaster = new PaymasterRpc({
  nodeUrl: 'https://starknet.api.avnu.fi/paymaster/v1',
});

const result = await executeSwap({
  provider: account,
  quote: quotes[0],
  slippage: 0.01,
  paymaster: {
    active: true,
    provider: paymaster,
    params: {
      feeMode: { mode: 'default', gasToken: TOKENS.USDC },
    },
  },
});

With Fee Estimation (Recommended)

import { PaymasterRpc, type PaymasterDetails } from 'starknet';
import { quoteToCalls } from '@avnu/avnu-sdk';

const paymaster = new PaymasterRpc({
  nodeUrl: 'https://starknet.api.avnu.fi/paymaster/v1',
});

// Build calls from quote
const { calls } = await quoteToCalls({
  quote: quotes[0],
  takerAddress: account.address,
  slippage: 0.01,
  includeApprove: true,
});

// Estimate fees
const feeDetails: PaymasterDetails = {
  feeMode: { mode: 'default', gasToken: TOKENS.USDC },
};
const estimation = await account.estimatePaymasterTransactionFee(calls, feeDetails);

// Execute with estimated max fee
const result = await account.executePaymasterTransaction(
  calls,
  feeDetails,
  estimation.suggested_max_fee_in_gas_token
);

See references/paymaster-guide.md for supported tokens and best practices.

---

Gasfree (Sponsored Transactions)

Enable zero-gas-fee transactions where your dApp pays gas on behalf of users. Requires an API key from portal.avnu.fi.

Setup (Backend/Scripts)

import { PaymasterRpc } from 'starknet';

const paymaster = new PaymasterRpc({
  nodeUrl: 'https://starknet.paymaster.avnu.fi',
  headers: {
    'x-paymaster-api-key': process.env.AVNU_PAYMASTER_API_KEY!,
  },
});

Gasfree Swap

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

const result = await executeSwap({
  provider: account,
  quote: quotes[0],
  slippage: 0.01,
  paymaster: {
    active: true,
    provider: paymaster,
    params: {
      feeMode: { mode: 'sponsored' },
    },
  },
});
// User paid $0 in gas!

Frontend Integration (Next.js)

The API key must never be exposed client-side. Use a 3-phase pattern:

// Server Action (API key protected)
'use server';
import { buildPaymasterTransaction, executePaymasterTransaction } from '@avnu/avnu-sdk';

export async function buildSponsoredTx(userAddress: string, calls: Call[]) {
  return buildPaymasterTransaction({
    takerAddress: userAddress,
    paymaster: { provider: getPaymaster(), params: { feeMode: { mode: 'sponsored' } } },
    calls,
  });
}

// Client-side
const prepared = await buildSponsoredTx(account.address, calls);  // 1. Build on server
const signed = await signPaymasterTransaction({ provider: account, typedData: prepared.typed_data });  // 2. Sign on client
const result = await executeSponsoredTx(account.address, signed);  // 3. Execute on server

See references/gasfree-frontend.md for complete Next.js integration with hooks and error handling. See scripts/gasfree-swap.ts for a runnable backend example.

Gasless vs Gasfree

Mode	Who Pays	API Key	Best For
Gasless	User (in token)	No	Users without ETH
Gasfree	dApp	Yes	Zero-friction UX

---

Tokens & Prices

Fetch token lists and real-time market data.

Fetch Tokens

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

// Get paginated token list
const page = await fetchTokens({
  page: 0,
  size: 50,
  tags: ['Verified'],
});

page.content.forEach(token => {
  console.log(token.symbol, token.address, token.decimals);
});

// Get verified token by symbol
const eth = await fetchVerifiedTokenBySymbol('ETH');
const strk = await fetchVerifiedTokenBySymbol('STRK');

Get Token Prices

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

const prices = await getPrices([
  TOKENS.ETH,
  TOKENS.STRK,
  TOKENS.USDC,
]);

prices.forEach(p => {
  console.log('Address:', p.address);
  console.log('Global USD:', p.globalMarket?.usd);
  console.log('Starknet USD:', p.starknetMarket?.usd);
});

Token tags: Verified, Community, Unruggable, AVNU, Unknown. See references/tokens-prices.md for OHLCV data.

---

Error Quick Reference

Error	Cause	Solution
INSUFFICIENT_LIQUIDITY	No route found	Reduce amount or try different pair
SLIPPAGE_EXCEEDED	Price moved during execution	Increase slippage or refresh quote
QUOTE_EXPIRED	Quote too old (>30s)	Fetch new quote before executing
PAYMASTER_REJECTED	Transaction not eligible	Check token/amount eligibility
INSUFFICIENT_BALANCE	Not enough tokens	Validate balance before execute

See references/error-handling.md for complete error taxonomy.

---

Configuration

Environment Variables

# Required for direct account
STARKNET_ACCOUNT_ADDRESS=0x...
STARKNET_PRIVATE_KEY=0x...         # NEVER commit!

# Optional
STARKNET_RPC_URL=https://rpc.starknet.lava.build

SDK Options

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

const options: AvnuOptions = {
  baseUrl: 'https://starknet.api.avnu.fi', // Default
  impulseBaseUrl: 'https://starknet.impulse.avnu.fi', // DCA API
  abortSignal: controller.signal, // Request cancellation
};

// Pass to any SDK call
const quotes = await getQuotes(request, options);

Networks

Network	Base URL
Mainnet	https://starknet.api.avnu.fi
Sepolia	https://sepolia.api.avnu.fi

See references/configuration.md for complete setup guide.

---

References & Examples

Guides: swap-guide | dca-guide | staking-guide | paymaster-guide | gasfree-frontend | tokens-prices | error-handling | configuration

Scripts: swap-example.ts | dca-example.ts | staking-example.ts | gasless-swap.ts | gasfree-swap.ts

Links: Docs | SDK GitHub | App