/quote - Implementation flow

Implement a correct quoting 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:

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:

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:

{
  // ... 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:

{
  "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..."
  }
}