Skip to content

Swap API Documentation

Overview

The Swap API provides functionality to generate swap call data necessary for executing a swap transaction. The sushi package also exposes a wrapper function for this API called getSwap, available under the sushi/evm export.

Example

import { createPublicClient, createWalletClient, http, type Hex } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { mainnet } from 'viem/chains'
import { type SwapResponse } from 'sushi/evm'
 
const publicClient = createPublicClient({
  chain: mainnet,
  transport: http(),
})
 
const chainId = 1
 
const SWAP_API_URL = new URL('https://api.sushi.com/swap/v7/' + chainId)
 
// TokenA & TokenB
const inputCurrency = '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'
const outputCurrency = '0x6B3595068778DD592e39A122f4f5a5cF09C90fE2'
 
// Amount
const amount = 1000000000000000
 
// Max Slippage
const maxSlippage = 0.005
 
// Sender
const sender = '0x' // replace with your own address
 
// Api Key, get yours at https://sushi.com/portal
// const apiKey = "sushi_abcdefghijklmnopqr"
 
const { searchParams } = SWAP_API_URL
searchParams.set('tokenIn', inputCurrency)
searchParams.set('tokenOut', outputCurrency)
searchParams.set('amount', amount.toString())
searchParams.set('maxSlippage', maxSlippage.toString())
searchParams.set('sender', sender)
// searchParams.set('apiKey', apiKey)
 
// Make call to API
console.log(SWAP_API_URL.toString())
const res = await fetch(SWAP_API_URL.toString())
const data = await res.json() as SwapResponse
console.log(data)
 
// If the swap status is 'Success'
if (data.status === 'Success') {
  const { tx } = data
  // Simulate a call to the blockchain for the swap
  const callResult = await publicClient.call({
    account: tx.from,
    data: tx.data,
    to: tx.to,
    value: tx.value,
  })
  // Returns the simulated amount out
  console.log('Output: ', callResult)
 
  // Send a transaction
  const PRIVATE_KEY = process.env.PRIVATE_KEY as Hex
  const walletClient = createWalletClient({
    chain: mainnet,
    transport: http(),
  })
  const hash = await walletClient.sendTransaction({ 
    account: privateKeyToAccount(PRIVATE_KEY),
    data: tx.data,
    to: tx.to,
    value: tx.value,
  })
  console.log('Tx: ', hash)
}

Response

The endpoint returns a SwapResponse, which includes the route status and, on success, the prepared transaction to execute the swap.

  • Status: one of Success, Partial, or NoWay.
  • Tokens: array of involved tokens with address, decimals, symbol, and name.
  • Token indexes: tokenFrom and tokenTo are indexes into tokens and are also expanded to the full token objects in the response.
  • Pricing: swapPrice (price tokenIn → tokenOut) and priceImpact (as a fraction, e.g. 0.005 for 0.5%).
  • Amounts: amountIn and assumedAmountOut as stringified integers in token base units.
  • Transaction: tx with from, to, gasPrice (number), data (hex), and value (stringified integer, may be omitted or "0" for ERC-20 → ERC-20). When simulate=true is passed, tx.gas is also included as a string.

Example (Success):

{
  "status": "Success",
  "tokens": [
    {
      "address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
      "decimals": 18,
      "symbol": "ETH",
      "name": "Ether"
    },
    {
      "address": "0x6b3595068778dd592e39a122f4f5a5cf09c90fe2",
      "decimals": 18,
      "symbol": "SUSHI",
      "name": "SushiToken"
    }
  ],
  "tokenFrom": 0,
  "tokenTo": 1,
  "swapPrice": 2300.12,
  "priceImpact": 0.0012,
  "amountIn": "1000000000000000",
  "assumedAmountOut": "1234567890000000000",
  "tx": {
    "from": "0x0000000000000000000000000000000000000000",
    "to": "0x0000000000000000000000000000000000000000",
    "gasPrice": 1000000000,
    "data": "0x…",
    "value": "1000000000000000"
    // when simulate=true, a string field "gas" is also included
  }
}

If status is NoWay, only the status field is returned, indicating that no route satisfying the constraints was found. Partial indicates a route is available but cannot fully satisfy the requested amount under the given constraints.

Errors are returned with RFC 7807 problem details; see API error references under Errors.