avnu Developers

Overview

Execute a swap in one function call. The SDK handles building calls, approvals, and transaction execution automatically.

SDK Method

executeSwap(
  params: InvokeSwapParams,
  options?: AvnuOptions
): Promise<InvokeTransactionResponse>

Parameters

InvokeSwapParams

required

Show properties

Quote

required

The quote object returned by getQuotes

number

required

Maximum slippage as a decimal (0..1). E.g., 0.001 = 0.1%, 0.01 = 1%

AccountInterface

required

The Starknet account executing the swap

boolean

default:"true"

Whether to automatically handle token approvals

object

Optional paymaster configuration

Example

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

// ... setup provider and account ...

// 1. Get quotes
const quotes = await getQuotes({
  sellTokenAddress: ETH_ADDRESS,
  buyTokenAddress: USDC_ADDRESS,
  sellAmount: parseUnits('1', 18),
  takerAddress: account.address,
});

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

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

// Execute gasless swap
const result = await executeSwap({
  provider: account,
  quote: quotes[0],
  slippage: 0.005, // 0.5%
  paymaster: {
    active: true,
    provider: paymasterProvider, // Your Paymaster instance
    params: {} // Paymaster params
  }
});

// If token is already approved
const result = await executeSwap({
  provider: account,
  quote: quotes[0],
  slippage: 0.005, // 0.5%
  executeApprove: false,
});

Response

{
  transactionHash: '0x...'
}

Slippage Protection

Slippage is defined as a decimal (0..1 range):

0.001 = 0.1%
0.005 = 0.5%
0.01 = 1%

The SDK automatically calculates the minimum received amount: minAmount = buyAmount * (1 - slippage)

Token Approval

By default (executeApprove: true), the SDK:

Checks the user’s current allowance for the avnu router.
If insufficient, adds an approve call to the transaction.
Executes approve and swap in a single multicall (atomic).

Best Practices

Always use fresh quotes

With Starknet’s block time of ~2 seconds, quotes become stale after just 1 block. Refresh quotes every block before execution.

Set appropriate slippage

Stable pairs: 0.001 - 0.003 (0.1% - 0.3%)
Regular pairs: 0.005 - 0.01 (0.5% - 1%)
Volatile pairs: 0.01 - 0.03 (1% - 3%)

Handle failures gracefully

Implement retry logic with exponential backoff for network issues.

Developer Docs

Execute Swap

Overview

SDK Method

Parameters

Example

Response

Slippage Protection

Token Approval

Best Practices

​Overview

​SDK Method

​Parameters

​Example

​Response

​Slippage Protection

​Token Approval

​Best Practices

Overview

SDK Method

Parameters

Example

Response

Slippage Protection

Token Approval

Best Practices