Quote and Swap Implementation flow

Implement a correct quoting flow

An important part of our service is the possibility of including transaction data in a /swap response. After already implementing our /providers and their /tokens, you will use the /quote and /swap endpoints to process transactions for your users.

1. Initial Quote Request

First, fetch quotes with . For this step, "sourceAddress" and "destinationAddress" are not needed and instead you are just quoting the price of a swap:

curl -X POST "https://api.swapkit.dev/v3/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
  }'

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. The "nextActions" object will inform you of the following steps to take. Generally, you will provide the routeId into the /swap endpoint.

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. We identify the different providers offered with the "RECOMMENDED", "FASTEST" and "CHEAPEST" tags.

Before the user gets offered a transaction to sign though, you will use the /swap endpoint referencing the quote used by using the routeId.

3. Request a /swap - Transaction Building

When the user is ready to execute the swap, request the /swap endpoint with the selected routeId and the addresses the user is using:

curl -X POST "https://api.swapkit.dev/v3/swap" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_VARIABLE_HERE" \
  -d '{
    "routeId": "eed91159-86bd-4674-9558-48f7e4f8bac0",
    "sourceAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "destinationAddress": "357a3So9CbsNfBBgFYACGvxxS6tMaDoa1P"
}'

This endpoint can take a bit longer to reply. SwapKit builds the transaction payload, including fetching UTXOs and building PSBT when required, does a balance check and also performs address screening on every /swap call automatically.

The routeId is valid for 60 seconds. Past that time, a new quote will be obtained with the initial parameters before processing the swap request.

The swap will include transaction related fields under tx, which could be an object or a string. It also includes the price so you can show it 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 calling the /swap endpoint, the system performs the following validations:

1. Balance Verification

SwapKit 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 different the errors that could be returned. You can see them in more detail in the swap endpoint page.

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