💻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