/v3/quote - Request a swap quote
Obtain a quote before performing a swap.
Method: POST
URL: https://api.swapkit.dev/quote
The first step towards performing a swap is requesting a quote, which will compare the price offered by the different swap providers.
Request Schema
Here's a detailed description of the different parameters:
sellAsset
string
Yes
The asset being sold (e.g. "ETH.ETH").
buyAsset
string
Yes
The asset being bought (e.g. "BTC.BTC").
sellAmount
string
Yes
Amount in basic units (decimals separated with a dot).
providers
array
No
Limits the possible liquidity providers. If omitted, all available providers are used.
slippage
number
No
Max slippage in percentage (5 = 5%).
affiliateFee
number
No
Affiliate fee override in basis points (0-1000, max 10%). Must be a positive integer. If it is not provided, the API key configured fee tiers are applied.
cfBoost
boolean
No
Enables Chainflip boost for better rates.
maxExecutionTime
number
No
Maximum execution time in seconds. Routes exceeding this time are filtered out.
Note: Asset names for sellAsset and buyAsset should follow the following nomenclature:
Chain.Asset (e.g.,
"BTC.BTC"or"ARB.ETH")Chain.Asset-ContractAddress (e.g.,
"ETH.USDC-0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48")
This is the identifier as provided in the /tokens or /swapTo endpoints.
Example request
A simple request to trade ETH.ETHto BTC.BTCmay omit the providers array if you can manage them in the response, but should include the amount and slippage settings.
The expiration time of a quote is of 60 seconds. After that, you may request a new one or it will be automatically requested if a swap is openned using this routeId .
Quote Response Schema
quoteId
string
UUID for this quote response
routes
QuoteRoute[]
An array of routes with an individual routeId to request a swap with. QuoteRoute schema is explained below
providerErrors
QuoteError[] or undefined
Optional. If errors encountered from providers, details returned here. QuoteError schema is explained below
error
string or undefined
In case of a bad request, root level error is provided.
Quote Route Schema
Each route identifies a provider or group of providers for the swap. Each item in the routes array contains the information needed to compare between them:
routeId
string
UUID of this specific swap response.
providers
array
List of providers available for this route (CHAINFLIP, THORHCAIN etc.).
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.
fees
array
List of fees applied to the swap (inbound, network, affiliate, service).
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
object
Other information about the transaction and the assets involved.
meta.tags
array
"FASTEST", "RECOMMENDED" or "CHEAPEST" tag help sort the routes available
nextActions
object
Data about next request to make in the flow.`{ method: string; url: string; payload: object
Quote Error Schema
provider
string
Specific ProviderName value
errorCode
string
One of the possible error codes listed below.
message
string
Message relating to thrown error.
Quote Error Codes and messages
noRoutesFound
No routes found for swap from {sellAsset} to {buyAsset}
404
No valid swap path exists between the requested token pair.
blackListAsset
Asset {asset} is blacklisted
400
The sell or buy asset is identified as a scam token in our blacklist.
apiKeyInvalid or unauthorized
"Invalid API key" / "Unauthorized”
401
Missing, expired, or invalid API key in x-api-key header.
invalidRequest
"Request body is required and must be a valid JSON object”.
400
Request body is missing, null, or malformed JSON.
The invalidRequest error may include additional details depending on the missing parameters. Make sure to check the JSON formatting in the request.
Fees breakdown
Fees are categorized into different types based on their role in the swap process.
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.
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:
Route metadata
The meta section provides additional information about the swap.
assets
Details of the involved assets, including price and image links.
tags
["FASTEST", "RECOMMENDED", "CHEAPEST"]
Example meta Object:
meta Object:The "tags"can help recognize what SwapKit considers the best routes by filtering through the ["FASTEST", "RECOMMENDED", "CHEAPEST"] identification.
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.
Next Actions
The nextActions object includes information about the request to use next. Generally it will point to the /swap endpoint which will return a transaction object, but the /swap endpoint may only approve spending for a token and include a new nextActions object.
As an example, it could be something like this, which includes the method, url and payload to use. The "soureAddress" and "destinationAddress" need to be filled in:
Last updated