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 install @cowprotocol/sdk-flash-loans @cowprotocol/sdk-trading
How It Works
Borrow tokens via Aave flash loan
The SDK initiates a flash loan from Aave Protocol V3 to borrow the required assets
Execute CoW Protocol swap
The borrowed assets are swapped to the desired collateral using CoW Protocol’s batch auction system
Use CoW hooks to manage flow
Pre and post-execution hooks deploy adapter contracts and manage the entire swap flow
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
Custom default gas limits for hooks
Pre-hook gas limit (default: 300,000)
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
Chain ID where the swap will execute
Standard trading parameters
Token to sell (underlying asset address)
Order validity in seconds
Slippage tolerance in basis points
Aave aToken address used as collateral
Flash loan fee percentage (default: 0.05 for 0.05%)
Advanced settings
Skip automatic approval check (default: false)
EIP-2612 permit for gasless approval
Per-operation gas limits override
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)
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
Parameters used for quote
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
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%
}
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 + swapSolution: Increase amount or adjust flash loan fee{
amount: '25000000000000000000', // Increase from 20 to 25
flashLoanFeePercent: 0.05,
}
Error: Slippage tolerance too low for market conditionsSolution: Increase slippageBps{
slippageBps: 100, // Increase to 1%
}
Error: Order validity period too shortSolution: Increase validFor{
validFor: 1200, // 20 minutes
}
Insufficient collateral allowance
Error: Adapter doesn’t have approval to spend collateralSolution: Approve collateral or use permitconst 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
