Integrator Fees

How to charge fees as an integrator using the Cross Chain SDK

This guide explains how to collect fees as an integrator when facilitating cross-chain swaps using the 1inch Cross Chain SDK.

Overview

Integrator fees allow you to earn revenue by charging a percentage of each swap. Fees are:

• Specified in basis points (bps) where 100 bps = 1%
• Collected in the destination token
• Sent to a specified receiver address
• Currently supported for EVM-to-EVM swaps only

Fee collection is supported for EVM → EVM swaps only. Solana swaps do not support fees in the current release.

Fee Structure

The SDK uses the Bps type for fee values:

import { Bps } from '@1inch/cross-chain-sdk'

// 1% fee = 100 basis points
const fee = new Bps(100n)

// 0.5% fee = 50 basis points
const fee = new Bps(50n)

// 2.5% fee = 250 basis points
const fee = new Bps(250n)

Basic Implementation

1. Import Required Types

   Import the Bps type along with other SDK components.

   import {
     SDK,
     NetworkEnum,
     PrivateKeyProviderConnector,
     Bps,
     EvmAddress
   } from '@1inch/cross-chain-sdk'
   
2. Define Fee Parameters

   Set your fee receiver address and fee percentage.

   const integratorFeeReceiver = '0xYourFeeReceiverAddress'
   const feePercentage = new Bps(100n) // 1% fee
   

   Ensure you control the fee receiver address. Fees sent to incorrect addresses cannot be recovered.

3. Include Fee in Quote Request

   Pass the integratorFee parameter when requesting a quote.

   const quote = await sdk.getQuote({
     amount: '10000000',
     srcChainId: NetworkEnum.POLYGON,
     dstChainId: NetworkEnum.BINANCE,
     srcTokenAddress: '0xc2132d05d31c914a87c6611c10748aeb04b58e8f', // USDT
     dstTokenAddress: '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee', // BNB
     walletAddress,
     enableEstimate: true,
     integratorFee: {
       receiver: EvmAddress.fromString(integratorFeeReceiver),
       value: new Bps(100n) // 1% fee
     }
   })
   
4. Access Fee Information

   The quote response includes fee details.

   // Fee information is available in the quote
   console.log('Integrator fee:', quote.integratorFee)
   // { receiver, value, share }
   
   console.log('Resolver fee:', quote.resolverFee)
   // { receiver, bps, whitelistDiscount }
   
5. Create and Submit Order

   Create the order normally - fees are automatically included from the quote.

   const { hash, quoteId, order } = await sdk.createOrder(quote, {
     walletAddress,
     hashLock,
     preset: PresetEnum.fast,
     source: 'my-integration',
     secretHashes
   })
   
   await sdk.submitOrder(quote.srcChainId, order, quoteId, secretHashes)
   

   Fees are automatically deducted from the destination amount and sent to your receiver address.

Complete Example with Fees

import {
  SDK,
  PrivateKeyProviderConnector,
  NetworkEnum,
  PresetEnum,
  HashLock,
  Bps,
  EvmAddress
} from '@1inch/cross-chain-sdk'
import Web3 from 'web3'
import { randomBytes } from 'node:crypto'

const privateKey = '0x...'
const rpc = 'https://polygon-rpc.com'
const authKey = 'your-auth-key'

const web3 = new Web3(rpc)
const walletAddress = web3.eth.accounts.privateKeyToAccount(privateKey).address

const sdk = new SDK({
  url: 'https://api.1inch.com/fusion-plus',
  authKey,
  blockchainProvider: new PrivateKeyProviderConnector(privateKey, web3)
})

async function swapWithFee() {
  // Define integrator fee (1%)
  const integratorFeeReceiver = '0xYourFeeReceiverAddress'
  
  const quote = await sdk.getQuote({
    amount: '10000000',
    srcChainId: NetworkEnum.POLYGON,
    dstChainId: NetworkEnum.BINANCE,
    srcTokenAddress: '0xc2132d05d31c914a87c6611c10748aeb04b58e8f',
    dstTokenAddress: '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee',
    walletAddress,
    enableEstimate: true,
    integratorFee: {
      receiver: EvmAddress.fromString(integratorFeeReceiver),
      value: new Bps(100n) // 1% fee
    }
  })

  console.log('Fee details:', {
    integratorFee: quote.integratorFee,
    resolverFee: quote.resolverFee
  })

  const preset = PresetEnum.fast
  const secrets = Array.from({
    length: quote.presets[preset].secretsCount
  }).map(() => '0x' + randomBytes(32).toString('hex'))

  const hashLock = secrets.length === 1
    ? HashLock.forSingleFill(secrets[0])
    : HashLock.forMultipleFills(HashLock.getMerkleLeaves(secrets))

  const secretHashes = secrets.map((s) => HashLock.hashSecret(s))

  const { hash, quoteId, order } = await sdk.createOrder(quote, {
    walletAddress,
    hashLock,
    preset,
    source: 'my-integration',
    secretHashes
  })

  await sdk.submitOrder(quote.srcChainId, order, quoteId, secretHashes)
  
  console.log('Order submitted with integrator fee:', hash)
}

swapWithFee()

Fee Response Types

The quote response includes detailed fee information:

type IntegratorFeeResponse = {
  receiver: EvmAddress  // Your fee receiver address
  value: Bps            // Fee in basis points (100 = 1%)
  share: Bps            // Your share (rest goes to protocol)
}

type ResolverFeeParams = {
  receiver: EvmAddress      // Resolver fee receiver
  bps: Bps                  // Resolver fee in basis points
  whitelistDiscount: Bps    // Discount for whitelisted integrators
}

Migration from v1.x

If you’re upgrading from v1.x, update your code:

v1.x (Old)

const quote = await sdk.getQuote({
  amount: '10000000',
  srcChainId: NetworkEnum.POLYGON,
  dstChainId: NetworkEnum.BINANCE,
  srcTokenAddress: '0x...',
  dstTokenAddress: '0x...',
  walletAddress,
  takingFeeBps: 100 // Old parameter
})

Key Changes

v1.x	v2.x
takingFeeBps?: number	integratorFee?: IntegratorFeeRequest
OrderParams.fee?: TakingFeeInfo	Removed (fees derived from quote)
Fee in number	Fee in Bps type with receiver

Fee Calculation Examples

// Example swap: 100 USDT → BNB with 1% integrator fee
const swapAmount = 100 // USDT
const integratorFeeBps = 100n // 1%

// Fee calculation
const feeAmount = (swapAmount * Number(integratorFeeBps)) / 10000
console.log('Fee amount:', feeAmount) // 1 USDT equivalent in BNB
console.log('User receives:', swapAmount - feeAmount) // 99 USDT equivalent in BNB

// Different fee percentages
const fees = [
  { bps: 50n, percent: '0.5%' },
  { bps: 100n, percent: '1%' },
  { bps: 250n, percent: '2.5%' },
  { bps: 500n, percent: '5%' }
]

fees.forEach(({ bps, percent }) => {
  const fee = new Bps(bps)
  console.log(`${percent} = ${bps} bps = new Bps(${bps}n)`)
})

Best Practices

Transparent Fees

Display fee amounts clearly to users before they confirm swaps.

Competitive Rates

Set reasonable fees that balance revenue with user experience.

Secure Receiver

Use a secure, controlled address for fee collection.

Track Revenue

Monitor fee collection for accounting and analytics.

Fee Validation

Validate fee parameters before submitting:

function validateIntegratorFee(
  receiver: string,
  bps: bigint
): { valid: boolean; error?: string } {
  // Validate receiver address
  if (!receiver.match(/^0x[a-fA-F0-9]{40}$/)) {
    return { valid: false, error: 'Invalid receiver address format' }
  }

  // Validate fee range (0-10% = 0-1000 bps)
  if (bps < 0n || bps > 1000n) {
    return { valid: false, error: 'Fee must be between 0 and 10%' }
  }

  return { valid: true }
}

const validation = validateIntegratorFee(integratorFeeReceiver, 100n)
if (!validation.valid) {
  throw new Error(validation.error)
}

Monitoring Fee Collection

Track fees collected from your integration:

import { EvmAddress } from '@1inch/cross-chain-sdk'

async function trackFees(orders: string[]) {
  let totalFeesCollected = 0n

  for (const orderHash of orders) {
    const status = await sdk.getOrderStatus(orderHash)
    
    if (status.status === OrderStatus.Executed) {
      // Fee info is in the order details
      console.log('Order executed:', orderHash)
      console.log('Fee collected:', status.integratorFee)
      // Add to analytics/database
    }
  }
}

Common Fee Amounts

Use Case	Basis Points	Percentage
Low fee	25 bps	0.25%
Standard	50 bps	0.5%
Common	100 bps	1%
Higher	250 bps	2.5%
Maximum recommended	500 bps	5%

Limitations

Current Limitations:

• Fees only supported for EVM-to-EVM swaps
• Solana swaps do not support integrator fees
• Fees are collected in destination token only
• Fee receiver must be an EVM address

Next Steps

EVM to EVM

Implement EVM swaps with fees

Order Lifecycle

Monitor order execution and fee collection