🔸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

Name	Value
`Marswap-Api-Key`	string

Marswap-Api-Key

string

Query Parameters

Parameter Description Required Type

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

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%.

number

feeRecipient

The wallet address that will receive affiliate fees from each trade.

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

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

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

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

{
  "error": "Invalid request"
}

Example

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'

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

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.

PreviousPrice API NextExamples

Last updated 1 month ago