/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
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
On a UTXO sell chain this may name several addresses separated by ;. This endpoint builds the transaction, so send the same list you sent to /v3/quote — send just one address here and the transaction is funded from that address alone. See Funding a swap from several addresses.
Refunds go here unless you pass refundAddress. Must be an address the user controls and can receive at, not an exchange deposit address.
destinationAddress
string
Yes
Recipient blockchain address to send the asset to. Must be a valid address for the buy asset's chain
refundAddress
string
No
Where a failed swap refunds to, on the sell chain. Overrides the value sent to /v3/quote, then falls back to it, then to sourceAddress. See Refunding to a different address.
refundAddressSetting
string
No
WARNING (default) or STRICT — what happens when the route can't honour the address. See Refunding to a different address. Ignored when no refund address applies.
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, or an off-curve Solana address. Do not use without consulting SwapKit devs first. Default: false
allowSmartContractReceiver
boolean
No
Whether to allow the destination address to be a smart contract, or an off-curve Solana address. 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
Deprecated — use slippageSetting, which supersedes it. Default: false
slippageSetting
string
No
How /v3/swap reacts when the re-priced route no longer meets the minimum it published. WARNING, STRICT or OVERRIDE — see Slippage settings. Default: WARNING.
enableSweep
boolean
No
Whether to enable max-spend sweep behaviour for UTXO assets (BTC, LTC, DOGE, BCH). Set to true to send the full spendable balance instead of exactly sellAmount when the swap would otherwise leave unspendable dust. Opt-in; if omitted, inherits enableSweep from the /v3/quote call that created the routeId. Default: false.
previousTxData
string
No
How much previous-transaction data to attach on a UTXO sell — "AUTO" (default), "ALL" or "NONE". NONE is for callers that hold the previous transactions themselves: the unsigned transaction is identical at all three values, only the PSBT's per-input signing fields change. Refused alongside enableSweep, and on Zcash. Supersedes includeNonWitnessUtxo, which is still accepted and means ALL.
gasCheck
boolean
No
Opt-in native-gas balance check for token sells (gas-asset sells are covered by insufficientBalance instead). When the wallet can't cover the network fee, the route carries an insufficientGas warning and the transaction is still returned. Inherits from /v3/quote when omitted. Default: false.
includeAttestation
boolean
No
Set to true to receive meta.nearSignedQuote, 1Click's signed quote. NEAR-routed swaps only; the field is absent unless you ask for it. Default: false.
quoteType
string
No
Re-quote the route in a different mode than the /v3/quote call used — EXACT_INPUT, FLEX_INPUT or EXACT_OUTPUT. Omit it and the route keeps the mode it was quoted in.
For example, the request could be as simple as this (this routeId will not work for you, as it has now expired):
Disabling transaction building
disableBuildTxis 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.disableBalanceChecksstill 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.
On a Chainflip route, memo is returned even under disableBuildTx. For a Bitcoin vault swap that memo is the OP_RETURN payload the deposit is attributed by, so a transaction you build yourself has to carry it — a deposit that reaches the vault without it belongs to no swap.
Slippage settings
Every /v3/swap call re-prices the route, then checks the refreshed output against two independent guards. slippageSetting governs how each one reacts:
Guard
Compares
WARNING (default)
STRICT
OVERRIDE
Published floor
Refreshed output vs the route's expectedBuyAmountMaxSlippage — the worst case /v3/quote already showed you
outputBelowPublishedFloor in warnings[], transaction still returned
409 outputBelowPublishedFloor
skipped
Deviation guard
Refreshed output vs the original quote, at more than 5% and more than $10
400 outputAmountDeviationTooHigh
400 outputAmountDeviationTooHigh
skipped
Two things the table can't show. The deviation guard runs first, so WARNING can't let a deviation breach through by also breaching the floor. And the floor check is skipped entirely on sweeps, which re-solve the sell amount — a smaller output there is correct rather than a breach.
On an EXACT_OUTPUT route neither guard applies: the buy amount is pinned, so the equivalent check runs on the sell amount and rejects with 400 inputAmountDeviationTooHigh.
Swap Response Schema
swapId
string
UUID of this specific swap response.
createdAt
string
ISO 8601 timestamp of when this swap response was built.
quoteCreatedAt
string
ISO 8601 timestamp of the underlying quote. Note the unit change from expiration, which is unix seconds as a string.
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. Warnings never block the response — tx is still returned.
meta
object
Other information about the transaction. A superset of the /v3/quote route metadata — it adds the swap-only allowance and, on routes that open a deposit channel, the deposit-channel fields.
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, optional)
How the deposit must be sent — one of simpleTransfer (plain value transfer), transferWithMemo (transfer that must include the memo), or contractCall (submit as a smart-contract / EVM transaction). Also returned by /v3/quote — the value is identical for the same routeId. Present even when no tx is built.
txType
string
(enum, optional)
The format of the returned tx. See Transaction Formats by txType. Also mirrored at meta.txType.
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.
shieldedMemo
object
(optional)
Shielded-Zcash source only. { unifiedAddress: string, uivk?: string }. Send a 0-value shielded note carrying the memo to unifiedAddress in the same transaction as the value output to inboundAddress. uivk is MAYAChain's unified incoming viewing key for decrypting the note. See Zcash shielded & unified addresses for more details.
expiration
string
(optional)
Quote deadline only — not the deposit window. Unix seconds, as a string (not ISO 8601). For most providers this is a flat quoteCreatedAt + 3600s rather than a provider-supplied value; only FLASHNET and MAYAN return their own deadline, and CHAINFLIP returns none at all. If you need to know how long a deposit channel accepts funds, use meta.depositChannelExpiration — see below.
Verifying a NEAR deposit address
Funds sent to a substituted deposit address are unrecoverable. Set includeAttestation: true and a NEAR-routed swap carries meta.nearSignedQuote — 1Click's quote response verbatim, to verify against 1Click's signature before you broadcast.
Compare
quote.depositAddressagainst where you are actually sending funds — not againsttargetAddress. The two differ on routes that swap through a DEX first.Keep a copy. 1Click treats the signed quote as the record when resolving a dispute.
The approvalTx object
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 meta.allowance field
meta.allowance
string (optional)
The sell token's current on-chain allowance for the spender this route pulls through, in base units. Usually that is meta.approvalAddress — see How the allowance is read for the exception.
"0"is a normal value — it means no allowance has been granted yet, not that the field is missing.It is not the approval signal. It's returned whether or not an approval is needed; the presence of
approvalTxremains the only "approval required" indicator. Don't derive one from the other — the two are gated separately, soallowancecan be absent on a route that still returns anapprovalTx.Omitted when an ERC-20 allowance isn't a meaningful concept for the route: native gas-asset sells, non-EVM sell chains, and deposit-channel routes (e.g. Chainflip) that move funds with a plain
transferrather than atransferFrompull.
How the allowance is read
The allowance is read live from the sell chain on every /v3/swap call — there is no cached value — and compared against this route. Two consequences worth designing around:
The comparison is amount- and spender-scoped.
approvalTxappears when the allowance is belowsellAmountfor the spender this route pulls through. A partial allowance therefore still produces anapprovalTx, and an allowance granted to a different provider's spender does not count — so switching routes can reintroduce an approval step for a token the user has already approved once. The spender is usuallymeta.approvalAddress, but not always: routes that swap in through THORChain, Chainflip or NEAR are checked against the token-transfer proxy instead.The read can trail the chain tip by a block or two. After broadcasting an approval, wait on your own confirmation rather than re-calling
/v3/swapuntilapprovalTxdisappears.
Deposit-channel fields in meta
When a route settles by opening a deposit channel, /v3/swap returns the channel's id and its deadline. These are /v3/swap only — /v3/quote never opens a channel, so they never appear in a quote response.
meta.providerDepositChannelId
string
(optional)
The provider's own id for the deposit channel, returned as soon as the channel is opened. Pass it to /track as depositChannelId to follow the swap without a transaction hash.
meta.depositChannelExpiration
number
(optional)
Unix seconds after which the channel stops accepting a deposit. This is the deadline where user funds are at stake — drive your deposit countdown from this, never from expiration.
meta.depositChannelExpirationBlock
number
(optional)
Chainflip only. The raw source-chain block the channel expires at (sourceChainExpiryBlock). Informational — depositChannelExpiration is not derived from it.
Which providers return them
CHAINFLIP / CHAINFLIP_STREAMING, deposit-channel
yes
channel open + a flat 24h
yes
CHAINFLIP vault swaps
—
—
—
NEAR
yes
provider's quote deadline
—
FLASHNET
yes
channel open + a flat 24h
—
GARDEN
yes
may be omitted
—
all other providers
—
—
—
Chainflip and Flashnet channels close after a flat 24 hours regardless of source chain, so that the network can rotate its vaults and authority sets. The deadline is computed from that fixed lifetime, not from source-chain block times.
On a multi-provider route these fields describe the channel you actually deposit into — the first leg's. When Chainflip is a later leg there is no channel for the user to deposit to, and the fields are absent.
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
A Zcash PSBT is a version 5 transaction, signed with the ZIP 244 digest — see Zcash NU7 and version 5 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:
The transaction can also use SLIP-0024 payload for verification. Reach out to use if you are interested.
Swap Errors
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
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.
refundAddressUnsupportedByRoute
Provider {provider} always refunds the sender
400
Only under refundAddressSetting: STRICT, when the route's provider can't send a refund anywhere but the on-chain sender.
refundAddressTooLongForSellChain
Refund address does not fit the {provider} memo on {sellChain}
400
Only under refundAddressSetting: STRICT. The provider carries the refund address in the swap memo and this sell chain has no room for it. Carries { provider, sellChain }.
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.
insufficientGas
Cannot build transaction. Insufficient gas balance on chain {chain}
400
EVM token sell where the node reports insufficient funds while estimating gas. Distinct from the non-blocking insufficientGas warning in warnings[], which does not fail the request.
invalidSourceAddress
Invalid source address: {address}
400
Source address validation fails (invalid format, smart contract when not allowed, or fails security checks). Also returned for an off-curve Solana source unless allowSmartContractSender: true.
invalidDestinationAddress
Invalid destination address: {address}
400
Destination address validation fails (invalid format, smart contract when not allowed, or fails security checks). Also returned for off-curve Solana destinations unless allowSmartContractReceiver: true
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. Bypassed only by slippageSetting: "OVERRIDE"
inputAmountDeviationTooHigh
Input amount deviation too high. Original: {originalAmount}, Refreshed: {refreshedAmount}, Change: {percentageChange}%
400
EXACT_OUTPUT routes only. The re-quote solved a sell amount more than 5% and more than $10 above the quoted one — with the buy side pinned, the drift lands on what the user pays. The mirror image of outputAmountDeviationTooHigh, and bypassed by the same slippageSetting: "OVERRIDE" — see Slippage settings.
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.
memoTooLongForSourceChain
Destination address is too long for the source chain's memo limit
400
Generated memo exceeds the source chain's memo capacity (e.g. a long unified refund address on a transparent source).
zcashMemoTooLong
Zcash memo exceeds the byte budget
400
Final Zcash memo exceeds its byte budget (80B transparent source / 512B shielded source).
zcashShieldedMemoUnavailable
Maya shielded memo support is unavailable
503
MAYAChain's shielded-memo config is disabled or absent when a shielded Zcash deposit is requested.
zcashTransactionFormatRetired
Zcash transaction format {format} is no longer accepted from the network upgrade at block {height}; switch to {PCZT_V5}
400
Version 4 Zcash transactions stopped being valid at the NU7 upgrade. Only reachable on a key explicitly set to PCZT or PCZT_V4 — a key that has chosen no Zcash format is served PSBT and never sees this. Ask us to move such a key to PCZT_V5.
zcashShieldedRefundMissing
Refund address missing from memo for shielded Zcash deposit
500
Safety guard: shielded-source memo produced without the refund address embedded; swap aborted to prevent unrecoverable funds.
invalidAddressForChain
Invalid address for chain
400
The derived refund address fails Zcash validation.
outputBelowPublishedFloor
Refreshed output {refreshedAmount} is below the published floor {publishedFloor}
409
The re-priced route settles for less than the expectedBuyAmountMaxSlippage the original quote published. Only raised under slippageSetting: "STRICT" — see Slippage settings.
litecoinMwebAddressUnsupported
Litecoin MWEB addresses are not supported (source|destination address {address})
400
An ltcmweb1… address was supplied as source or destination. Not waivable by disableSecurityChecks. See Litecoin MWEB addresses.
geoRestrictedToken
{asset} is not available in your region ({country})
451
A geo-restricted asset executed from a restricted jurisdiction. Re-checked here, so a route priced in a permitted region cannot be executed from a blocked one. See Tokenized equities & geo-restrictions.
Additional Notes
Quote price refresh: The quote response is cached for 5 minutes. Each
/swapcall fetches a fresh quote from the blockchain to refresh price and slippage; after 5 minutes therouteIdexpires and/swapreturns aswapRouteNotFounderror. To get the swap payload, always call/swapwith thenextActionsfrom the quote response.Balance check: By default we check if the
sourceAddresshas a sufficient balance. Since OKW is already the wallet, you can usedisableBalanceCheck: truein the body of the/swaprequest.Latency: The
/swapendpoint 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/swapcall. It also opens a deposit channel when NEAR or Chainflip providers are used, which can take up to 2.5s. SettinggasCheck: trueadds a native-balance lookup, and on TRON an extra fee estimate for low-balance wallets.Calling this endpoint should only be done after the user has selected a quote as their swap route.
The
/swapresponse also carries over some of the same fields returned by/quote, such asestimatedTime,totalSlippageBps, and thefeesbreakdown.
Some of these can be skipped by using the optional parameters listed in the request schema.
Optional /swap params:
disableBalanceCheck: skip checking thesourceAddressbalance of thefromAsset. Recommended for wallets that do this check internally.disableEstimate: skip gas estimation for EVM chains.overrideSlippage: receive a/swaptransaction payload even if the output amount doesn’t fit within the slippage parameter provided in the referenced/quotethrough therouteId(relevant if a new quote has to be fetched).gasCheck: opt in to the native-gas balance check on token sells, adding aninsufficientGaswarning when the wallet can't cover the network fee. Off by default; costs an extra balance lookup.
Last updated

