/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: false object is used, but it is important to keep a proper quote request flow for a better functioning integration.

1. Initial Quote Request

First, fetch quotes with includeTx: false (or unset, as false is the default):

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",
    "slippage": 3,
    "includeTx": false
  }'

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. Transaction Building

When the user is ready to execute the swap, request a new quote with includeTx: true:

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",
    "slippage": 3,
    "includeTx": true
  }'

Setting includeTx: true results in slightly slower response times as the system performs additional validations and transaction building.

The quote response will now include additional transaction related fields, different for each provider:

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

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.

• 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).

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