/quote - Understanding the response

Response structure

The response lists the available providers for the route, limited by the list used to quote it. If the parameter was not included the response lists all possible providers. Estimated output, expected slippage and estimated time are some of the information listed for each swap provider so you can choose the best routes. Additionally, SwapKit provides tags to aid you in the process and identify what we would consider ourselves.

When you test your integration, use an address with enough sellAsset balance to cover the trade. This will ensure you receive complete responses.

quoteId

A unique identifier for the quote request. You can optionally store it to reference the quote provided by SwapKit at a later date.

---

routes Object

The routes array contains possible swap options, each identified by the providersobject at the start.

Field	Type	Description
providers	array	List of providers available for this route (CHAINFLIP, THORHCAINetc.).
sellAsset	string	The asset being sold (e.g., "ETH.ETH").
buyAsset	string	The asset being bought (e.g., "BTC.BTC").
sellAmount	string	Amount of the sell asset in smallest units.
expectedBuyAmount	string	Estimated amount of the buy asset to be received.
expectedBuyAmountMaxSlippage	string	Worst-case buy amount considering max slippage.
sourceAddress	string	Source address.
destinationAddress	string	Destination address.
targetAdddress	string	Address to send the initial transaction to.
approvalAddress	string	Address to approve spending to (when swapping tokens on EVM)
memo	string	Transaction memo, which can be used in UTXO chains directly.
fees	array	List of fees applied to the swap (inbound, network, affiliate).
tx	array	Transaction object for EVM chains, a PSBT object for BTC etc.
estimatedTime	object	Estimated time for different phases of the swap.
totalSlippageBps	number	Expected total slippage.
legs	array	The different involved steps in the swap.
warnings	array	Potential warnings about this swap provider.
meta	array	Other information about the transaction.
priceImpact	number	Price impact percentage in USD terms.

• The txobject is only provided if the "includeTx":trueparameter was included. It can be used as the transaction data for EVM chains. It won't be provided if the token to swap is not approved for the approvalAddress .

• targetAddress is the address to send the transaction to, but Chainflip transactions need to use a deposit channel instead and don't require approval.

It is necessary to approve approvalAddress as an spender if you are swapping tokens on an EVM chain.

In many cases targetAddress and approvalAddress will be the same but they will differ when using dex aggregation for a cross chain swap (swapping an ERC20 into BTC.BTC for example).

Example routes Object:

{
    "providers": ["MAYACHAIN"],
    "sellAsset": "ETH.ETH",
    "sellAmount": "0.1",
    "buyAsset": "BTC.BTC",
    "expectedBuyAmount": "0.00275103",
    "expectedBuyAmountMaxSlippage": "0.00247592",
    "sourceAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "destinationAddress": "357a3So9CbsNfBBgFYACGvxxS6tMaDoa1P",
    "targetAddress": "0xe3985E6b61b814F7Cdb188766562ba71b446B46d",
    "inboundAddress": "0x62b54578b77d0ccfe74b4a009d9ecbc82777c9ff",
    "expiration": "1738931194",
    "memo": "=:b:357a3So9CbsNfBBgFYACGvxxS6tMaDoa1P:247592:_/sk:20/100",
    "fees": [{
        ...
    }],
    "tx": {
        "to": "0xe3985E6b61b814F7Cdb188766562ba71b446B46d",
        "from": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "gas": "0x9714",
        "gasPrice": "0x5be199fd",
        "value": "100000000000000000",
        "data": "0x44bc937b00000000000000000000000062b54578b77d0ccfe74b4a009d9ecbc82777c9ff0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000016345785d8a000000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000067a5fbfa00000000000000000000000000000000000000000000000000000000000000393d3a623a3335376133536f394362734e6642426746594143477678785336744d61446f6131503a3234373539323a5f2f736b3a32302f31303000000000000000"
    },
    "estimatedTime": {
        ...
    },
    "totalSlippageBps": 246,
    "legs": [{
        ...
    }],
    "warnings": [],
    "meta": {
        ...
    }
    "priceImpact": -0.38,
    "approvalAddress": "0xe3985E6b61b814F7Cdb188766562ba71b446B46d",
    }

---

Fees breakdown

Fees are categorized into different types based on their role in the swap process.

Fee Type	Description
Inbound	Fee for transferring the sell asset, paid from the user's wallet.
Network	Blockchain transaction fee for processing the swap.
Affiliate	Fee paid to the specified affiliate.
Service	SwapKit's service fee.
Outbound	Fee for transferring the buy asset to the destination address.
Liquidity	Fee applied by the liquidity provider to facilitate the swap.

Only the inbound fee will be paid from the source wallet. The other fees are deducted from the output, and the output values provided by the endpoint already take this into consideration.

---

Transaction details

Transaction details are only included if the option "includeTx": true was used in the /quoterequest. It provides an object valid to initiate a transaction in the source chain. These objects can be used so sing and send the transaction using the main libraries for each blockchain.

---

Estimated time

The estimated time in seconds for the swap is divided into the following phases:

• Inbound: Time taken to receive the sell asset.

• Swap: Time taken for the swap process.

• Outbound: Time taken to transfer the bought asset to the destination. This includes the provider outbound time, not only the transaction time.

• Total: The sum of all time estimates.

Example estimated time:

"estimatedTime": {
    "inbound": 30,
    "swap": 6,
    "outbound": 624,
    "total": 660
}

---

Transaction metadata

The meta section provides additional information about the swap.

priceImpact	The expected impact on market rates.
affiliate - affiliateFee	Details of affiliate commissions.
tags	["FASTEST", "RECOMMENDED", "CHEAPEST"]
approvalAddress	The contract address for ERC-20 approvals.
chainflip	Information necessary to open a deposit channel for the Chainflip providers.

Example meta Object:

"meta": {
    "priceImpact": -1.69,
    "assets": [{
        "asset": "ETH.ETH",
        "price": 2752.14,
        "image": "https://storage.googleapis.com/token-list-swapkit/images/eth.eth.png"
    }, {
        "asset": "BTC.BTC",
        "price": 97648,
        "image": "https://storage.googleapis.com/token-list-swapkit/images/btc.btc.png"
    }],
    "approvalAddress": "0xD37BbE5744D730a1d98d8DC97c42F0Ca46aD7146",
    "tags": ["FASTEST"],
    "affiliate": "sk",
    "affiliateFee": "100",
    "txType": "EVM"
}

The "tags"can help recognize what SwapKit considers the best routes by filtering through the ["FASTEST", "RECOMMENDED", "CHEAPEST"] identification.

Tag	Description
RECOMMENDED	Best overall route based on output and speed.
CHEAPEST	The route with the maximum output.
FASTEST	The route with the shortest total estimated time.

Additionally the "chainflip"object is added for CHAINFLIP and CHAINFLIP_STREAMINGswaps. This is used to open a deposit channel, a necessary step to initiate a trade.

"chainflip": {
    "sellAsset": {
        "chain": "Ethereum",
        "asset": "ETH"
    },
    "buyAsset": {
        "chain": "Bitcoin",
        "asset": "BTC"
    },
    "destinationAddress": "357a3So9CbsNfBBgFYACGvxxS6tMaDoa1P",
    "affiliateFees": [{
        "brokerAddress": "cFNwtr2mPhpUEB5AyJq38DqMKMkSdzaL9548hajN2DRTwh7Mq",
        "feeBps": 100
    }],
    "refundParameters": {
        "minPrice": "0x2c166186363d48000000000",
        "refundAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "retryDuration": 150
    }
}

---

Warnings

Warnings highlight potential issues such as high price impact or insufficient liquidity.

Example warning:

"warnings": [
      {
        "code": "highPriceImpact",
        "display": "-10%",
        "tooltip": "This swap has a high value impact given the current liquidity and network fees. There may be a large difference between the amount of your input token and what you will receive in the output token."
      }
]

---

Provider errors

If certain providers cannot facilitate the swap, the response may include error messages under providerErrors.

Example provider error:

"providerErrors": [{
    "provider": "CHAINFLIP_STREAMING",
    "errorCode": "swapAmountTooSmall"
}]