MicroSwap API Specification

Step 1: Query Swap Route

Basic GET API:

https://api.microswap.org/aggregator/v2/quote?chainId=250&from=?&to=&receiver=&source=

Curl sample

curl --location --request GET ‘https://api.microswap.org/aggregator/v2/quote?chainId=250&from=0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee&amount=1000000000000000000&slippage=0.003&to=0x28a92dde19d9989f39a49905d7c9c2fac7799bdf&source=microswap&receiver=0x19369328B9d837F5E5248FaE4c30b9a6A5C18a7C’

Request query parameters

GET URL: https://api.microswap.org/aggregator/v2/quote

Query Parameters

Name

Type

Description

Response sample:

{
  "chainId": 250,
  "from": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
  "to": "0x28a92dde19d9989f39a49905d7c9c2fac7799bdf",
  "amount": "1000000000000000000",
  "slippage": 0.003,
  "deadline": 0,
  "dexes": "",
  "excludedDexes": "hashflow",
  "receiver": "0x19369328B9d837F5E5248FaE4c30b9a6A5C18a7C",
  "source": "microswap",
  "hash": "AYQQl8sIYFdR87YvikXDwei7jXQupd0mMyhqY5Uc6a0=",
  "quoteData": {
    "maxReturn": {
      "from": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
      "to": "0x28a92dde19d9989f39a49905d7c9c2fac7799bdf",
      "totalFrom": "1000000000000000000",
      "totalTo": "682199",
      "totalGas": 341000,
      "gasPrice": "17422876294",
      "paths": [
        {
          "amountFrom": "999500000000000000",
          "amountTo": "682199",
          "gas": 216000,
          "swaps": [
            {
              "from": "0x21be370d5312f44cb42ce377bc9b8a0cef1a4c83",
              "to": "0x82f0b8b456c1a451378467398982d4834b6829c1",
              "amountFrom": "999500000000000000",
              "amountTo": "687920673532895045",
              "pool": "0xa7c86fc1b87830b8abfa623571405e03560a8326",
              "swapFee": 0.005,
              "dex": "tombswap"
            },
            {
              "from": "0x82f0b8b456c1a451378467398982d4834b6829c1",
              "to": "0x1b6382dbdea11d97f24495c9a90b7c88469134a4",
              "amountFrom": "687920673532895045",
              "amountTo": "681850",
              "pool": "0x327a8676af1bd079031a46fc2b594a238660bf55",
              "swapFee": 0.0003,
              "dex": "equalizer"
            },
            {
              "from": "0x1b6382dbdea11d97f24495c9a90b7c88469134a4",
              "to": "0x28a92dde19d9989f39a49905d7c9c2fac7799bdf",
              "amountFrom": "681850",
              "amountTo": "682199",
              "pool": "0xdb0f33978b5366191c42bb9a7b7d886cb714df65",
              "swapFee": 0.0003,
              "dex": "velocimeter"
            }
          ]
        }
      ],
      "tokens": {
        "0x1b6382dbdea11d97f24495c9a90b7c88469134a4": {
          "address": "0x1b6382dbdea11d97f24495c9a90b7c88469134a4",
          "symbol": "axlUSDC",
          "name": "Axelar Wrapped USDC",
          "decimals": 6,
          "price": 1.0005309029879415
        },
        "0x21be370d5312f44cb42ce377bc9b8a0cef1a4c83": {
          "address": "0x21be370d5312f44cb42ce377bc9b8a0cef1a4c83",
          "symbol": "FTM",
          "name": "Wrapped Fantom",
          "decimals": 18,
          "price": 0.676683782068614
        },
        "0x28a92dde19d9989f39a49905d7c9c2fac7799bdf": {
          "address": "0x28a92dde19d9989f39a49905d7c9c2fac7799bdf",
          "symbol": "USDC",
          "name": "LayerZero USD Coin",
          "decimals": 6,
          "price": 1
        },
        "0x82f0b8b456c1a451378467398982d4834b6829c1": {
          "address": "0x82f0b8b456c1a451378467398982d4834b6829c1",
          "symbol": "MIM",
          "name": "Magic Internet Money",
          "decimals": 18,
          "price": 0.9883771772891552
        }
      }
    },
    "encodedData": {}
  }
}

Step 2: Encode Preferred Swap Route

Basic API:

POST URL: https://api.microswap.org/aggregator/v2/quote

Param sample:

{
  "chainId": 250,
  "from": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
  "to": "0x28a92dde19d9989f39a49905d7c9c2fac7799bdf",
  "amount": "1000000000000000000",
  "slippage": 0.003,
  "deadline": 0,
  "excludedDexes": "hashflow",
  "receiver": "0x7c841c5e304aed36339f54b54edc04f89ef4ab0f",
  "source": "microswap",
  "hash": "T17x8zPchSRDf9JfVQ49Sk5l5I+calZCbZXJZS2nwHM=",
  "quoteData": {
    "maxReturn": {
      "from": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
      "to": "0x28a92dde19d9989f39a49905d7c9c2fac7799bdf",
      "totalFrom": "1000000000000000000",
      "totalTo": "680752",
      "totalGas": 383000,
      "gasPrice": "17086951841",
      "paths": [
        {
          "amountFrom": "999500000000000000",
          "amountTo": "680752",
          "gas": 258000,
          "swaps": [
            {
              "from": "0x21be370d5312f44cb42ce377bc9b8a0cef1a4c83",
              "to": "0x82f0b8b456c1a451378467398982d4834b6829c1",
              "amountFrom": "999500000000000000",
              "amountTo": "686713816143087027",
              "pool": "0xa7c86fc1b87830b8abfa623571405e03560a8326",
              "swapFee": 0.005,
              "dex": "tombswap"
            },
            {
              "from": "0x82f0b8b456c1a451378467398982d4834b6829c1",
              "to": "0x1b6382dbdea11d97f24495c9a90b7c88469134a4",
              "amountFrom": "686713816143087027",
              "amountTo": "680406",
              "pool": "0x327a8676af1bd079031a46fc2b594a238660bf55",
              "swapFee": 0.0003,
              "dex": "equalizer"
            },
            {
              "from": "0x1b6382dbdea11d97f24495c9a90b7c88469134a4",
              "to": "0x28a92dde19d9989f39a49905d7c9c2fac7799bdf",
              "amountFrom": "680406",
              "amountTo": "680752",
              "pool": "0x121ce0321de5e245fc49efdbb6444bcb4b42fc6f",
              "dex": "e3dex",
              "meta": {
                "version": 1
              }
            }
          ]
        }
      ],
      "tokens": {
        "0x1b6382dbdea11d97f24495c9a90b7c88469134a4": {
          "address": "0x1b6382dbdea11d97f24495c9a90b7c88469134a4",
          "symbol": "axlUSDC",
          "name": "Axelar Wrapped USDC",
          "decimals": 6,
          "price": 0.9986927193173001
        },
        "0x21be370d5312f44cb42ce377bc9b8a0cef1a4c83": {
          "address": "0x21be370d5312f44cb42ce377bc9b8a0cef1a4c83",
          "symbol": "FTM",
          "name": "Wrapped Fantom",
          "decimals": 18,
          "price": 0.67970138892444
        },
        "0x28a92dde19d9989f39a49905d7c9c2fac7799bdf": {
          "address": "0x28a92dde19d9989f39a49905d7c9c2fac7799bdf",
          "symbol": "USDC",
          "name": "LayerZero USD Coin",
          "decimals": 6,
          "price": 1
        },
        "0x82f0b8b456c1a451378467398982d4834b6829c1": {
          "address": "0x82f0b8b456c1a451378467398982d4834b6829c1",
          "symbol": "MIM",
          "name": "Magic Internet Money",
          "decimals": 18,
          "price": 0.9910073135236579
        }
      }
    },
    "encodedData": {}
  }
}

Response sample:

{
  "maxReturn": {
    "from": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
    "to": "0x28a92dde19d9989f39a49905d7c9c2fac7799bdf",
    "totalFrom": "1000000000000000000",
    "totalTo": "680752",
    "totalGas": 383000,
    "gasPrice": "17086951841",
    "paths": [
      {
        "amountFrom": "999500000000000000",
        "amountTo": "680752",
        "gas": 258000,
        "swaps": [
          {
            "from": "0x21be370d5312f44cb42ce377bc9b8a0cef1a4c83",
            "to": "0x82f0b8b456c1a451378467398982d4834b6829c1",
            "amountFrom": "999500000000000000",
            "amountTo": "686713816143087027",
            "pool": "0xa7c86fc1b87830b8abfa623571405e03560a8326",
            "swapFee": 0.005,
            "dex": "tombswap"
          },
          {
            "from": "0x82f0b8b456c1a451378467398982d4834b6829c1",
            "to": "0x1b6382dbdea11d97f24495c9a90b7c88469134a4",
            "amountFrom": "686713816143087027",
            "amountTo": "680406",
            "pool": "0x327a8676af1bd079031a46fc2b594a238660bf55",
            "swapFee": 0.0003,
            "dex": "equalizer"
          },
          {
            "from": "0x1b6382dbdea11d97f24495c9a90b7c88469134a4",
            "to": "0x28a92dde19d9989f39a49905d7c9c2fac7799bdf",
            "amountFrom": "680406",
            "amountTo": "680752",
            "pool": "0x121ce0321de5e245fc49efdbb6444bcb4b42fc6f",
            "dex": "e3dex",
            "meta": {
              "version": 1
            }
          }
        ]
      }
    ],
    "tokens": {
      "0x1b6382dbdea11d97f24495c9a90b7c88469134a4": {
        "address": "0x1b6382dbdea11d97f24495c9a90b7c88469134a4",
        "symbol": "axlUSDC",
        "name": "Axelar Wrapped USDC",
        "decimals": 6,
        "price": 0.9986927193173001
      },
      "0x21be370d5312f44cb42ce377bc9b8a0cef1a4c83": {
        "address": "0x21be370d5312f44cb42ce377bc9b8a0cef1a4c83",
        "symbol": "FTM",
        "name": "Wrapped Fantom",
        "decimals": 18,
        "price": 0.67970138892444
      },
      "0x28a92dde19d9989f39a49905d7c9c2fac7799bdf": {
        "address": "0x28a92dde19d9989f39a49905d7c9c2fac7799bdf",
        "symbol": "USDC",
        "name": "LayerZero USD Coin",
        "decimals": 6,
        "price": 1
      },
      "0x82f0b8b456c1a451378467398982d4834b6829c1": {
        "address": "0x82f0b8b456c1a451378467398982d4834b6829c1",
        "symbol": "MIM",
        "name": "Magic Internet Money",
        "decimals": 18,
        "price": 0.9910073135236579
      }
    }
  },
  "encodedData": {
    "router": "0xc9147959bab2ceeac49692e03f8b132fdd62196c",
    "data": "0x7c025200000000000000000000000000def68e73155e706b0ad34d6875abdf4c207446e700000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000000180000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee00000000000000000000000028a92dde19d9989f39a49905d7c9c2fac7799bdf000000000000000000000000def68e73155e706b0ad34d6875abdf4c207446e70000000000000000000000007c841c5e304aed36339f54b54edc04f89ef4ab0f0000000000000000000000000000000000000000000000000de0b6b3a764000000000000000000000000000000000000000000000000000000000000000a5b36000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000056000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000120000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee00000000000000000000000028a92dde19d9989f39a49905d7c9c2fac7799bdf00000000000000000000000000000000000000000000000000000000000a5b360000000000000000000000000000000000000000000000000000000000000004ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff0000000000000000000000007c841c5e304aed36339f54b54edc04f89ef4ab0f00000000000000000000000000000000000000000000000000000000661f4fd100000000000000000000000000000000000000000000000000000000000005000000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000030000000000000000000000000000000000000000000000000000000000000060000000000000000000000000000000000000000000000000000000000000016000000000000000000000000000000000000000000000000000000000000002600000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000003200000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000a7c86fc1b87830b8abfa623571405e03560a832600000000000000000000000021be370d5312f44cb42ce377bc9b8a0cef1a4c8300000000000000000000000082f0b8b456c1a451378467398982d4834b6829c10000000000000000000000000000000000000000000000000ddeeff45500c00000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000090000000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000327a8676af1bd079031a46fc2b594a238660bf5500000000000000000000000082f0b8b456c1a451378467398982d4834b6829c10000000000000000000000001b6382dbdea11d97f24495c9a90b7c88469134a40000000000000000000000000000000000000000000000000987b293d18fc5b300000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000180000000000000000000000000000000000000000000000000000000000000000c0000000000000000000000000121ce0321de5e245fc49efdbb6444bcb4b42fc6f0000000000000000000000001b6382dbdea11d97f24495c9a90b7c88469134a400000000000000000000000028a92dde19d9989f39a49905d7c9c2fac7799bdf00000000000000000000000000000000000000000000000000000000000a61d60000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000167b22736f75726365223a226d6963726f73776170227d00000000000000000000"
  }
}

Response payload

Step 3: Execute Swap Transaction On-Chain

Integration example:

const Web3 = require('web3')
const axios = require('axios')


const { BN } = Web3.utils
const MAX_UINT = '115792089237316195423570985008687907853269984665640564039457584007913129639935'


const PRIVATE_KEY = '' // TODO: config your private key
const ROUTER_API = 'https://api.microswap.org/aggregator/v2/encode'
const RPC_URL = 'https://rpc.ftm.tools/'


const ERC20_ABI = [
 {
   "constant": true,
   "inputs": [{ "name": "_owner", "type": "address" }, { "name": "_spender", "type": "address" }],
   "name": "allowance",
   "outputs": [{ "name": "remaining", "type": "uint256" }],
   "payable": false,
   "stateMutability": "view",
   "type": "function"
 },
 {
   "constant": false,
   "inputs": [{ "name": "_spender", "type": "address" }, { "name": "_value", "type": "uint256" }],
   "name": "approve",
   "outputs": [],
   "payable": false,
   "stateMutability": "nonpayable",
   "type": "function"
 }
]


const web3 = new Web3(new Web3.providers.HttpProvider(RPC_URL))


// PRIVATE_KEY variable defined
const account = web3.eth.accounts.privateKeyToAccount(PRIVATE_KEY)


function sendTransaction(tx) {
 const signPromise = web3.eth.accounts.signTransaction(tx, PRIVATE_KEY)
 return new Promise((resolve, reject) => {
   signPromise.then((signedTx) => {
     // raw transaction string may be available in .raw or
     // .rawTransaction depending on which signTransaction
     // function was called
     const sentTx = web3.eth.sendSignedTransaction(signedTx.raw || signedTx.rawTransaction)
     sentTx.on("receipt", receipt => {
       // do something when receipt comes back
       resolve(receipt)
     })
     sentTx.on("error", err => {
       // do something on transaction error
       reject(err)
     })
   }).catch((err) => {
     // do something when promise fails
     reject(err)
   })
 })
}


async function swap(params) {
 // fetch encoded swap transaction data
 const { data: { encodedData } } = await axios.get(ROUTER_API, {
   headers: { 'Content-Type': 'application/json' },
   params
 })


 const tokenIn = params.from
 const routerContract = encodedData.router // router contract address
 const currencyAIsEth = tokenIn.toLowerCase() === '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee'
 const amountIn = params.amount


 if (!currencyAIsEth) {
   // check approval
   const contract = new web3.eth.Contract(ERC20_ABI, tokenIn, {
     from: account.address
   })
   const allowance = await contract.methods.allowance(account.address, routerContract).call()
   if (new BN(allowance).lt(new BN(amountIn))) {
     console.log('# APPROVING...')
     const approvalData = contract.methods.approve(routerContract, MAX_UINT).encodeABI()
     const tx = {
       from: account.address,
       to: tokenIn,
       gas: '1000000',
       data: approvalData,
     }
     const approvalReceipt = await sendTransaction(tx, PRIVATE_KEY).catch()
     console.log('# APPROVED TXN:', approvalReceipt.transactionHash)
   }
 }


 const tx = {
   from: account.address, // signer address
   to: routerContract,
   gas: '1000000',
   data: encodedData.data, // encoded contract data
   value: currencyAIsEth ? amountIn : undefined,
 }


 console.log('# SWAPPING...')
 sendTransaction(tx)
   .then((receipt) => {
     console.log('# SWAP SUCCESSFULLY:')
     // do something when receipt comes back
     console.log(receipt)
   })
   .catch((err) => {
     console.log('# SWAP FAILED:')
     // do something on transaction error
     console.error(err)
   })
}


// swap USDC to FTM
swap({
 chainId: 250,
 from: '0x28a92dde19d9989f39a49905d7c9c2fac7799bdf',
 to: '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee',
 amount: '1000000',
 receiver: account.address,
 source: 'sample'
})