💻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:

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

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

Last updated