/v3/swap - Obtain swap transaction details

Use an existing routeId to obtain a swap's transaction details.

Method: POST URL: https://api.swapkit.dev/v3/swap

After the user has accepted a quote, perform a request to the swap endpoint to obtain transaction details. Use a quote's routeId to identify it, providing additional details about the involved addresses.

Request Schema

Parameter	Type	Required	Description
routeId	string	Yes	The ID of the route to swap. Obtained from a previous /v3/quote response
sourceAddress	string	Yes	Blockchain address to send the asset from. Must be a valid address for the sell asset's chain
destinationAddress	string	Yes	Recipient blockchain address to send the asset to. Must be a valid address for the buy asset's chain
disableBalanceCheck	boolean	No	Whether to skip balance validation. If false or omitted, checks that source address has sufficient balance. Default:false
disableEstimate	boolean	No	Whether to skip on-chain gas estimation when building the transaction. Default: false
allowSmartContractSender	boolean	No	Whether to allow the source address to be a smart contract. Default: false
allowSmartContractReceiver	boolean	No	Whether to allow the destination address to be a smart contract. Default: false
disableSecurityChecks	boolean	No	Whether to bypass address format validation and security checks. Default: false
overrideSlippage	boolean	No	Whether to bypass the 5% output amount deviation check when the quote is refreshed. Default: false

When you test your integration, use an address with enough sellAsset balance to cover the swap. This will ensure you receive complete responses with a valid transaction object.

As an example, the request could be something as simple as this (this `routeId` will not work for you since it is now expired):

cURL

curl -X 'POST' \
  'https://api.swapkit.dev/v3/swap' \
  -H 'Content-Type: application/json' \
  -H "x-api-key: YOUR_VARIABLE_HERE" \
  -d '{
    "routeId": "85bb4fa2-3a65-4d22-b20b-e43d028d83e6",
    "sourceAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "destinationAddress": "357a3So9CbsNfBBgFYACGvxxS6tMaDoa1P"
}'

A quote is valid for one minute. If the routeId specified is older than one minute, a new quote will be fetched.

Swap Response Schema

Field	Type	Description
swapId	string	UUID of this specific swap response.
providers	array	List of providers available for this route (CHAINFLIP, THORHCAINetc.).
sellAsset	string	The asset being sold (e.g., “ETH.ETH”).
buyAsset	string	The asset being bought (e.g., “BTC.BTC”).
sellAmount	string	Amount of the sell asset in smallest units.
expectedBuyAmount	string	Estimated amount of the buy asset to be received.
expectedBuyAmountMaxSlippage	string	Worst-case buy amount considering max slippage.
tx	varies	Explained below
approvalTx	object	For EVM sell chain. When a token approval transaction is required to be submitted before the tx can be broadcasted.
targetAddress	string	The target of the swap. Either by transfer of assets here, or smart contract call with this recipient. Interacting with this directly is is not advised. Please use the tx we return, unless you are an advanced user.
memo	string	Optional. Memo with instructions for swap.
fees	array	List of fees applied to the swap (inbound, network, affiliate, service).
estimatedTime	object	Estimated time for different phases of the swap.
totalSlippageBps	number	Expected total slippage.
legs	array	The different involved steps in the swap.
warnings	array	Potential warnings about this swap provider.
meta	object	Other information about the transaction.
nextActions	object	Data about next request to make in the flow.

The tx field

We provide the ready to be signed transaction in the tx field. It can be an object or a string, depending on the source chain of the swap.

• VM sell chain - Ethers V6 Transaction https://docs.ethers.org/v6/api/transaction/#Transaction

• UTXO sell chain (BTC, BCH, LTC, DOGE) - base64 encoded PSBT ZCash sell chain - By default a base64 encoded PSBT using https://github.com/BitGo/BitGoJS/blob/master/modules/utxo-lib/src/bitgo/UtxoPsbt.ts#L161 library is returned.We also support returning of an unsigned PCZT using https://github.com/zcash/librustzcash - Please reach out for more information.

• TRON sell chain - A TransactionBuilder object from the TronWeb lib https://tronweb.network/docu/docs/API%20List/transactionBuilder/sendAsset#example

• Cosmos sell chains (incl THOR & MAYA) - A native Cosmos transaction object https://tutorials.cosmos.network/academy/2-cosmos-concepts/3-transactions.html#generating-transactions

As an example, for an EVM sell chain it could be something like this. In this case, this is a simple transfer without any contract being involved:

"tx": {
        "to": "0x4e6960159d85254cb8e88483793f6fa8e9a49a4c",
        "from": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "gas": "0x5208",
        "gasPrice": "0x9129260",
        "value": "3000000000000000000",
        "data": "0x"
    },

---

Swap Errors

Field	Type	Description
provider	string	Specific provider name
errorCode	string	One of the possible error codes listed below.
message	string	Message related to the error.

Error codes and messages

Error	Message	Status Code	Scenario
swapRouteNotFound	Route not found for routeId: {routeId}	404	The routeId doesn't exist in cache (expired after 5 minutes or never existed). Client must request a new quote first.
isSanctionedAddress	Address {address} is sanctioned or risky	400	Source or destination address flagged by screening service (Chainalysis/Elliptic). Addresses are screened against sanctions lists and risk databases
apiKeyInvalid / unauthorized	"Invalid API key" / "Unauthorized”	401	Missing, expired, or invalid API key in x-api-key header.
insufficientBalance	Insufficient balance for {chain} amount {amount} at address {address}	400	When disableBalanceCheck is false, source address doesn't have enough tokens to complete the swap. Balance fetched from blockchain and compared to sellAmount.
invalidSourceAddress	Invalid source address: {address}	400	Source address validation fails (invalid format, smart contract when not allowed, or fails security checks).
invalidDestinationAddress	Invalid destination address: {address}	400	Destination address validation fails (invalid format, smart contract when not allowed, or fails security checks).
outputAmountDeviationTooHigh	Output amount deviation too high. Original: {originalAmount}, Refreshed: {refreshedAmount}, Deviation: {percentageChange}%	400	Quote was refreshed and the new output amount deviates more than 5% from the cached quote. Protects users from price slippage. Can be bypassed withoverrideSlippage: true
noRoutesFound	No routes found for swap from {sellAsset} to {buyAsset}	404	When quote is refreshed, no valid routes are returned from providers. Rare - indicates liquidity dried up or all providers failed.

---

Additional Notes

• Quote price refresh: The quote response is kept in our cache for 60s. If the /swap call is done after 60s, the /swap endpoint will automatically get a fresh quote on the blockchain. If you always want to get the swap payload for the quote

• Balance check: By default we check that the sourceAddress has a sufficient balance. Since OKW is already the wallet, you can use disableBalanceCheck: true in the body of the /swap request.

• Latency: The /swap endpoint is more costly and slower. We build the transaction payload, including fetching UTXOs and building PSBT when required. We do a balance check. We also do address screening on every /swap call automatically. We also open a deposit channel if NEAR or Chainflip providers are used, which can take up to 2.5s.

  Calling this endpoint should only be done after the user has selected a quote as their swap route.

• Other items which are part of the /quote endpoint response are also included here, such as estimatedTime, totalSlippage or the fees breakdown.

Some of these can be skipped by using the optional parameters listed in the request schema.

Optional /swap params:

1. disableBalanceCheck : skip checking the sourceAddress balance of the fromAsset . Recommended for wallets that do this check internally.

2. disableEstimate : skip gas estimation for EVM chains.

3. overrideSlippage : receive a /swap transaction payload even if the output amount doesn’t fit within the slippage parameter provided in the referenced /quote through the routeId (relevant if a new quote has to be fetched.

4. overrideSlippage : receive a /swap transaction payload even if the output amount doesn’t fit within the slippage parameter provided in /quote a aaaaassasas