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

For a ready-made quote request and a captured example response for a specific route or asset pair, such as BTC to SOL, see [Chainflip Swap Routes](https://docs.chainflip-broker.io/routes/).

## API Endpoint

* [`/quotes`](https://chainflip-broker.io/docs/ui/index.html#tag/Quote/operation/getQuotes) - Get a quote.
* [`/quotes-native`](https://chainflip-broker.io/docs/ui/index.html#tag/Quote/operation/getNativeQuotes) - Get a quote from native units.

### Deprecated API Endpoints

* ~~[`/quote`](https://chainflip-broker.io/docs/ui/index.html#tag/Quote/operation/getQuote)~~ - Deprecated in favor of `/quotes`, this version only returns `regular` type quotes, no DCA. When Chainflip offers only a DCA quote for the amount, it answers `400` with code `insufficient_liquidity`.
* ~~[`/quote-native`](https://chainflip-broker.io/docs/ui/index.html#tag/Quote/operation/getNativeQuote)~~ - Deprecated in favor of `/quotes-native`, this version only returns `regular` type quotes, no DCA. When Chainflip offers only a DCA quote for the amount, it answers `400` with code `insufficient_liquidity`.

## Parameters

To get a quote, you are required to provide the following parameters:

* `sourceAsset` - The asset to swap from, for example `btc.btc`
* `destinationAsset` - The asset to swap to, for example `eth.arb`
* `amount` - The amount to swap, in human-readable amount for `/quotes` (for example `1`) and in native units of the `sourceAsset` for `/quotes-native`, for example `100000000` to 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](https://docs.chainflip-broker.io/use-cases/#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`, plus `intermediateAmount` and `intermediateAmountNative` when the route uses an intermediate pool).
* A suggested [slippage limit](https://docs.chainflip-broker.io/features/start-swap/#slippage-protection) to apply (`recommendedSlippageTolerancePercent`).
* A suggested `retryDurationInBlocks` for [starting the swap](https://docs.chainflip-broker.io/features/start-swap/#slippage-protection) (`recommendedRetryDurationInBlocks`): Chainflip recommends 30 minutes (`300` blocks) when BTC is on either side and 5 minutes (`50` blocks) otherwise.
* A suggested [live price protection](https://docs.chainflip-broker.io/features/start-swap/#live-price-protection) limit (`recommendedLivePriceSlippageTolerancePercent`), absent when Chainflip has no oracle-based protection to recommend for the pair.
* An estimated price to receive in return for 1 source unit, to be used in calculating the [slippage limit](https://docs.chainflip-broker.io/features/start-swap/#slippage-protection) (`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](https://docs.chainflip-broker.io/features/ask-quote/#boost) quote is supplied to quickly swap Bitcoin for a small fee (`boostQuote`).
* For [DCA](https://docs.chainflip-broker.io/features/ask-quote/#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`. It carries its own `recommendedSlippageTolerancePercent`, `recommendedRetryDurationInBlocks` and `recommendedLivePriceSlippageTolerancePercent`, and `maxBoostFeeBps`: the `boostFee` to [start the boosted swap](https://docs.chainflip-broker.io/features/start-swap/#boost) with.

### 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](https://docs.chainflip-broker.io/features/start-swap/), or determine them yourself.

## Error Responses

When a quote request fails, the response is an [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807) 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](https://docs.chainflip-broker.io/features/error-codes/) for the full list, what each one means, and how to handle unknown or missing codes.

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

## Example

> **Tip**
>
> Want to test first? Change the API base URL to `https://perseverance.chainflip-broker.io`. The [Testing](https://docs.chainflip-broker.io/environments/testing/) environment swaps testnet assets with no real value.
>
> Swap the API key in the examples for your own [production API key](https://chainflip-broker.io/register). Testing requires a separate [testnet API key](https://perseverance.chainflip-broker.io/register).

We want to get a quote for `2 BTC` to `USDC`.

```bash
curl --location 'https://chainflip-broker.io/quotes-native?apiKey=87517a91d5f34dbabfc1e410946a3a3c&sourceAsset=btc.btc&destinationAsset=usdt.eth&amount=200000000'
```

```json
[
    {
        "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
        }
    }
]
```
