Quote and Swap Implementation flow

Implement a correct quoting flow

A key part of our service is the ability to include 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 the /v3/quote endpoint. 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

Once you have presented a price to the user, they would then accept it. This determines which provider offers the best match for the route you quoted. The available providers are labeled with the "RECOMMENDED", "FASTEST" and "CHEAPEST" tags.

Then, before presenting the user with a transaction to sign, you will call the /swap endpoint, referencing the chosen quote via its routeId.

3. Request a /swap - Transaction Building

When the user is ready to execute the swap, request the /v3/swap endpoint with the selected routeId along with the user's sourceAddress and destinationAddress

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 5 minutes. After it expires, a new quote is fetched using the original parameters before the swap request is processed.

The swap will include transaction-related fields under tx, which may be either an object or a string. It also includes the price, so you can display it to the user again before signing or compare it internally against the previous value before presenting 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"
  }
}

If SLIP-0024 signing is enabled for your API key, the response also includes a signed payload ready for verification.

---

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 will receive a complete route with transaction data that can be directly signed and broadcasted.

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 errors that can be returned. You can find more details on 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..."
  }
}