# 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](/sdk/guides/swap) a wrapper function for this API called `getSwap`, available under the `sushi/evm` export.

## Example

```ts twoslash
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 = '0x...' 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):

```json
{
  "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](/api/errors).