Asking for a Quote
Details
Easily get a quote for a certain amount between two assets.
Your broker fee will automatically be taken into account.
API Endpoint
/quotes- Get a quote./quotes-native- Get a quote from native units.
Deprecated API Endpoints
/quote/quotes, this version only returnsregulartype quotes, no DCA./quote-native/quotes-native, this version only returnsregulartype quotes, no DCA.
Parameters
To get a quote, you are required to provide the following parameters:
sourceAsset- The asset to swap from, for examplebtc.btcdestinationAsset- The asset to swap to, for exampleeth.arbamount- The amount to swap, in human-readable amount for/quotes(for example1) and in native units of thesourceAssetfor/quotes-native, for example100000000to represent 1 BTC.
Optionally you can also provide the commissionBps parameter to get a custom quote with a specified commission. Note this can never be lower than your default according to the Commission Protection feature.
Response
The response consists out of an array of available quotes. There are 2 types of quotes, a regular quote and a dca quote. A regular quote is a swap which can be executed instantly, while a DCA quote spreads the swap out over time to get a better pricing.
For both types of quote, you get back the following information:
- The incoming and outgoing amounts in human-readable and native units (
ingressAmount,egressAmount,ingressAmountNative,egressAmountNative, plusintermediateAmountandintermediateAmountNativewhen the route uses an intermediate pool). - A suggested slippage limit to apply (
recommendedSlippageTolerancePercent). - An estimated price to receive in return for 1 source unit, to be used in calculating the slippage limit (
estimatedPrice). - An estimate on how long the swap will take in total (
estimatedDurationSeconds). - An estimate on how long each step of the swap will take in detail (
estimatedDurationsSeconds). - All fees which are involved in the swap (
includedFees). - All pools which are involved in the swap (
poolInfo). - A warning in case liquidity is low and there is a risk of high slippage if no slippage protection is applied (
lowLiquidityWarning). - For Bitcoin swaps, a Boost quote is supplied to quickly swap Bitcoin for a small fee (
boostQuote). - For DCA swaps, the suggested DCA parameters are provided (
chunkIntervalBlocks,numberOfChunks).
Boost
The Bitcoin Boost feature allows the user to swap Bitcoin faster than the estimated half hour (3 Bitcoin confirmations, which take 10 minutes per confirmation), in return for a small (usually 0.05%) fee. Thanks to this a Bitcoin swap can happen in minutes instead of half an hour.
The Boost quote is identical to a normal quote result, with the addition of a boost fee (representing the estimatedBoostFeeBps) and a noticeably lower estimatedDurationSeconds.
DCA
The DCA feature allows the user to perform a swap spread out over time, usually resulting in a better price because the liquidity providers are able to fill the swap in smaller chunks and provide better pricing due to less risk.
For a DCA swap, a suggested timeframe will be provided in the quote in the form of numberOfChunks and the time between chunks as chunkIntervalBlocks (a block is 6 seconds). You can later use these values to start a swap, or determine them yourself.
Error Responses
When a quote request fails, the response is an RFC 7807 problem details object. A successful request to /quotes or /quotes-native can return HTTP 200 with an empty array ([]) when a provider succeeds but has no quotes to offer. Failures that originate upstream (for example the asset is disabled, or there is not enough liquidity for the amount) carry a stable, machine-readable code next to the human-readable detail, so your client can branch on the code instead of matching the text. The HTTP status follows the code: 400 when the request as sent cannot be fulfilled (amount too small, not enough liquidity), 503 when the condition is temporary (maintenance, a disabled asset, no healthy provider), 500 only for unclassified failures. A pair that is not enabled for your account answers 403 with code route_disabled.
See Error Codes for the full list, what each one means, and how to handle unknown or missing codes.
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "Bad Request",
"status": 400,
"detail": "There is currently no quote available for this amount, try a lower amount",
"traceId": "00-6e04726aca44787669d57a48b1833007-ddd09a1fe1f24426-00",
"code": "insufficient_liquidity"
}
Testnet Example
We want to get a quote for 2 BTC to USDC.
curl --location 'https://perseverance.chainflip-broker.io/quotes-native?apikey=93c2bff017e243f29ffb14e42dccbec8&sourceAsset=btc.btc&destinationAsset=usdt.eth&amount=200000000'
[
{
"type": "regular",
"ingressAsset": "btc.btc",
"ingressAmount": 2,
"ingressAmountNative": "200000000",
"intermediateAsset": "usdc.eth",
"intermediateAmount": 188484.493872,
"intermediateAmountNative": "188484493872",
"egressAsset": "usdt.eth",
"egressAmount": 188323.954723,
"egressAmountNative": "188323954723",
"includedFees": [
{
"type": "ingress",
"asset": "btc.btc",
"amount": 0.00000405,
"amountNative": "405"
},
{
"type": "network",
"asset": "usdc.eth",
"amount": 188.956602,
"amountNative": "188956602"
},
{
"type": "broker",
"asset": "usdc.eth",
"amount": 283.151468,
"amountNative": "283151468"
},
{
"type": "egress",
"asset": "usdt.eth",
"amount": 1.617026,
"amountNative": "1617026"
},
{
"type": "liquidity",
"asset": "btc.btc",
"amount": 0.00099999,
"amountNative": "99999"
},
{
"type": "liquidity",
"asset": "usdc.eth",
"amount": 94.242246,
"amountNative": "94242246"
}
],
"recommendedSlippageTolerancePercent": 2.5,
"lowLiquidityWarning": false,
"poolInfo": [
{
"baseAsset": "btc.btc",
"quoteAsset": "usdc.eth",
"fee": {
"asset": "btc.btc",
"amount": 0.00099999,
"amountNative": "99999"
}
},
{
"baseAsset": "usdt.eth",
"quoteAsset": "usdc.eth",
"fee": {
"asset": "usdc.eth",
"amount": 94.242246,
"amountNative": "94242246"
}
}
],
"estimatedDurationSeconds": 1920,
"estimatedDurationsSeconds": {
"deposit": 1806,
"swap": 12,
"egress": 102
},
"estimatedPrice": 94162.97655452752291823391,
"boostQuote": {
"ingressAsset": "btc.btc",
"ingressAmount": 2,
"ingressAmountNative": "200000000",
"intermediateAsset": "usdc.eth",
"intermediateAmount": 188390.251435,
"intermediateAmountNative": "188390251435",
"egressAsset": "usdt.eth",
"egressAmount": 188229.797076,
"egressAmountNative": "188229797076",
"includedFees": [
{
"type": "boost",
"asset": "btc.btc",
"amount": 0.001,
"amountNative": "100000"
},
{
"type": "ingress",
"asset": "btc.btc",
"amount": 0.00000405,
"amountNative": "405"
},
{
"type": "network",
"asset": "usdc.eth",
"amount": 188.862123,
"amountNative": "188862123"
},
{
"type": "broker",
"asset": "usdc.eth",
"amount": 283.009892,
"amountNative": "283009892"
},
{
"type": "egress",
"asset": "usdt.eth",
"amount": 1.617026,
"amountNative": "1617026"
}
],
"lowLiquidityWarning": false,
"poolInfo": [
{
"baseAsset": "btc.btc",
"quoteAsset": "usdc.eth",
"fee": {
"asset": "btc.btc",
"amount": 0.00099949,
"amountNative": "99949"
}
},
{
"baseAsset": "usdt.eth",
"quoteAsset": "usdc.eth",
"fee": {
"asset": "usdc.eth",
"amount": 94.195125,
"amountNative": "94195125"
}
}
],
"estimatedDurationSeconds": 720,
"estimatedDurationsSeconds": {
"deposit": 606,
"swap": 12,
"egress": 102
},
"estimatedBoostFeeBps": 5
}
},
{
"type": "dca",
"ingressAsset": "btc.btc",
"ingressAmount": 2,
"ingressAmountNative": "200000000",
"intermediateAsset": "usdc.eth",
"intermediateAmount": 188484.407937,
"intermediateAmountNative": "188484407937",
"egressAsset": "usdt.eth",
"egressAmount": 188388.548644,
"egressAmountNative": "188388548644",
"includedFees": [
{
"type": "ingress",
"asset": "btc.btc",
"amount": 0.00000405,
"amountNative": "405"
},
{
"type": "network",
"asset": "usdc.eth",
"amount": 188.95653,
"amountNative": "188956530"
},
{
"type": "broker",
"asset": "usdc.eth",
"amount": 283.151358,
"amountNative": "283151358"
},
{
"type": "egress",
"asset": "usdt.eth",
"amount": 1.617026,
"amountNative": "1617026"
},
{
"type": "liquidity",
"asset": "btc.btc",
"amount": 0.00099999,
"amountNative": "99999"
},
{
"type": "liquidity",
"asset": "usdc.eth",
"amount": 94.242203,
"amountNative": "94242203"
}
],
"recommendedSlippageTolerancePercent": 2.5,
"lowLiquidityWarning": false,
"poolInfo": [
{
"baseAsset": "btc.btc",
"quoteAsset": "usdc.eth",
"fee": {
"asset": "btc.btc",
"amount": 0.00099999,
"amountNative": "99999"
}
},
{
"baseAsset": "usdt.eth",
"quoteAsset": "usdc.eth",
"fee": {
"asset": "usdc.eth",
"amount": 94.242203,
"amountNative": "94242203"
}
}
],
"estimatedDurationSeconds": 2664,
"estimatedDurationsSeconds": {
"deposit": 1806,
"swap": 756,
"egress": 102
},
"estimatedPrice": 94195.27358042900036872575,
"chunkIntervalBlocks": 2,
"numberOfChunks": 63,
"boostQuote": {
"ingressAsset": "btc.btc",
"ingressAmount": 2,
"ingressAmountNative": "200000000",
"intermediateAsset": "usdc.eth",
"intermediateAmount": 188390.195721,
"intermediateAmountNative": "188390195721",
"egressAsset": "usdt.eth",
"egressAmount": 188294.383489,
"egressAmountNative": "188294383489",
"includedFees": [
{
"type": "boost",
"asset": "btc.btc",
"amount": 0.001,
"amountNative": "100000"
},
{
"type": "ingress",
"asset": "btc.btc",
"amount": 0.00000405,
"amountNative": "405"
},
{
"type": "network",
"asset": "usdc.eth",
"amount": 188.862093,
"amountNative": "188862093"
},
{
"type": "broker",
"asset": "usdc.eth",
"amount": 283.009797,
"amountNative": "283009797"
},
{
"type": "egress",
"asset": "usdt.eth",
"amount": 1.617026,
"amountNative": "1617026"
}
],
"lowLiquidityWarning": false,
"poolInfo": [
{
"baseAsset": "btc.btc",
"quoteAsset": "usdc.eth",
"fee": {
"asset": "btc.btc",
"amount": 0.00099949,
"amountNative": "99949"
}
},
{
"baseAsset": "usdt.eth",
"quoteAsset": "usdc.eth",
"fee": {
"asset": "usdc.eth",
"amount": 94.195097,
"amountNative": "94195097"
}
}
],
"estimatedDurationSeconds": 1464,
"estimatedDurationsSeconds": {
"deposit": 606,
"swap": 756,
"egress": 102
},
"estimatedBoostFeeBps": 5,
"chunkIntervalBlocks": 2,
"numberOfChunks": 63
}
}
]