Quote v1 API (Deprecated)

️🚫

Quote v1 API has been deprecated and will be removed in the future. Please use Quote v2 API instead.

Quote API computes the best path to swap tokens at the best rate using our Navigator.

With a straightforward API call, you can get the transaction data that will execute the swap without hassle.

💡

Quote API requires authentication.

Changes since `v0`

skipGasEstimation field has been added.

Endpoint

https://api.swapscanner.io/v1/quote

Request Message Schema

{
  "domain": {
    "name": "Swapscanner Navigator",
    "version": "v1",
    "chainId": "8217",
    "verifyingContract": "0x8888888888888888888888888888888888888888",
    "salt": "0xYourSaltHere"
  },
  "primaryType": "QuoteRequestV1",
  "types": {
    "EIP712Domain": [
      { "name": "name", "type": "string" },
      { "name": "version", "type": "string" },
      { "name": "chainId", "type": "uint256" },
      { "name": "verifyingContract", "type": "address" },
      { "name": "salt", "type": "bytes32" }
    ],
    "QuoteRequestV1": [
      { "name": "issuedAt", "type": "uint256" },
      { "name": "from", "type": "address" },
      { "name": "tokenInAddress", "type": "address" },
      { "name": "tokenOutAddress", "type": "address" },
      { "name": "amount", "type": "uint256" },
      { "name": "slippageNumerator", "type": "uint256" },
      { "name": "slippageDenominator", "type": "uint256" },
      { "name": "mode", "type": "string" },
      { "name": "skipGasEstimation", "type": "bool" }
    ]
  }
}

💡

Every address must be lowercased, without the checksum.

issuedAt - UNIX timestamp (in seconds) when you issued the request. issuedAt and salt will together work as a countermeasure for replay attacks.

Your computer and the Swapscanner API server could be a clock difference, resulting in the message expiring earlier than expected. In such case, try subtracting 1~2 seconds from your current timestamp. However, do not subtract too much since we have TTL.
from - The address of the wallet (or contract) that would like to perform a swap. Token tokenInAddress will be transferred from this address.
tokenInAddress - Address of the token that the from wallet would like to provide.
tokenOutAddress - Address of the token that the from wallet would like to receive.
amount - amount of tokenInAddress that the from wallet would like to provide. Must be numerated with the decimals of the tokenInAddress. (e.g. 1 KAIA = 1000000000000000000)
slippageNumerator - the numerator of the slippage that the from wallet would like to allow. (e.g. for slippage allowance of 1%, set slippageNumerator to 10, and slippageDenominator to 1000)
slippageDenominator - denominator of the slippage allowance.
mode - Algorithm to be used for this quote request. Possible values are:
- gasEfficient: maximize return while taking the gas cost into consideration. (highly recommended)
- maxReturn: maximize return (ignore gas cost).
skipGasEstimation - If true, the gas will not be estimated. This will result in a faster response time, but the gas will not be included in response.quote.tx*. Setting this to true requires you to manually estimate gas before executing the transaction, and add it to the tx object (or set it to big enough number).

⚠️
Setting skipGasEstimation to true will make all the estimated gas related fields from the respone highly inaccurate. Also we are not able to guarantee if the transaction will go through without getting reverted. Use it at your own risk.

Example Message

{
  issuedAt: Math.floor(Date.now() / 1000),
  from: '0x4236[REDACTED]57a9'.toLowerCase(),
  tokenInAddress: '0x754288077d0ff82af7a5317c7cb8c444d421d103'.toLowerCase(),
  tokenOutAddress: '0x0000000000000000000000000000000000000000'.toLowerCase(),
  amount: '1000000',
  slippageNumerator: '1',
  slippageDenominator: '100',
  mode: 'gasEfficient',
  skipGasEstimation: false,
}

Response Codes

200: OK
400: Bad Request
- used_salt: the salt given is already used once and not fresh anymore.
- bad_signature: signature is invalid and Swapscanner API was unable to recover signer address.
- bttf: acronym of “Back to the Future”. Happens when the issuedAt is greater than the current server timestamp.
- signature_expired: the request was generated too long ago.
403: Forbidden
- bad_referrer: the referrer address is not authorized.
- invalid_signature: the referrer address does not match with the recovered one.
429: Too Many Requests
- rate_limited: the request is rejected due to rate limiting.
503: Service Unavailable
- quote_under_maintenance: system is under the maintenance mode and will be back online shortly.

Response Body

{
  // tokenInAddress: the actual input token address. (replay from the request)
  "tokenInAddress": "0x0000000000000000000000000000000000000000",

  // tokenInBalance: balance of the input token of the given `from` account.
  "tokenInBalance": "397728315733417638919",

  // tokenOutBalance: balance of the output token of the given `from` account.
  "tokenOutBalance": "90930302878",

  // tokenInAmount: the amount of the input token that the `from` account would like
  // to provide.
  "tokenInAmount": "100000000000000000000",

  // tokenOutAddress: the actual output token address. (replay from the request)
  "tokenOutAddress": "0x754288077d0ff82af7a5317c7cb8c444d421d103",

  // quote: the best quote that the Swapscanner Navigator found.
  "quote": {
    // id: unique ID
    "id": "93131e60-9570-51ed-ae60-542cb88eab26",

    // priceImpact: the price impact of the quote. (in percentage)
    "priceImpact": 0,

    // amountInUSDC: the USDC estimated value of the `tokenInAmount`.
    "amountInUSDC": 23.072421628033496,

    // minAmountOut: the minimum amount of the output token that the `from` account will be
    // receiving while taking the slippage into account.
    // (expected amount - slippage tolerance)
    "minAmountOut": "23048141",

    // minAmountOutUSDC: the USDC estimated value of the `minAmountOut`.
    "minAmountOutUSDC": 23.048141,

    // estimatedAmountOut: the estimated amount of the output token that the `from` account
    // will be receiving while ignoring the slippage. (Swapscanner fee is also not deducted)
    "estimatedAmountOut": "23076974",

    // estimatedAmountOutUSDC: the USDC estimated value of the `estimatedAmountOut`.
    "estimatedAmountOutUSDC": 23.076974,

    // gasIncludedAmountOutUSDC: the USDC estimated value of the `estimatedAmountOut` with
    // the gas cost deducted.
    "gasIncludedAmountOutUSDC": 22.990178,

    // estimatedGas: the estimated gas cost of the transaction. (in KAIA peb)
    // WARN: this could be **highly** inaccurate if the `skipGasEstimation` is set to `true`.
    "estimatedGas": 406581000000000000,

    // estimatedGasUSDC: the USDC estimated value of the `estimatedGas`.
    // WARN: this could be **highly** inaccurate if the `skipGasEstimation` is set to `true`.
    "estimatedGasUSDC": 0.09380808257947487,

    // swapscannerFee: the Swapscanner fee that will be deducted from the
    // `estimatedAmountOut`.
    "swapscannerFee": "5756",

    // swapscannerFeeUSDC: the USDC estimated value of the `swapscannerFee`.
    "swapscannerFeeUSDC": 0.005756,

    // tx: the transaction data to be used to execute the transaction. (for Metamask-like
    // `web3` standard wallets)
    "tx"?: {
      // from: the account that will be sending the transaction.
      "from": "0x8639[REDACTED]c3db",

      // to: the contract address of the Swapscanner NAEP.
      "to": "0xf50782a24afcb26acb85d086cf892bfffb5731b5",

      // data: the data containing swap route information and so on.
      "data": "0x000000000000000000000000000000000000000000000000000000000000000000000000...",

      // value: `tokenInAmount` if the `tokenInAddress` is KAIA, otherwise should be 0.
      "value": "0x56bc75e2d63100000",

      "type": "0x2",
      "maxPriorityFeePerGas": "0x3a35294400",
      "maxFeePerGas": "0x3a35294400",

      // gas will be `undefined` if the `skipGasEstimation` is set to `true`.
      "gas"?: "0x18d0d4"
    },

    // txKlay: same as above, but to be used with Kaia standard wallets like Kaikas.)
    "txKlay"?: {
      "from": "0x8639[REDACTED]c3db",
      "to": "0xf50782a24afcb26acb85d086cf892bfffb5731b5",
      "data": "0x000000000000000000000000000000000000000000000000000000000000000000004000...",
      "value": "0x56bc75e2d63100000",
      "type": "SMART_CONTRACT_EXECUTION",
      "gasPrice": "0x3a35294400",

      // gas will be `undefined` if the `skipGasEstimation` is set to `true`.
      "gas"?: "0x18d0d4"
    },

    // txKlip: same as above, but to be used with Klip API.
    "txKlip"?: {
      "bappName": "Swapscanner",
      "to": "0xf50782a24afcb26acb85d086cf892bfffb5731b5",
      "value": "100000000000000000000",
      "abi": "{\"inputs\":[{\"internalType\":\"bytes\",\"name\":\"\",\"type\":\"bytes\"},...",
      "params": "[\"0x0000000000000000000000000000000000000000000000000000000000000020000...",
      "from": "0x8639[REDACTED]c3db"
    },

    // txError?: this indicates that the transaction data could not be generated or validated.
    // This is an optional field and may not be present if the transaction data is valid.
    // - insufficnent_balance: the `from` account does not have enough balance.
    // - gas_estimation      : the transaction is going to be reverted. This could raise very
    //                         rarely when the market situation drastically changed after the
    //                         quote was generated.
    // - empty_from          : the `from` address is empty.
    "txError"?: "",

    // txType: the type of the `tx`.
    // - approve: when approval is required, and the given `tx` is an approval transaction.
    // - swap: when the given `tx` is a swap transaction.
    "txType": "swap",

    // type: this must always be a `swapscanner`, and the best quote is always from us,
    // guaranteed.
    "type": "swapscanner",

    // paths: the paths that the Swapscanner Navigator found.
    "paths": [
      {
        // the initial token in the path was KAIA (0x000000...).
        "path": [
          // and then NAEP will swap this with 0xcee8faf64bb97a73bb51e115aa89c17ffa8dd167 on
          // KokonutSwap DEX. The `fraction: 1` means that 100% of the `tokenInAmount` will be
          // go through this path.
          {
            "token": "0xcee8faf64bb97a73bb51e115aa89c17ffa8dd167",
            "subPaths": [
              {
                "exchange": "KokonutSwap",
                "fraction": 1
              }
            ]
          },
          // this will then swapped to 0x0000000000000000000000000000000000000000 (KAIA)
          // through Pala DEX.
          {
            "token": "0x0000000000000000000000000000000000000000",
            "subPaths": [
              {
                "exchange": "Pala",
                "fraction": 1
              }
            ]
          },
          // this will then swapped to 0xcee8faf64bb97a73bb51e115aa89c17ffa8dd167 (KAIA)
          // through KLAYswap DEX.
          {
            "token": "0xcee8faf64bb97a73bb51e115aa89c17ffa8dd167",
            "subPaths": [
              {
                "exchange": "KLAYswap",
                "fraction": 1
              }
            ]
          },
          // and finally, this will be swapped to 0x754288077d0ff82af7a5317c7cb8c444d421d103
          // through Pala DEX.
          {
            "token": "0x754288077d0ff82af7a5317c7cb8c444d421d103",
            "subPaths": [
              {
                "exchange": "Pala",
                "fraction": 1
              }
            ]
          }
        ]
      }
    ]
  },

  // quotes: the quotes from other DEXes (single DEX used).
  "quotes": [
    {
      "id": "ed2ccbf3-bda7-5b5c-927e-f3f906125520",
      "priceImpact": 0.002307240604896711,
      "amountInUSDC": 23.072421628033496,
      "minAmountOut": "22996168",
      "minAmountOutUSDC": 22.996168,
      "estimatedAmountOut": "23019188",
      "estimatedAmountOutUSDC": 23.019188,
      "gasIncludedAmountOutUSDC": 22.970989,
      "estimatedGas": "209383500000000000",
      "estimatedGasUSDC": 0.04830984393953351,
      "type": "single_exchange",
      "exchange": "KokonutSwap"
    },
    {
      "id": "8859286f-f954-56e3-a513-8f479150bfde",
      "priceImpact": 0.004574276152498207,
      "amountInUSDC": 23.072421628033496,
      "minAmountOut": "22943915",
      "minAmountOutUSDC": 22.943915,
      "estimatedAmountOut": "22966882",
      "estimatedAmountOutUSDC": 22.966882,
      "gasIncludedAmountOutUSDC": 22.951945,
      "estimatedGas": "65038500000000000",
      "estimatedGasUSDC": 0.015005956940548565,
      "type": "single_exchange",
      "exchange": "KLAYswap"
    },
    {
      "id": "c8abdcdc-c0f0-5a9a-8a23-28e40d45eeb6",
      "priceImpact": 0.00715103211502627,
      "amountInUSDC": 23.072421628033496,
      "minAmountOut": "22884522",
      "minAmountOutUSDC": 22.884522,
      "estimatedAmountOut": "22907430",
      "estimatedAmountOutUSDC": 22.90743,
      "gasIncludedAmountOutUSDC": 22.893349,
      "estimatedGas": "61469750000000000",
      "estimatedGasUSDC": 0.01418255989369812,
      "type": "single_exchange",
      "exchange": "Pala"
    },
    {
      "id": "a14f20d9-8394-5f4a-9563-a5dfeeb740e2",
      "priceImpact": 0.010332275990650517,
      "amountInUSDC": 23.072421628033496,
      "minAmountOut": "22811196",
      "minAmountOutUSDC": 22.811196,
      "estimatedAmountOut": "22834031",
      "estimatedAmountOutUSDC": 22.834031,
      "gasIncludedAmountOutUSDC": 22.770238,
      "estimatedGas": "279374000000000000",
      "estimatedGasUSDC": 0.0644583471991023,
      "type": "single_exchange",
      "exchange": "ClaimSwap"
    },
    {
      "id": "472abd61-bae5-5e80-a057-7ef444d06c67",
      "priceImpact": 0.013002606872829807,
      "amountInUSDC": 23.072421628033496,
      "minAmountOut": "22749647",
      "minAmountOutUSDC": 22.749647,
      "estimatedAmountOut": "22772420",
      "estimatedAmountOutUSDC": 22.77242,
      "gasIncludedAmountOutUSDC": 22.758672,
      "estimatedGas": "60374500000000000",
      "estimatedGasUSDC": 0.013929859195817082,
      "type": "single_exchange",
      "exchange": "UFOswap"
    }
  ]
}

Quote v1 API (Deprecated)

Changes since v0#

Endpoint#

Request Message Schema#

Example Message#

Response Codes#