avnu Developers

avnu SDK v4 introduces significant improvements including a new paymaster architecture leveraging starknet.js, streamlined function naming, enhanced type safety with Zod validation, and new services for market data and staking. If you encounter any missing changes, please let us know and we will update this guide.

This guide covers breaking changes that require code modifications. Review each section carefully before upgrading.

Quick Summary

Function Renaming: fetch* functions renamed to get* (e.g., fetchQuotes → getQuotes)
Paymaster Architecture: Now uses starknet.js PaymasterInterface instead of SDK-internal handling
executeSwap Signature: Changed from positional arguments to a single params object
DCA Service: Refactored with new *ToCalls + execute* pattern
Type Changes: Quote, Route, Page, and other types have structural changes
Slippage: Now expressed as decimal (0.01 = 1%) consistently

Prerequisites

Before migrating, ensure you have:

# Update starknet.js to v8.9+ (required for PaymasterInterface)
npm install starknet@^8.9.1

# Update the SDK
npm install @avnu/avnu-sdk@^4.0.0

Node.js >= 22 is required for SDK v4.0.0.

Breaking Changes

Swap Service

Function Renaming

v3 Function	v4 Function	Notes
`fetchQuotes()`	`getQuotes()`	Same functionality
`fetchSources()`	`getSources()`	Same functionality
`fetchBuildExecuteTransaction()`	`quoteToCalls()`	Returns `AvnuCalls`
`calculateMinAmount()`	`calculateMinReceivedAmount()`	Slippage semantics changed

New Function

calculateMaxSpendAmount(amount, slippage) - Calculate max spend amount for exactTokenTo swaps

Removed Functions

fetchPrices() - Use getQuotes() or the new Impulse service getPrices()
fetchBuildSwapTypedData() - Paymaster flow refactored
fetchExecuteSwapTransaction() - Paymaster flow refactored

`executeSwap` Signature Change

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

const response = await executeSwap(
  account,           // AccountInterface
  quote,             // Quote
  {                  // ExecuteSwapOptions
    executeApprove: true,
    slippage: 0.005,
  },
  { baseUrl: '...' } // AvnuOptions
);

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

const response = await executeSwap(
  {                    // InvokeSwapParams
    provider: account, // AccountInterface
    quote,             // Quote
    slippage: 0.005,   // Required (decimal: 0.005 = 0.5%)
    executeApprove: true,
  },
  { baseUrl: '...' }   // AvnuOptions
);

`quoteToCalls` Change

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

const { calls } = await fetchBuildExecuteTransaction(
  quoteId,
  takerAddress,
  slippage,
  true // includeApprove
);

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

const { calls, chainId } = await quoteToCalls({
  quoteId,
  slippage: 0.005,
  takerAddress,     // optional
  executeApprove: true,
});

DCA Service

The DCA service has been refactored with a new pattern separating call building from execution.

Function Renaming

v3 Function	v4 Function
`fetchGetOrders()`	`getDcaOrders()`
`fetchCreateOrder()`	`createDcaToCalls()`
`fetchCancelOrder()`	`cancelDcaToCalls()`
`executeCreateOrder()`	`executeCreateDca()`
`executeCancelOrder()`	`executeCancelDca()`

Removed Functions

These low-level functions have been removed in favor of the new pattern:

fetchEstimateFeeCreateOrder()
fetchEstimateFeeCancelOrder()
fetchBuildCreateOrderTypedData()
fetchBuildCancelOrderTypedData()
fetchExecuteCreateOrder()
fetchExecuteCancelOrder()

Type Renaming

v3 Type	v4 Type
`CreateOrderDto`	`CreateDcaOrder`
`OrderReceipt`	`DcaOrder`
`OrderStatus`	`DcaOrderStatus`
`Trade`	`DcaTrade`
`TradeStatus`	`DcaTradeStatus`
`GetOrdersParams`	`GetDcaOrdersParams`

DCA Migration Example

import { executeCreateOrder, fetchGetOrders } from '@avnu/avnu-sdk';

// Get orders
const orders = await fetchGetOrders({ traderAddress });

// Create order
const response = await executeCreateOrder(
  account,
  order,
  { gasless: true, gasTokenAddress: '0x...' }
);

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

// Get orders
const orders = await getDcaOrders({ traderAddress });

// Create order
const response = await executeCreateDca({
  provider: account,
  order,
  // Paymaster now uses starknet.js PaymasterInterface
});

Paymaster (Critical Change)

The paymaster architecture has fundamentally changed. V3’s built-in gasless handling has been replaced with starknet.js PaymasterInterface integration.

v3 Approach (Removed)

In v3, gasless transactions were handled internally by the SDK:

// v3 - NO LONGER WORKS
const response = await executeSwap(account, quote, {
  gasless: true,
  gasTokenAddress: '0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7',
  maxGasTokenAmount: BigInt('1000000000000000000'),
});

v4 Approach (New)

In v4, you must use a PaymasterInterface from starknet.js:

import { executeSwap } from '@avnu/avnu-sdk';
// PaymasterInterface comes from starknet.js
import { PaymasterInterface } from 'starknet';

// Create your paymaster provider (implementation depends on your setup)
const paymasterProvider: PaymasterInterface = /* your paymaster implementation */;

const response = await executeSwap({
  provider: account,
  quote,
  slippage: 0.005,
  paymaster: {
    active: true,
    provider: paymasterProvider,
    params: executionParams, // ExecutionParameters from starknet.js
  },
});

New Paymaster Functions

The SDK now exposes dedicated paymaster functions for advanced use cases:

buildPaymasterTransaction() - Build a transaction for the paymaster
signPaymasterTransaction() - Sign the typed data
executePaymasterTransaction() - Execute the signed transaction
executeAllPaymasterFlow() - Helper that chains all three steps

For detailed paymaster configuration, refer to the starknet.js documentation and the avnu Paymaster docs.

Token Service

The token service has minimal breaking changes. New functions have been added:

fetchTokenByAddress(tokenAddress) - Get a specific token by address
fetchVerifiedTokenBySymbol(symbol) - Get a verified token by symbol

Type Changes

`Quote` Type

// v3
interface Quote {
  buyAmountWithoutFees: bigint;
  buyAmountWithoutFeesInUsd: number;
  gasFees: bigint;
  gasFeesInUsd: number;
  avnuFees: bigint;
  avnuFeesInUsd: number;
  avnuFeesBps: bigint;
  integratorFees: bigint;
  integratorFeesInUsd: number;
  integratorFeesBps: bigint;
  liquiditySource: string;
  gasless: Gasless;
  // ...
}

// v4
interface Quote {
  fee: Fee;           // Consolidated fee structure
  priceImpact: number;        // New
  estimatedSlippage?: number; // New
  gasFees: bigint;
  gasFeesInUsd?: number;      // Now optional
  // ...
}

interface Fee {
  feeToken: string;
  avnuFees: bigint;
  avnuFeesInUsd: number;
  avnuFeesBps: bigint;
  integratorFees: bigint;
  integratorFeesInUsd: number;
  integratorFeesBps: bigint;
}

`Route` Type

// v3
interface Route {
  routeInfo?: Map<string, string>;
  // ...
}

// v4
interface Route {
  routeInfo?: Record<string, string>; // Changed from Map to Record
  alternativeSwapCount: number;       // New field
  // ...
}

`Source` Type

// v3
interface Source {
  name: string;
  address: string;  // Removed in v4
  icon?: string;    // Removed in v4
  type: SourceType;
}

// v4
interface Source {
  name: string;
  type: SourceType;
}

`SourceType` Enum

// v3
enum SourceType {
  DEX = 'DEX',
  MARKET_MAKER = 'MARKET_MAKER',
  SOLVER = 'SOLVER',        // Removed in v4
  ORDERBOOK = 'ORDERBOOK',
}

// v4
enum SourceType {
  DEX = 'DEX',
  MARKET_MAKER = 'MARKET_MAKER',
  TOKEN_WRAPPER = 'TOKEN_WRAPPER', // New
  ORDERBOOK = 'ORDERBOOK',
}

`Page<T>` Type

// v3
interface Page<T> {
  content: T[];
  totalPages: number;
  totalElements: number;
  size: number;
  number: number;  // Field name in v3
}

// v4
interface Page<T> {
  content: T[];
  totalPages: number;
  totalElements: number;
  size: number;
  page: number;    // Renamed from 'number' to 'page'
}

Slippage Semantics

Slippage is now consistently expressed as a decimal value.

Value	Meaning
`0.001`	0.1% slippage
`0.005`	0.5% slippage
`0.01`	1% slippage
`0.05`	5% slippage

// Correct usage in v4
const minReceived = calculateMinReceivedAmount(amount, 0.005); // 0.5% slippage
const maxSpend = calculateMaxSpendAmount(amount, 0.01);        // 1% slippage

Gas Fees Denomination

Gas fees are now denominated in STRK instead of ETH.

In v3, the gasFees field in quotes was denominated in ETH (WEI). Starting from v4, gas fees are denominated in STRK (FRI).

// v3 - Gas fees in ETH (WEI)
const gasFeesInEth = quote.gasFees; // BigInt in WEI

// v4 - Gas fees in STRK (FRI)
const gasFeesInStrk = quote.gasFees; // BigInt in FRI

New Features (Non-Breaking)

Impulse Service (Market Data)

New service for market data, prices, volume, and TVL:

import {
  getMarketData,
  getTokenMarketData,
  getPriceFeed,
  getPrices,
  getVolumeByExchange,
  getTVLByExchange,
  FeedDateRange,
  PriceFeedType,
  FeedResolution,
} from '@avnu/avnu-sdk';

// Get popular tokens with market data
const marketData = await getMarketData();

// Get price feed for a token
const priceFeed = await getPriceFeed(
  tokenAddress,
  {
    type: PriceFeedType.CANDLE,
    dateRange: FeedDateRange.ONE_DAY,
    resolution: FeedResolution.HOURLY,
  }
);

Staking Service

New service for avnu stake delegation:

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

// Get staking info
const stakingInfo = await getAvnuStakingInfo();

// Stake tokens
const response = await executeStake({
  provider: account,
  poolAddress: '0x...',
  amount: BigInt('1000000000000000000'),
});

Zod Validation

All API responses are now validated and transformed using Zod schemas:

Automatic hex string to BigInt conversion
Automatic ISO string to Date conversion
Runtime type safety

Migration Checklist

Update Dependencies

npm install @avnu/avnu-sdk@^4.0.0 starknet@^6.0.0

Update Function Imports

Replace fetch* imports with get*:

// Before
import { fetchQuotes, fetchSources } from '@avnu/avnu-sdk';

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

Update executeSwap Calls

Change from positional arguments to params object:

// Before
executeSwap(account, quote, options, avnuOptions)

// After
executeSwap({ provider: account, quote, slippage, ...options }, avnuOptions)

Update Paymaster Integration

If using gasless transactions, implement PaymasterInterface from starknet.js.

Update DCA Calls

Replace old DCA functions with new pattern:

fetchGetOrders → getDcaOrders
executeCreateOrder → executeCreateDca
executeCancelOrder → executeCancelDca

Update Type References

Page.number → Page.page
Route.routeInfo is now Record<string, string> instead of Map
Access fees via quote.fee instead of individual fee fields

Verify Slippage Values

Ensure all slippage values are decimals (0.01 = 1%).

Test Your Integration

Run your test suite and verify all functionality works as expected.

Troubleshooting

TypeError: fetchQuotes is not a function

The function has been renamed to getQuotes. Update your import:

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

TypeError: Cannot read property 'number' of undefined

The Page type’s number field has been renamed to page:

// Before
const currentPage = result.number;

// After
const currentPage = result.page;

Gasless transactions not working

Gasless handling has moved to starknet.js PaymasterInterface. You need to:

Create a PaymasterInterface implementation
Pass it via the paymaster parameter

See the Paymaster section for details.

Type error on Quote.avnuFees

Fee fields are now consolidated under quote.fee:

// Before
const fees = quote.avnuFees;

// After
const fees = quote.fee.avnuFees;

Route.routeInfo type mismatch

routeInfo changed from Map<string, string> to Record<string, string>:

// Before (Map)
const value = route.routeInfo?.get('key');

// After (Record)
const value = route.routeInfo?.['key'];

Developer Docs

Migrate from v3 to v4

Quick Summary

Prerequisites

Breaking Changes

Swap Service

Function Renaming

New Function

Removed Functions

`executeSwap` Signature Change

`quoteToCalls` Change

DCA Service

Function Renaming

Removed Functions

Type Renaming

DCA Migration Example

Paymaster (Critical Change)

v3 Approach (Removed)

v4 Approach (New)

New Paymaster Functions

Token Service

Type Changes

`Quote` Type

`Route` Type

`Source` Type

`SourceType` Enum

`Page<T>` Type

Slippage Semantics

Gas Fees Denomination

New Features (Non-Breaking)

Impulse Service (Market Data)

Staking Service

Zod Validation

Migration Checklist

Troubleshooting

Resources

​Quick Summary

​Prerequisites

​Breaking Changes

​Swap Service

​Function Renaming

​New Function

​Removed Functions

​executeSwap Signature Change

​quoteToCalls Change

​DCA Service

​Function Renaming

​Removed Functions

​Type Renaming

​DCA Migration Example

​Paymaster (Critical Change)

​v3 Approach (Removed)

​v4 Approach (New)

​New Paymaster Functions

​Token Service

​Type Changes

​Quote Type

​Route Type

​Source Type

​SourceType Enum

​Page<T> Type

​Slippage Semantics

​Gas Fees Denomination

​New Features (Non-Breaking)

​Impulse Service (Market Data)

​Staking Service

​Zod Validation

​Migration Checklist

​Troubleshooting

​Resources

Quick Summary

Prerequisites

Breaking Changes

Swap Service

Function Renaming

New Function

Removed Functions

`executeSwap` Signature Change

`quoteToCalls` Change

DCA Service

Function Renaming

Removed Functions

Type Renaming

DCA Migration Example

Paymaster (Critical Change)

v3 Approach (Removed)

v4 Approach (New)

New Paymaster Functions

Token Service

Type Changes

`Quote` Type

`Route` Type

`Source` Type

`SourceType` Enum

`Page<T>` Type

Slippage Semantics

Gas Fees Denomination

New Features (Non-Breaking)

Impulse Service (Market Data)

Staking Service

Zod Validation

Migration Checklist

Troubleshooting

Resources