💻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
chainId*	integer	Currently, we support Fantom ( 250) The list with expand as usage increase
from*	string	ERC20 token contract address to sell
to*	string	ERC20 token contract address to buy
amount*	integer	buy amount of ERC20 tokens in wei
slippage	float	Default = 0.005 (equal 0.5%)
deadline	integer	Unix timestamp, transaction will fail if it's not executed before this deadline
receiver	string	Destination receiver wallet address !Important: it's allowed to be empty for quote-query only Receiver can't be empty if you intent to use encoded data to perform swap
source*	string	Referrer , this is to attribute volume to traffic source. We use this info to build up referral program at later stages.

Response sample:

200: ok

{
  "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:

200: ok

{
  "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

Field	Sub field	Type	Description
encodedData		json object
	router	string	MicroSwap Router smart contract address The address is returned here because it's frequently updated
	data	string	Data encoded for given quote. Client just need to submit this data to given provided contract address returned at "router"
maxReturn		json object
	from	string	ERC20 token contract address to sell
	to	string	ERC20 token contract address to buy
	totalFrom	string	buy amount of ERC20 tokens in wei
	totalTo	numeric string	best sell amount of ERC20 tokens in wei
	totalGas	number
	gasPrice	numeric string
	paths	array of object	swap paths, for display purpose

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'
})