starknet-defi

Starknet DeFi Skill

Execute DeFi operations on Starknet using avnu aggregator and native protocols.

When to Use

• Swaps, DCA orders, staking, and lending or borrowing flows on Starknet.
• Agent workflows that need AVNU routing, paymaster support, or protocol-specific DeFi execution.

When NOT to Use

• Plain wallet management without DeFi intent.
• Cairo contract authoring, deployment operations, or security auditing.

Quick Start

1. Install the AVNU + starknet.js dependencies and point the skill at a funded Starknet account.
2. Use skills catalog when the flow expands into wallet setup, deployment, or auditing.

Prerequisites

npm install starknet@^8.9.1 @avnu/avnu-sdk@^4.0.1

Token Swaps (avnu SDK v4)

Get Quote and Execute Swap

import { getQuotes, executeSwap, type QuoteRequest } from "@avnu/avnu-sdk";
import { Account, RpcProvider, ETransactionVersion } from "starknet";

const provider = new RpcProvider({ nodeUrl: process.env.STARKNET_RPC_URL });

// starknet.js v8: Account uses options object
const account = new Account({
  provider,
  address,
  signer: privateKey,
  transactionVersion: ETransactionVersion.V3,
});

// Resolve token addresses via avnu SDK (or use MCP server's TokenService)
import { fetchVerifiedTokenBySymbol } from '@avnu/avnu-sdk';

const eth = await fetchVerifiedTokenBySymbol('ETH');
const strk = await fetchVerifiedTokenBySymbol('STRK');

// SDK v4: getQuotes takes QuoteRequest object directly
const quoteParams: QuoteRequest = {
  sellTokenAddress: eth.address,
  buyTokenAddress: strk.address,
  sellAmount: BigInt(10 ** 17), // 0.1 ETH
  takerAddress: account.address,
};

const quotes = await getQuotes(quoteParams);
const bestQuote = quotes[0];

// SDK v4: executeSwap takes single object param
const result = await executeSwap({
  provider: account,
  quote: bestQuote,
  slippage: 0.01, // 1%
  executeApprove: true,
});
console.log("Tx:", result.transactionHash);

Quote Response Fields (SDK v4)

interface Quote {
  quoteId: string;
  sellTokenAddress: string;
  buyTokenAddress: string;
  sellAmount: bigint;
  buyAmount: bigint;
  sellAmountInUsd: number;
  buyAmountInUsd: number;
  priceImpact: number;        // In basis points (15 = 0.15%)
  gasFeesInUsd: number;
  routes: Array<{
    name: string;             // e.g., "Ekubo", "JediSwap"
    percent: number;          // e.g., 0.8 = 80%
  }>;
  fee: {
    avnuFees: bigint;
    integratorFees: bigint;
  };
}

Build Swap Calls (for multicall composition)

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

const calls = await quoteToCalls({
  quote: bestQuote,
  takerAddress: account.address,
  slippage: 0.01,
  includeApprove: true,
});
// `calls` can be combined with other calls in account.execute([...calls, ...otherCalls])

Gasless Swap (Pay Gas in Token) - SDK v4 + PaymasterRpc

import { getQuotes, executeSwap } from "@avnu/avnu-sdk";
import { PaymasterRpc } from "starknet";

const quotes = await getQuotes(quoteParams);
const bestQuote = quotes[0];

// SDK v4: Use PaymasterRpc from starknet.js
// Mainnet: https://starknet.paymaster.avnu.fi
// Sepolia: https://sepolia.paymaster.avnu.fi
const paymaster = new PaymasterRpc({
  nodeUrl: process.env.AVNU_PAYMASTER_URL || "https://starknet.paymaster.avnu.fi",
});

const result = await executeSwap({
  provider: account,
  quote: bestQuote,
  slippage: 0.01,
  executeApprove: true,
  paymaster: {
    active: true,
    provider: paymaster,
    params: {
      feeMode: {
        mode: "default",
        gasToken: "0x053c91253bc9682c04929ca02ed00b3e423f6710d2ee7e0d5ebb06f3ecf368a8", // USDC
      },
    },
  },
});

DCA (Dollar Cost Averaging)

Create DCA Order

import { executeCreateDca } from "@avnu/avnu-sdk";
import moment from "moment";

const dcaOrder = {
  sellTokenAddress: usdcAddress,
  buyTokenAddress: strkAddress,
  totalAmount: parseUnits("100", 6),   // Total 100 USDC
  numberOfOrders: 10,                   // Split into 10 orders
  frequency: moment.duration(1, "day"), // moment.Duration object, not string
  startAt: Math.floor(Date.now() / 1000),
};

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

Check and Cancel DCA

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

const orders = await getDcaOrders({
  traderAddress: account.address,
  status: DcaOrderStatus.OPEN,  // Use enum, not string
});

// Cancel an order
await executeCancelDca({
  provider: account,
  orderAddress: orders[0].orderAddress,
});

STRK Staking

Stake STRK

import { executeStake, getAvnuStakingInfo } from "@avnu/avnu-sdk";

// Get pool info
const stakingInfo = await getAvnuStakingInfo();
// stakingInfo.pools[0] = { address, apy, tvl, token, minStake }

const result = await executeStake({
  provider: account,
  poolAddress: stakingInfo.pools[0].address,
  amount: parseUnits("100", 18), // 100 STRK
});

Get User Staking Info

import { getUserStakingInfo } from "@avnu/avnu-sdk";

const userInfo = await getUserStakingInfo(TOKENS.STRK, account.address);
console.log("Staked:", userInfo.amount);
console.log("Unclaimed rewards:", userInfo.unclaimedRewards);

Claim Rewards

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

// Claim and restake (compound)
await executeClaimRewards({
  provider: account,
  poolAddress: poolAddress,
  restake: true,
});

Unstake

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

// Step 1: Initiate (starts cooldown -- 21 days for STRK)
await executeInitiateUnstake({
  provider: account,
  poolAddress: poolAddress,
  amount: parseUnits("50", 18),
});

// Step 2: Complete unstake (after cooldown period)
await executeUnstake({
  provider: account,
  poolAddress: poolAddress,
});

Market Data

Token Prices

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

// Get token by symbol
const strk = await fetchVerifiedTokenBySymbol("STRK");

// Get prices for multiple tokens
const prices = await getPrices([ethAddress, strkAddress, usdcAddress]);
// prices = { "0x049d...": 3200.50, "0x047...": 1.23, ... }

// Browse tokens with pagination
const tokens = await fetchTokens({ page: 0, size: 20, tags: ["verified"] });

Protocol Reference

Protocol	Operations	Notes
avnu	Swap aggregation, DCA, gasless	Best-price routing across all DEXs
Ekubo	AMM, concentrated liquidity	Highest TVL on Starknet
JediSwap	AMM, classic pools	V2 with concentrated liquidity
zkLend	Lending, borrowing	Variable and stable rates
Nostra	Lending, borrowing	Multi-asset pools

Configuration

Variable	Purpose	Default
STARKNET_RPC_URL	Starknet JSON-RPC endpoint	Required
STARKNET_ACCOUNT_ADDRESS	Agent's account address	Required
STARKNET_PRIVATE_KEY	Agent's signing key	Required
AVNU_BASE_URL	avnu API base URL	https://starknet.api.avnu.fi
AVNU_PAYMASTER_URL	avnu paymaster URL	https://starknet.paymaster.avnu.fi
AVNU_API_KEY	Optional avnu integrator key	None

avnu URL Reference

Network	API URL	Paymaster URL
Mainnet	https://starknet.api.avnu.fi	https://starknet.paymaster.avnu.fi
Sepolia	https://sepolia.api.avnu.fi	https://sepolia.paymaster.avnu.fi

Error Handling

async function safeSwap(account, quote, slippage = 0.01) {
  try {
    return await executeSwap({
      provider: account,
      quote,
      slippage,
      executeApprove: true,
    });
  } catch (error) {
    if (error.message?.includes("INSUFFICIENT_BALANCE")) {
      throw new Error("Not enough tokens for swap");
    }
    if (error.message?.includes("SLIPPAGE") || error.message?.includes("Insufficient tokens received")) {
      // Retry with higher slippage
      return await executeSwap({
        provider: account,
        quote,
        slippage: slippage * 2,
        executeApprove: true,
      });
    }
    if (error.message?.includes("QUOTE_EXPIRED")) {
      throw new Error("Quote expired. Please retry the operation.");
    }
    if (error.message?.includes("INSUFFICIENT_LIQUIDITY")) {
      throw new Error("Insufficient liquidity. Try a smaller amount.");
    }
    throw error;
  }
}

References

• avnu SDK Documentation
• avnu Skill (detailed)
• Ekubo Protocol
• zkLend Documentation
• Nostra Finance