SDK
Swapper

Swapper

Begin by importing SwapperClient into your app. If you are using the SplitsClient, you can access the swapper client as well.

import { SwapperClient } from '@0xsplits/splits-sdk'
 
const swapperClient = new SwapperClient({
  chainId,
  publicClient, // viem public client (optional, required if using any of the contract functions)
  walletClient, // viem wallet client (optional, required if using any contract write functions. must have an account already attached)
  includeEnsNames, // boolean, defaults to false. If true, will return ens names for any swapper owner or beneficiary (only for mainnet)
  // If you want to return ens names on chains other than mainnet, you can pass in a mainnet public client
  // here. Be aware though that the ens name may not necessarily resolve to the proper address on the
  // other chain for non EOAs (e.g. Gnosis Safe's)
  ensPublicClient, // viem public client (optional)
})

OR

import { SplitsClient } from '@0xsplits/splits-sdk'
 
const splitsClient = new SplitsClient({
  chainId,
  publicClient,
  walletClient,
  includeEnsNames,
  ensPublicClient,
})
 
const swapperClient = splitsClient.swapper

Now you're ready to use any of the functions. All Arguments and Responses for these functions are objects. This will make it easier for us to release updates to the SDK without breaking existing implementations.

The SDK comprises 3 different types of functions: Subgraph Reads, Swapper Writes, and Swapper Reads.

Subgraph Reads

These functions make it easier to query the subgraph.

getSwapperMetadata

Returns all metadata for a given swapperAddress.

Usage

const args = {
  swapperAddress: '0x693C49a6296d90e8A8936Ad4836a680F551bb97d',
}
 
const response = await swapperClient.getSwapperMetadata(args)

Arguments

{
  swapperAddress: string
}

Response

{
  type: 'Swapper'
  address: string
  beneficiary: {
    address: string
    ens?: string
  }
  tokenToBeneficiary: {
    address: string
  }
  owner: {
    address: string
    ens?: string
  }
  paused: boolean
  defaultScaledOfferFactorPercent: number
  scaledOfferFactorOverrides: {
    baseToken: {
      address: string
    }
    quoteToken: {
      address: string
    }
    scaledOfferFactorPercent: number
  }[]
}

Swapper Writes

These functions make it easier to call Swapper functions.

createSwapper

Creates a new Swapper contract.

Usage

const args = {
  beneficiary: "0x442C01498ED8205bFD9aaB6B8cc5C810Ed070C8f",
  tokenToBeneficiary: "0x0000000000000000000000000000000000000000",
  defaultScaledOfferFactorPercent: 1,
  scaledOfferFactorOverrides: [
    {
      baseToken: "0x0000000000000000000000000000000000000000",
      quoteToken: "0x0000000000000000000000000000000000000000",
      scaledOfferFactorPercent: 0.1,
    }
  ],
  owner: "0x442C01498ED8205bFD9aaB6B8cc5C810Ed070C8f",
  oracleParams: {
    address: "0x8E0E20Ea43A88214A0908F32Cd14395022e823A6",
  },
}
 
const response = await swapperClient.createSwapper(args)

Arguments

{
  beneficiary: string
  tokenToBeneficiary: string
  defaultScaledOfferFactorPercent: number
  scaledOfferFactorOverrides: {
    baseToken: string
    quoteToken: string
    scaledOfferFactorPercent: number
  }[]
  owner: string
  paused?: boolean # defaults to false
  oracleParams: {
    address?: string
    createOracleParams?: {
      factory: string
      data: string
    }
  }
}

Response

{
  swapperAddress: string
  event: Log # CreateSwapper emitted on SwapperFactory
}

uniV3FlashSwap

Swaps the given tokens for the Swapper's output token. Uses 0xSplits' integration trader contract to trade with UniswapV3.

Usage

const args = {
  swapperAddress: '0x693C49a6296d90e8A8936Ad4836a680F551bb97d',
  inputAssets: [
    {
      encodedPath: '0xb4fbf271143f4fbf7b91a5ded31805e42b2208d60001f41f9840a85d5af5bf1d1762f925bdaddc4201f984',
      token: 0x0000000000000000000000000000000000000000,
      amountIn: BigInt('100000000000000000'),
      amountOutMin: BigInt('1000000000'),
    }
  ]
}
 
const response = await swapperClient.uniV3FlashSwap(args)

Arguments

{
  swapperAddress: string
  # Will receive the excess funds from the uniswap trade after the swapper beneficiary gets their expected output
  excessRecipient?: string # defaults to signer
  # Inputs required for the exact input function for Uniswap V3
  # See: https://docs.uniswap.org/contracts/v3/guides/swaps/multihop-swaps
  inputAssets: {
    encodedPath: string
    token: string
    amountIn: bigint
    amountOutMin: bigint
  }[]
  transactionTimeLimit?: number # In seconds
}

Response

{
  event: Log # Flash emitted on the Swapper contract
}

execCalls

Execute the given list of calls from the Swapper. Only callable by the Swapper owner.

Usage

const args = {
  swapperAddress: "0x693C49a6296d90e8A8936Ad4836a680F551bb97d",
  calls: [
    {
      to: "0x2fa128274cfcf47afd4dc03cd3f2a59af09b6a72",
      value: BigInt(1),
      data: "0x0",
    }
  ]
}
 
const response = await swapperClient.execCalls(args)

Arguments

{
  swapperAddress: string
  calls: {
    to: string
    value: bigint
    data: string
  }[]
}

Response

{
  event: Log # ExecCalls on the Swapper contract
}

setPaused

Updates the pause state of the contract, which blocks executing swaps (except for the contract owner). Only callable by the Swapper owner.

Usage

const args = {
  swapperAddress: "0x693C49a6296d90e8A8936Ad4836a680F551bb97d",
  paused: true,
}
 
const response = await swapperClient.setPaused(args)

Arguments

{
  swapperAddress: string
  paused: boolean
}

Response

{
  event: Log # SetPaused emitted on the Swapper contract
}

setBeneficiary

Updates the beneficiary of the swapper. Only callable by the Swapper owner.

Usage

const args = {
  swapperAddress: "0x693C49a6296d90e8A8936Ad4836a680F551bb97d",
  beneficiary: "0x2fa128274cfcf47afd4dc03cd3f2a59af09b6a72",
}
 
const response = await swapperClient.setBeneficiary(args)

Arguments

{
  swapperAddress: string
  beneficiary: string
}

Response

{
  event: Log # SetBeneficiary emitted on the Swapper contract
}

setTokenToBeneficiary

Updates the token to the beneficiary of the swapper. Only callable by the Swapper owner.

Usage

const args = {
  swapperAddress: "0x693C49a6296d90e8A8936Ad4836a680F551bb97d",
  tokenToBeneficiary: "0x0000000000000000000000000000000000000000",
}
 
const response = await swapperClient.setTokenToBeneficiary(args)

Arguments

{
  swapperAddress: string
  tokenToBeneficiary: string
}

Response

{
  event: Log # SetTokenToBeneficiary emitted on the Swapper contract
}

setOracle

Updates the oracle of the swapper. Only callable by the Swapper owner.

Usage

const args = {
  swapperAddress: "0x693C49a6296d90e8A8936Ad4836a680F551bb97d",
  oracle: "0x8E0E20Ea43A88214A0908F32Cd14395022e823A6",
}
 
const response = await swapperClient.setOracle(args)

Arguments

{
  swapperAddress: string
  oracle: string
}

Response

{
  event: Log # SetOracle emitted on the Swapper contract
}

setDefaultScaledOfferFactor

Updates the default scaled offer factor of the swapper. Only callable by the Swapper owner.

Usage

const args = {
  swapperAddress: "0x693C49a6296d90e8A8936Ad4836a680F551bb97d",
  defaultScaledOfferFactorPercent: 1,
}
 
const response = await swapperClient.setDefaultScaledOfferFactor(args)

Arguments

{
  swapperAddress: string
  defaultScaledOfferFactorPercent: number
}

Response

{
  event: Log # SetDefaultScaledOfferFactor emitted on the Swapper contract
}

setScaledOfferFactorOverrides

Updates the scaled offer factor overrides of the swapper. Only callable by the Swapper owner. NOTE: To remove an existing override you need to pass in a scaled offer factor percent of 100 which tells the contract to fallback to the default scaled offer factor.

Usage

const args = {
  swapperAddress: "0x693C49a6296d90e8A8936Ad4836a680F551bb97d",
  scaledOfferFactorOverrides: [
    {
      baseToken: "0x0000000000000000000000000000000000000000",
      quoteToken: "0x0000000000000000000000000000000000000000",
      scaledOfferFactorPercent: 0.1,
    },
    {
      baseToken: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      quoteToken: "0x0000000000000000000000000000000000000000",
      scaledOfferFactorPercent: 100,
    }
  ]
}
 
const response = await swapperClient.setDefaultScaledOfferFactor(args)

Arguments

{
  swapperAddress: string
  scaledOfferFactorOverrides: {
    baseToken: string
    quoteToken: string
    scaledOfferFactorPercent: number
  }[]
}

Response

{
  event: Log # SetPairScaledOfferFactors emitted on the Swapper contract
}

Gas Estimation

The client has a gas estimation feature that can be used with any of the above write functions. Just call the function off of the estimateGas property. Estimating the gas for the create swapper function would look like:

const args = {
  beneficiary: "0x442C01498ED8205bFD9aaB6B8cc5C810Ed070C8f",
  tokenToBeneficiary: "0x0000000000000000000000000000000000000000",
  defaultScaledOfferFactorPercent: 1,
  scaledOfferFactorOverrides: [
    {
      baseToken: "0x0000000000000000000000000000000000000000",
      quoteToken: "0x0000000000000000000000000000000000000000",
      scaledOfferFactorPercent: 0.1,
    }
  ],
  owner: "0x442C01498ED8205bFD9aaB6B8cc5C810Ed070C8f",
  oracleParams: {
    address: "0x8E0E20Ea43A88214A0908F32Cd14395022e823A6",
  },
}
 
const gasEstimate = await swapperClient.estimateGas.createSwapper(args)

CallData

The client has a call data feature that can be used with any of the above write functions. Just call the function off of the callData property. Generating call data for the create swapper function would look like:

const args = {
  beneficiary: "0x442C01498ED8205bFD9aaB6B8cc5C810Ed070C8f",
  tokenToBeneficiary: "0x0000000000000000000000000000000000000000",
  defaultScaledOfferFactorPercent: 1,
  scaledOfferFactorOverrides: [
    {
      baseToken: "0x0000000000000000000000000000000000000000",
      quoteToken: "0x0000000000000000000000000000000000000000",
      scaledOfferFactorPercent: 0.1,
    }
  ],
  owner: "0x442C01498ED8205bFD9aaB6B8cc5C810Ed070C8f",
  oracleParams: {
    address: "0x8E0E20Ea43A88214A0908F32Cd14395022e823A6",
  },
}
 
const callData = await swapperClient.callData.createSwapper(args)

Swapper Reads

These functions make it easier to query the Swapper contracts.

getBeneficiary

Returns the beneficiary for a given swapperAddress.

Usage

const args = {
  swapperAddress: '0x693C49a6296d90e8A8936Ad4836a680F551bb97d',
}
 
const response = await swapperClient.getBeneficiary(args)

Arguments

{
  swapperAddress: string
}

Response

{
  beneficiary: string
}

getTokenToBeneficiary

Returns the token to beneficiary for a given swapperAddress.

Usage

const args = {
  swapperAddress: '0x693C49a6296d90e8A8936Ad4836a680F551bb97d',
}
 
const response = await swapperClient.getTokenToBeneficiary(args)

Arguments

{
  swapperAddress: string
}

Response

{
  tokenToBeneficiary: string
}

getOracle

Returns the oracle for a given swapperAddress.

Usage

const args = {
  swapperAddress: '0x693C49a6296d90e8A8936Ad4836a680F551bb97d',
}
 
const response = await swapperClient.getOracle(args)

Arguments

{
  swapperAddress: string
}

Response

{
  oracle: string
}

getDefaultScaledOfferFactor

Returns the default scaled offer factor for a given swapperAddress.

Usage

const args = {
  swapperAddress: '0x693C49a6296d90e8A8936Ad4836a680F551bb97d',
}
 
const response = await swapperClient.getDefaultScaledOfferFactor(args)

Arguments

{
  swapperAddress: string
}

Response

{
  defaultScaledOfferFactor: number
}
WaterfallLiquid Splits