🔸Quote API

Step by step guide to set up the Marswap Aggregator API

GET/v1/swap/quote

This endpoint can be used to request transaction data to submit to the blockchain for a swap between two tokens.

Headers

Name	Value
Marswap-Api-Key	string

Query Parameters

Parameter	Description	Required	Type
sellToken	The address of the token you want to sell.	Yes	string
buyToken	The address of the token you want to buy.	Yes	string
sellAmount	The amount of sell token to swap in base units.	Yes	number
buyTokenOrSellTokenHasFees	Boolean indicating if buy or sell token has fees/taxes.	No. Default is true	boolean
slippagePercentage	Maximum slippage percentage for the swap.	Yes	number
integratorId	The integrator ID provided by the Marswap team for authentication.	Yes	string
buyTokenPercentageFee	The percentage of the buyAmount that will be sent to the feeRecipient as affiliate fees. Maximum is 1%.	No	number
feeRecipient	The wallet address that will receive affiliate fees from each trade.	No	string
gasPrice	The gas price on the network in Wei. This is required to determine the amount gas to submit with the transaction.	Yes	number
takerAddress	The address of the wallet making the swap.	Yes	string

Response

Parameter	Description
chainId	The blockchain network ID.
price	The calculated swap price of the buy token relative to the sell token.
minimumPrice	The minimum acceptable swap price of the buy token relative to the sell token considering slippage.
value	The amount of ETH in Wei to be sent in the transaction.
buyTokenAddress	The address of the token you want to buy.
buyAmount	The calculated amount of buy token to receive in base units.
sellTokenAddress	The address of the token you want to sell.
sellAmount	The amount of sell token to swap in base units.
sellTokenToEthRate	The exchange rate of sell token to ETH. Multiply this by the USD price of ETH to get the USD value of the sell token.
buyTokenToEthRate	The exchange rate of buy token to ETH. Multiply this by the USD price of ETH to get the USD value of the buy token.
swapFeeInEth	The swap fee in ETH.
allowanceTarget	The address of the contract to grant approval allowance to for the swap.
gas	The estimated gas limit that should be used to send the transaction to ensure success. While a estimate is returned in all responses, an accurate estimate will only be returned if a takerAddress is included in the request.
estimatedGas	The estimate for the amount of gas that will actually be used in the transaction.
gasPrice	The gas price on the network in Wei. This is required to determine the amount gas to submit with the transaction.
from	The address of the wallet making the swap.
to	The address of the contract to send transaction data to.
data	A transaction request that can be submitted to the blockchain using Ethers.js, Web3.js, etc to make the swap

200

{
    "swapFeeInEth": "10000000000000000",
    "chainId": 109,
    "price": "3460.659111705276",
    "minimumPrice": "3287.6261561200122",
    "to": "0xA0826E0d33879BbF360bEE11263E2c520D909565",
    "data": "0x97bc35a80000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000008ac7230489e800000000000000000000000000000000000000000000000006f639c82803327bf28000000000000000000000000000000000000000000000000000000000000000e00000000000000000000000000000000000000000000000000000000000000002000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee000000000000000000000000abbaf2746c46f8f269e0a252285abe9d8d8cdf6300000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000001869584cd000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000003d5b366733660c1c33",
    "value": "10010000000000000000",
    "gas": "222816",
    "estimatedGas": "222816",
    "from": "0x_swap_wallet_address", // Wallet address making the swap
    "gasPrice": "12401265290",
    "buyTokenAddress": "0xabbaf2746c46f8f269e0a252285abe9d8d8cdf63",
    "sellTokenAddress": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
    "buyAmount": "34606591117052760000000",
    "sellAmount": "10000000000000000000",
    "sellTokenToEthRate": "1",
    "buyTokenToEthRate": "3607.09844155613867812",
    "allowanceTarget": "0x0000000000000000000000000000000000000000"
}

400

{
  "error": "Invalid request"
}

Example

Curl

curl -X GET \
  'https://shib-api.marswap.exchange/swap/v1/quote?sellToken=0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee&buyToken=0xabbaf2746c46f8f269e0a252285abe9d8d8cdf63&slippagePercentage=0.05&buyTokenOrSellTokenHasFees=true&sellAmount=10000000000000000000&integratorId=test-api&feeRecipient=0x_fee_wallet_address&buyTokenPercentageFee=0.001&gasPrice=12379951372&takerAddress=0x_swap_wallet_address' \
  -H 'marswap-api-key: 4b5f885c-b764-4160-95f4-00ceb5124abb'

JavaScript

const params = {
  sellToken: '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee',
  buyToken: '0xabbaf2746c46f8f269e0a252285abe9d8d8cdf63',
  slippagePercentage: 0.05,
  buyTokenOrSellTokenHasFees: true,
  sellAmount: '10000000000000000000',
  integratorId: 'test-api', //Example ID
  feeRecipient: '0x_fee_wallet_address', // Enter wallet address to receive fee,
  buyTokenPercentageFee: 0.001, //0.1%
  gasPrice: 12379951372,
  takerAddress: '0x_swap_wallet_address', // Enter the wallet address making the swap
 }
 
// Construct the query string
const search = Object.keys(params).reduce(
  (searchString, key) => (params[key] !== undefined ? `${searchString}&${key}=${params[key]}` : searchString),
  '',
)

// Make a GET request to the API endpoint 
const response = await fetch(`https://shib-api.marswap.exchange/swap/v1/quote?${search.slice(1)}`, {
  headers: {
      'marswap-api-key': '4b5f885c-b764-4160-95f4-00ceb5124abb' //Example API Key
  }
})

// Check if the response is ok
if (response.ok) {
  const routeResponse = await response.json()
  console.log(routeResponse)
} else {
  console.error('Failed to fetch data');
}

Python

import requests

params = {
    'sellToken': '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee',
    'buyToken': '0xabbaf2746c46f8f269e0a252285abe9d8d8cdf63',
    'slippagePercentage': 0.05,
    'buyTokenOrSellTokenHasFees': True,
    'sellAmount': '10000000000000000000',
    'integratorId': 'test-api',  # Example ID
    'feeRecipient': '0x_fee_wallet_address',  # Enter wallet address to receive fee,
    'buyTokenPercentageFee': 0.001,  # 0.1%
    'gasPrice': 12379951372,
    'takerAddress': '0x_swap_wallet_address', # Enter the wallet address making the swap
}

# Construct the query string
search = '&'.join([f"{key}={value}" for key, value in params.items() if value is not None])

# Make a GET request to the API endpoint
url = f"https://shib-api.marswap.exchange/swap/v1/quote?{search}"
headers = {'marswap-api-key': '4b5f885c-b764-4160-95f4-00ceb5124abb'}  # Example API Key

response = requests.get(url, headers=headers)

# Check if the response is ok
if response.ok:
    route_response = response.json()
    print(route_response)
else:
    print('Failed to fetch data')

Allowance

An "allowance" refers to the amount of a specific ERC-20 token that an owner has approved another Ethereum address to swap. In our case, we would like the Marswap Aggregator smart contract to trade ERC20 tokens.

To do so, we will need to give an allowance to the allowanceTarget parameter that's returned by the API. The allowanceTarget is the the target contract address, in our case the Marswap Aggregator smart contract address on the relevant network.

For swaps with "ETH" as sellToken, wrapping "ETH" to "WETH" or unwrapping "WETH" to "ETH" no allowance is needed.

Read more here about setting token allowances.