🧑‍💻API Specification

We do not offer API key to individual users at this time, if you are a project please contact mobbie#3450 on Discord

Parameters, input/output format

Basic GET API: https://router.firebird.finance/aggregator/v1/route?chainId=250&from=?&to=&receiver=&source=

Curl sample

curl --location --request GET 'https://router.firebird.finance/aggregator/v1/route?chainId=250&from=0x04068da6c83afcfa0e13ba15a6696662335d5b75&to=0xf24bcf4d1e507740041c9cfd2dddb29585adce1e&amount=10000000&receiver=0x3FD5e7C6A2950691ffbf9358d0C093de30f54432&source=discord_swap_bot'

Request query parameters

GET URL: https://router.firebird.finance/aggregator/v1/route

Query Parameters

Name	Type	Description
chainId*	integer	Currently, we support Fantom ( 250) and Cronos (25) 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.

200: OK

{
  "encodedData": {
    "router": "0xe0c38b2a8d09aad53f1c67734b9a95e43d5981c0",
    "data": "0x7c025200000...00000"
  },
  "maxReturn": {
    "from": "0x04068da6c83afcfa0e13ba15a6696662335d5b75",
    "to": "0xf24bcf4d1e507740041c9cfd2dddb29585adce1e",
    "totalFrom": "9995000",
    "totalTo": "32174797224842296002",
    "totalGas": 473000,
    "gasPrice": "237540600000",
    "paths": [
      {
        "amountFrom": "9995000",
        "amountTo": "32174797224842296002",
        "gas": 348000,
        "swaps": [
          {
            "from": "0x04068da6c83afcfa0e13ba15a6696662335d5b75",
            "to": "0x82f0b8b456c1a451378467398982d4834b6829c1",
            "amountFrom": "9995000",
            "amountTo": "10008022331763463568",
            "pool": "0xbcab7d083cf6a01e0dda9ed7f8a02b47d125e682",
            "swapFee": 0.0001,
            "dex": "solidly"
          },
          {
            "from": "0x82f0b8b456c1a451378467398982d4834b6829c1",
            "to": "0x21be370d5312f44cb42ce377bc9b8a0cef1a4c83",
            "amountFrom": "10008022331763463568",
            "amountTo": "10117447804656825522",
            "pool": "0x8c3c964c2d08679d3d09866cf62c5b14a5346479000100000000000000000207",
            "swapFee": 0.01,
            "dex": "beethovenx",
            "meta": {
              "vaultAddress": "0x20dd72ed959b6147912c2e529f0a0c651c33c9ce"
            }
          },
          {
            "from": "0x21be370d5312f44cb42ce377bc9b8a0cef1a4c83",
            "to": "0xf24bcf4d1e507740041c9cfd2dddb29585adce1e",
            "amountFrom": "10117447804656825522",
            "amountTo": "32174797224842296002",
            "pool": "0x2d6de488fc701eb5ac687de9ad06f58fcbae45db",
            "swapFee": 0.003,
            "dex": "spiritswap"
          }
        ]
      }
    ],
    "tokens": {
      "0x04068da6c83afcfa0e13ba15a6696662335d5b75": {
        "address": "0x04068da6c83afcfa0e13ba15a6696662335d5b75",
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "price": 1
      },
      "0x21be370d5312f44cb42ce377bc9b8a0cef1a4c83": {
        "address": "0x21be370d5312f44cb42ce377bc9b8a0cef1a4c83",
        "symbol": "FTM",
        "name": "Wrapped Fantom",
        "decimals": 18,
        "price": 0.9889604661220429
      },
      "0x82f0b8b456c1a451378467398982d4834b6829c1": {
        "address": "0x82f0b8b456c1a451378467398982d4834b6829c1",
        "symbol": "MIM",
        "name": "Magic Internet Money",
        "decimals": 18,
        "price": 1
      },
      "0xf24bcf4d1e507740041c9cfd2dddb29585adce1e": {
        "address": "0xf24bcf4d1e507740041c9cfd2dddb29585adce1e",
        "symbol": "BEETS",
        "name": "BeethovenxToken",
        "decimals": 18,
        "price": 0.3122953983828485
      }
    }
  }
}

Response payload

Field	Sub field	Type	Description
encodedData		json object
	router	string	Firebird 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

Example API Code

https://github.com/firebird-prod/firebird_api_examples

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://router.firebird.finance/aggregator/v1/route'
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: '0x6c021ae822bea943b2e66552bde1d2696a53fbb7',
  to: '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee',
  amount: '1000000',
  receiver: account.address,
  source: 'sample'
})