Flash Loans SDK

Execute flash loan-based collateral swaps with Aave Protocol V3 and CoW Protocol

The Flash Loans SDK enables capital-efficient collateral swaps using Aave V3 flash loans integrated with CoW Protocol’s intent-based trading for optimal execution.

Installation

npm

npm install @cowprotocol/sdk-flash-loans @cowprotocol/sdk-trading

How It Works

1. Borrow tokens via Aave flash loan

   The SDK initiates a flash loan from Aave Protocol V3 to borrow the required assets

2. Execute CoW Protocol swap

   The borrowed assets are swapped to the desired collateral using CoW Protocol’s batch auction system

3. Use CoW hooks to manage flow

   Pre and post-execution hooks deploy adapter contracts and manage the entire swap flow

4. Repay flash loan automatically

   The flash loan is automatically repaid with fees, completing the atomic transaction

Why Use Flash Loans?

• Capital Efficiency - No upfront capital required to swap collateral
• Atomic Execution - The entire operation succeeds or reverts atomically
• Gas Optimization - Single transaction for complex multi-step operations
• Aave Integration - Leverage Aave V3’s flash loan infrastructure
• CoW Protocol Benefits - MEV protection and optimal execution via batch auctions

Constructor

AaveCollateralSwapSdk

options · AaveCollateralSwapSdkOptions

Optional SDK configuration

Show options

hooksGasLimit · HooksGasLimit

Custom default gas limits for hooks

Show hooksGasLimit

pre · bigint

Pre-hook gas limit (default: 300,000)

post · bigint

Post-hook gas limit (default: 600,000)

import { AaveCollateralSwapSdk } from '@cowprotocol/sdk-flash-loans'

// Default configuration
const flashLoanSdk = new AaveCollateralSwapSdk()

// Custom gas limits
const flashLoanSdk = new AaveCollateralSwapSdk({
  hooksGasLimit: {
    pre: 500000n,
    post: 800000n,
  },
})

Methods

collateralSwap

Execute a complete flash loan-based collateral swap with automatic approval handling.

params · CollateralSwapParams · required

Swap parameters

Show params

chainId · SupportedChainId · required

Chain ID where the swap will execute

tradeParameters · TradeParameters · required

Standard trading parameters

Show tradeParameters

sellToken · string · required

Token to sell (underlying asset address)

sellTokenDecimals · number · required

Decimals of sell token

buyToken · string · required

Token to buy

buyTokenDecimals · number · required

Decimals of buy token

amount · string · required

Amount to sell in wei

kind · OrderKind · required

Order kind (SELL or BUY)

validFor · number

Order validity in seconds

slippageBps · number

Slippage tolerance in basis points

collateralToken · string · required

Aave aToken address used as collateral

flashLoanFeePercent · number

Flash loan fee percentage (default: 0.05 for 0.05%)

settings · CollateralSwapSettings

Advanced settings

Show settings

preventApproval · boolean

Skip automatic approval check (default: false)

collateralPermit · PermitSignature

EIP-2612 permit for gasless approval

hooksGasLimit · HooksGasLimit

Per-operation gas limits override

tradingSdk · TradingSdk · required

Initialized TradingSdk instance

import { AaveCollateralSwapSdk } from '@cowprotocol/sdk-flash-loans'
import { TradingSdk } from '@cowprotocol/sdk-trading'
import { SupportedChainId, OrderKind } from '@cowprotocol/sdk-config'

const flashLoanSdk = new AaveCollateralSwapSdk()

const result = await flashLoanSdk.collateralSwap(
  {
    chainId: SupportedChainId.GNOSIS_CHAIN,
    tradeParameters: {
      sellToken: '0xe91D153E0b41518A2Ce8Dd3D7944Fa863463a97d', // WXDAI
      sellTokenDecimals: 18,
      buyToken: '0x2a22f9c3b484c3629090FeED35F17Ff8F88f76F0', // USDC.e
      buyTokenDecimals: 6,
      amount: '20000000000000000000', // 20 WXDAI
      kind: OrderKind.SELL,
      validFor: 600,
      slippageBps: 50,
    },
    collateralToken: '0xd0Dd6cEF72143E22cCED4867eb0d5F2328715533', // aGnoWXDAI
    flashLoanFeePercent: 0.05,
  },
  tradingSdk
)

console.log('Order created:', result.orderId)

orderId · string

Unique identifier for the created order

getSwapQuoteParams

Prepare quote parameters for manual quote fetching.

params · CollateralSwapParams · required

Same parameters as collateralSwap

const quoteParams = await flashLoanSdk.getSwapQuoteParams(params)
const { quoteResults } = await tradingSdk.getQuote(quoteParams)

console.log('Buy amount:', quoteResults.amountsAndCosts.afterSlippage.buyAmount)

getOrderPostingSettings

Generate order settings and get the flash loan adapter instance address.

params · CollateralSwapParams · required

Swap parameters

quoteParams · TradeParameters · required

Parameters used for quote

quoteResults · QuoteResults · required

Results from getQuote

const { swapSettings, instanceAddress } = await flashLoanSdk.getOrderPostingSettings(
  params,
  quoteParams,
  quoteResults
)

console.log('Adapter address:', instanceAddress)

getCollateralAllowance

Check the current collateral token allowance for the flash loan adapter.

params · CollateralAllowanceParams · required

Show params

trader · string · required

Trader address

collateralToken · string · required

Aave aToken address

amount · bigint · required

Required amount

instanceAddress · string · required

Flash loan adapter address

const allowance = await flashLoanSdk.getCollateralAllowance({
  trader: ownerAddress,
  collateralToken: '0xd0Dd6cEF72143E22cCED4867eb0d5F2328715533',
  amount: BigInt('20000000000000000000'),
  instanceAddress,
})

console.log('Current allowance:', allowance.toString())

approveCollateral

Approve the flash loan adapter to spend collateral tokens.

params · CollateralApprovalParams · required

Same structure as getCollateralAllowance params

if (allowance < requiredAmount) {
  const txResponse = await flashLoanSdk.approveCollateral({
    trader: ownerAddress,
    collateralToken: '0xd0Dd6cEF72143E22cCED4867eb0d5F2328715533',
    amount: BigInt('20000000000000000000'),
    instanceAddress,
  })
  
  console.log('Approval transaction:', txResponse.hash)
}

Complete Examples

Basic Collateral Swap

import { AaveCollateralSwapSdk } from '@cowprotocol/sdk-flash-loans'
import { TradingSdk, OrderKind, SupportedChainId } from '@cowprotocol/sdk-trading'
import { ViemAdapter } from '@cowprotocol/sdk-viem-adapter'
import { createPublicClient, http, privateKeyToAccount } from 'viem'
import { gnosis } from 'viem/chains'

// Set up adapter
const adapter = new ViemAdapter({
  provider: createPublicClient({
    chain: gnosis,
    transport: http('YOUR_RPC_URL')
  }),
  signer: privateKeyToAccount('YOUR_PRIVATE_KEY' as `0x${string}`)
})

// Initialize Trading SDK
const tradingSdk = new TradingSdk(
  {
    chainId: SupportedChainId.GNOSIS_CHAIN,
    appCode: 'aave-flash-loan-app',
  },
  {},
  adapter
)

// Initialize Flash Loan SDK
const flashLoanSdk = new AaveCollateralSwapSdk()

// Execute swap
const result = await flashLoanSdk.collateralSwap(
  {
    chainId: SupportedChainId.GNOSIS_CHAIN,
    tradeParameters: {
      sellToken: '0xe91D153E0b41518A2Ce8Dd3D7944Fa863463a97d', // WXDAI
      sellTokenDecimals: 18,
      buyToken: '0x2a22f9c3b484c3629090FeED35F17Ff8F88f76F0', // USDC.e
      buyTokenDecimals: 6,
      amount: '20000000000000000000', // 20 WXDAI
      kind: OrderKind.SELL,
      validFor: 600,
      slippageBps: 50,
    },
    collateralToken: '0xd0Dd6cEF72143E22cCED4867eb0d5F2328715533', // aGnoWXDAI
    flashLoanFeePercent: 0.05,
  },
  tradingSdk
)

console.log('Flash loan order created:', result.orderId)

Advanced with Manual Approval

const params = {
  chainId: SupportedChainId.GNOSIS_CHAIN,
  tradeParameters: {
    sellToken: '0xe91D153E0b41518A2Ce8Dd3D7944Fa863463a97d',
    sellTokenDecimals: 18,
    buyToken: '0x2a22f9c3b484c3629090FeED35F17Ff8F88f76F0',
    buyTokenDecimals: 6,
    amount: '20000000000000000000',
    kind: OrderKind.SELL,
  },
  collateralToken: '0xd0Dd6cEF72143E22cCED4867eb0d5F2328715533',
  flashLoanFeePercent: 0.05,
}

// Step 1: Get quote parameters
const quoteParams = await flashLoanSdk.getSwapQuoteParams(params)

// Step 2: Get quote
const { quoteResults, postSwapOrderFromQuote } = await tradingSdk.getQuote(quoteParams)

// Step 3: Review quote
const buyAmount = quoteResults.amountsAndCosts.afterSlippage.buyAmount
console.log(`Will receive at least: ${buyAmount} tokens`)

// Step 4: Get order settings
const { swapSettings, instanceAddress } = await flashLoanSdk.getOrderPostingSettings(
  params,
  quoteParams,
  quoteResults
)

// Step 5: Check and approve collateral
const sellAmount = BigInt(params.tradeParameters.amount)
const allowance = await flashLoanSdk.getCollateralAllowance({
  trader: quoteParams.owner,
  collateralToken: params.collateralToken,
  amount: sellAmount,
  instanceAddress,
})

if (allowance < sellAmount) {
  const txResponse = await flashLoanSdk.approveCollateral({
    trader: quoteParams.owner,
    collateralToken: params.collateralToken,
    amount: sellAmount,
    instanceAddress,
  })
  console.log('Approval tx:', txResponse.hash)
}

// Step 6: Post order with manual approval
const result = await flashLoanSdk.collateralSwap(
  {
    ...params,
    settings: {
      preventApproval: true, // Skip auto-approval
    },
  },
  tradingSdk
)

console.log('Order created:', result.orderId)

Understanding Collateral Tokens

What are aTokens?

When you deposit assets into Aave, you receive aTokens (interest-bearing tokens):

• aGnoWXDAI - Aave WXDAI on Gnosis Chain
• aGnoUSDC - Aave USDC on Gnosis Chain
• Accrue interest automatically
• Can be used for flash loan collateral swaps

Common aTokens on Gnosis Chain

const AAVE_TOKENS = {
  aGnoWXDAI: '0xd0Dd6cEF72143E22cCED4867eb0d5F2328715533',
  aGnoUSDC: '0xc6B7AcA6DE8a6044E0e32d0c841a89244A10D284',
}

Flash Loan Fees

Aave flash loans charge a fee (typically 0.05%):

// With 0.05% fee on 20 WXDAI:
// - Flash loan: 20 WXDAI
// - Fee: 0.01 WXDAI
// - Actual swap: 19.99 WXDAI

{
  amount: '20000000000000000000',
  flashLoanFeePercent: 0.05, // 0.05%
}

The fee is automatically deducted before getting the quote to ensure proceeds cover both output and repayment.

Hook Architecture

The SDK uses CoW Protocol hooks to orchestrate the flash loan:

Pre-Hook (300,000 gas default)

• Deploys the Aave adapter contract deterministically
• Transfers the flash loan to the adapter
• Sets up swap parameters

Post-Hook (600,000 gas default)

• Executes collateral swap via the adapter
• Repays Aave flash loan with fees
• Transfers remaining tokens to owner

Gas limits can be customized per operation or set as SDK defaults.

Error Handling

Insufficient flash loan amount

Error: Flash loan amount doesn’t cover fee + swap

Solution: Increase amount or adjust flash loan fee

{
  amount: '25000000000000000000', // Increase from 20 to 25
  flashLoanFeePercent: 0.05,
}

Slippage too tight

Error: Slippage tolerance too low for market conditions

Solution: Increase slippageBps

{
  slippageBps: 100, // Increase to 1%
}

Order expired

Error: Order validity period too short

Solution: Increase validFor

{
  validFor: 1200, // 20 minutes
}

Insufficient collateral allowance

Error: Adapter doesn’t have approval to spend collateral

Solution: Approve collateral or use permit

const allowance = await flashLoanSdk.getCollateralAllowance(...)
if (allowance < amount) {
  await flashLoanSdk.approveCollateral(...)
}

Limitations

• Only supports Aave V3 flash loans
• Requires sufficient liquidity in Aave pools
• Flash loan fees apply (typically 0.05%)
• Subject to CoW Protocol order limits
• Network-specific contract deployments required

Security Considerations

Always review quotes before execution and test with small amounts first.

• Set appropriate slippage tolerances
• Verify token addresses and decimals
• Monitor transaction execution
• Be aware of flash loan fees and costs
• Ensure sufficient collateral balance

Related APIs

• TradingSdk - Core trading functionality
• OrderBookApi - Order book operations
• Hooks - CoW Protocol hooks documentation