/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..."
}
}
Last updated