Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

/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 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):

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.

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.

overrideSlippage: true still works and still means OVERRIDE, but it's deprecated. When both are sent, slippageSetting wins.

Swap Response Schema

Field
Type
Description

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.depositAddress against where you are actually sending funds — not against targetAddress. 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

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 meta.allowance field

Field
Type
Description

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 approvalTx remains the only "approval required" indicator. Don't derive one from the other — the two are gated separately, so allowance can be absent on a route that still returns an approvalTx.

  • 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 transfer rather than a transferFrom pull.

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. approvalTx appears when the allowance is below sellAmount for the spender this route pulls through. A partial allowance therefore still produces an approvalTx, 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 usually meta.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/swap until approvalTx disappears.

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.

Field
Type
Description

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

Route
Channel id
Expiration
Expiration block

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.

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

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.

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 /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. Setting gasCheck: true adds 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 /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. gasCheck : opt in to the native-gas balance check on token sells, adding an insufficientGas warning when the wallet can't cover the network fee. Off by default; costs an extra balance lookup.

Last updated