Agent Skills: avnu SDK Integration

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