/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 (it is cached for 5 minutes), 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
disableBuildTx	boolean	No	Whether to skip providing a built transaction, ready to sign by the wallet.
disableBalanceCheck	boolean	No	Whether to skip balance validation. If false or omitted, checks that source address has sufficient balance. Do not use without consulting SwapKit devs first. 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. Do not use without consulting SwapKit devs first. Default: false
allowSmartContractReceiver	boolean	No	Whether to allow the destination address to be a smart contract. Do not use without consulting SwapKit devs first. 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
disableSweep	boolean	No	Whether to disable max-spend sweep behaviour for UTXO assets (BTC, LTC, DOGE, BCH). Set to true to send exactly sellAmount and pay the fee separately instead. 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.

For example, the request could be as simple as this (this routeId will not work for you, as it has 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 fresh quote is fetched on every /swap call to refresh price and slippage. Route IDs are cached for 5 minutes If the routeId is older than 5 minutes, it will not be cached anymore and won't be recognized by the swap endpoint.

Disabling transaction building

• disableBuildTx is the most effective filter. Data on where to send the tokens to swap will be provided, but the transaction building won't be performed. This avoids all balance checks and errors derived from it.

• disableBalanceChecks still tries to build a transaction without checking the balance of the address. This works on some chains, like EVM, but will fail on UTXO chains because building a transaction requires checking the balance (the flag is not applied).

Using them together ensures no errors from wallet balance or other transaction building errors are returned. This is only recommended for advanced integrations, where you are sure you can build the transaction yourselves.

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 (optional)	For EVM sell chain. When a token approval transaction is required to be submitted before the tx can be broadcasted. See below for more details.
targetAddress	string (optional)	The address the swap transaction targets — a DEX aggregator/router contract for EVM swaps, or the inbound vault address for non-EVM cross-chain swaps. Optional: it is omitted for deposit-channel routes (e.g. Chainflip), where the send destination comes from the deposit address in meta or is resolved during tx building instead.
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.
routeId	string	UUID of the specific route this swap was built from — the same routeId returned by /v3/quote and passed back in the /v3/swap request.
sourceAddress	string	Blockchain address to send the asset from.
destinationAddress	string	Recipient blockchain address to send the asset to.
txHint	string (enum)	Hint for how to broadcast the returned tx. One of simpleTransfer (plain value transfer), transferWithMemo (transfer that must include the memo), or contractCall (submit as a smart-contract / EVM transaction).
inboundAddress	string (optional)	For deposit/memo-based providers, the protocol's inbound vault address that funds are sent to. Present only when the route settles via an inbound deposit rather than a direct contract call.
expiration	string (optional)	Timestamp after which this quote/swap is no longer valid. Returned only by providers that supply a quote deadline. Omitted for providers that don't.

The approvalTx object

Field	Type	Description
approvalTx.to	string	Token contract address to send the approval
approvalTx.from	string	User wallet address.
approvalTx.value	string	ETH value — always "0" for approvals.
approvalTx.data	string	Encoded approve() call data.
approvalTx.gasLimit	string	Estimated max gas units for the approval transaction, as a hex quantity string
approvalTx.gasPrice	string	Gas price in wei per gas unit, as a hex quantity string. Legacy (type-0) gas pricing.

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 (including 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 might look like this. In this case, it's a simple transfer without any contract involved:

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

The transaction can also use SLIP-0024 payload for verification. Reach out to use if you are interested.

---

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 with overrideSlippage: 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 cached for 5 minutes. Each /swap call fetches a fresh quote from the blockchain to refresh price and slippage; after 5 minutes the routeId expires and /swap returns a swapRouteNotFound error. To get the swap payload, always call /swap with the nextActions from the quote response.

• Balance check: By default we check if 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. It builds the transaction payload, including fetching UTXOs and building PSBT when required, performs a balance check, and automatically runs address screening on every /swap call. It also opens a deposit channel when 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.

• The /swap response also carries over some of the same fields returned by /quote, such as estimatedTime, totalSlippageBps, and 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 .