# /quote v2 - Implementation flow

An important part of our service is the possibility of including transaction data in a `/quote` response.\
This option is activated when the "`includeTx": true` request parameter is used, but it is important to keep a proper quote request flow for a better performing integration.

### 1. Initial Quote Request

First, fetch quotes with "`includeTx": false` (or unset, as false is the default). For this step, you may leave out `"sourceAddress"` and `"destinationAddress"` since they are not needed to process a quote:

```bash
curl -X POST "https://api.swapkit.dev/quote" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_VARIABLE_HERE" \
  -d '{
    "sellAsset": "BTC.BTC",
    "buyAsset": "ETH.ETH",
    "sellAmount": "0.1",
    "slippage": 3,
    "includeTx": false
  }'
```

You can filter for the providers you have integrated using the `"providers"` argument if you want to limit the options shown.

This returns a regular quote response including pricing information, estimated timing and fees, and route details with the available providers, but without transaction data.

### 2. Identify the Provider route you want to use

After offering a price to the user of your application, the user would then accept it. This identifies what provider offers the best match for the route you quoted for.

Before the user gets offered a transaction to sign though, you will request a new quote filtering with this specific provider and requesting a transaction object.

### 3. Transaction Building

When the user is ready to execute the swap, request a new quote with "`includeTx": true` and filtering by provider:

```bash
curl -X POST "https://api.swapkit.dev/quote" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_VARIABLE_HERE" \
  -d '{
    "sellAsset": "BTC.BTC",
    "buyAsset": "ETH.ETH",
    "sellAmount": "0.1",
    "sourceAddress": "357a3So9CbsNfBBgFYACGvxxS6tMaDoa1P",
    "destinationAddress": "0x0a4c79cE84202b03e95B7a692E5D728d83C44c76",
    "providers": ["NEAR"],
    "slippage": 3,
    "includeTx": true
  }'
```

Setting `includeTx: true` results in slightly slower response times as the system performs additional validations and transaction building. This is why it is also best to now filter the providers used, so only the specific best quote is returned.

The quote response will now include additional transaction related fields, different for each provider. You can show the price to the user again for signing or compare internally to the previous value before offering it:

```json
{
  // ... all fields from above, plus:
  "targetAddress": "1FSHYruFaYjm5FQrzB3LmF15FMC3QwUFmy",
  "inboundAddress": "1FSHYruFaYjm5FQrzB3LmF15FMC3QwUFmy",
  "tx": "cHNidP8BAHUCAAAAAc86GvpcKcJoCV1YpX9orAcE/ZckHbLzuTXOPl0McccZAAAAAAD/////AoCWmAAAAAAAGXapFJ5Z+YVfu2g/WM/XGmu9FBGSeS5wiKx/LhEm4wAAABepFFKL8plEPOVGF9/52YVT+SKl3opehwAAAAAAAQEg/8SpJuMAAAAXqRRSi/KZRDzlRhff+dmFU/kipd6KXocAAAA=",
  "meta": {
    // ... existing meta fields, plus:
    "txType": "PSBT"
  }
}
```

***

### Transaction Building Process

When `includeTx: true` is set, the system performs the following validations:

#### 1. Balance Verification

The system first checks if the source address has sufficient balance to cover the `sellAmount`. If insufficient funds are detected, an `insufficientBalance` error is thrown for the entire request.

#### 2. Transaction Building

If the balance check passes, the system attempts to build the transaction. In certain edge cases, the wallet may have enough balance to match the `sellAmount` but insufficient funds to cover network fees. Since different providers have varying transaction sizes, some may return valid transaction data while others might fail with an `unableToBuildTransaction` error.

#### 3. Successful Response

If all validations pass, you'll receive a complete route with transaction data that can be directly signed and broadcast.

### Key Fields

* `targetAddress` The deposit address where funds should be sent, or the address of the contract that should be called.
* `inboundAddress` The address monitoring for incoming transactions.
* `tx` The transaction data ready for signing.
* `txType` The format of the transaction data (e.g., "PSBT" for Bitcoin or "EVM" for EVM chains).

### Error Handling

Be prepared to handle the following errors when using `includeTx: true`:

* `insufficientBalance` The source address doesn't have enough tokens for the swap.
* `insufficientAllowance`: The source address doesn't have enough tokens approved for the contract interaction. Relevant for tokens in EVM networks.
* `unableToBuildTransaction` The wallet has sufficient tokens but insufficient funds for network fees.

This is an example error for a wallet without enough balance:

```json
{
  "message": "Cannot build transaction. Insufficient balance for asset ETH.USDC-0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 amount 700 address 0x...",
  "error": "insufficientBalance",
  "data": {
    "chain": "ETH.USDC-0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "amount": "700",
    "address": "0x..."
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.swapkit.dev/swapkit-api-v2/quote-v2-implementation-flow.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.