💻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