# /v3/swap - Obtain swap 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

<table><thead><tr><th width="244">Parameter</th><th width="92">Type</th><th width="96">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>routeId</code></td><td><code>string</code></td><td>Yes</td><td>The ID of the route to swap. Obtained from a previous <code>/v3/quote</code> response</td></tr><tr><td><code>sourceAddress</code></td><td><code>string</code></td><td>Yes</td><td>Blockchain address to send the asset from. Must be a valid address for the sell asset's chain</td></tr><tr><td><code>destinationAddress</code></td><td><code>string</code></td><td>Yes</td><td>Recipient blockchain address to send the asset to. Must be a valid address for the buy asset's chain</td></tr><tr><td><code>disableBuildTx</code></td><td><code>boolean</code></td><td>No</td><td>Wheter to skip providing a built transaction, ready to sign by the wallet.</td></tr><tr><td><code>disableBalanceCheck</code></td><td><code>boolean</code></td><td>No</td><td>Whether to skip balance validation. If <code>false</code> or omitted, checks that source address has sufficient balance. Do not use without consulting SwapKit devs first. Default:<code>false</code></td></tr><tr><td><code>disableEstimate</code></td><td><code>boolean</code></td><td>No</td><td>Whether to skip on-chain gas estimation when building the transaction. Default: <code>false</code></td></tr><tr><td><code>allowSmartContractSender</code></td><td><code>boolean</code></td><td>No</td><td>Whether to allow the source address to be a smart contract. Do not use without consulting SwapKit devs first.  Default: <code>false</code></td></tr><tr><td><code>allowSmartContractReceiver</code></td><td><code>boolean</code></td><td>No</td><td>Whether to allow the destination address to be a smart contract. Do not use without consulting SwapKit devs first. Default: <code>false</code></td></tr><tr><td><code>disableSecurityChecks</code></td><td><code>boolean</code></td><td>No</td><td>Whether to bypass address format validation and security checks. Default: <code>false</code></td></tr><tr><td><code>overrideSlippage</code></td><td><code>boolean</code></td><td>No</td><td>Whether to bypass the 5% output amount deviation check when the quote is refreshed. Default: <code>false</code></td></tr></tbody></table>

{% hint style="warning" %}
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.
{% endhint %}

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

{% tabs %}
{% tab title="cURL" %}

```sh
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"
}'
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
A quote is valid for one minute. If the routeId specified is older than one minute, a new quote will be fetched to refresh the price and slippage.\
If the `routeId` is older than 5 minutes, it is not cached anymore and won't be recognized by the swap endpoint.
{% endhint %}

#### 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

<table><thead><tr><th width="271">Field</th><th width="85">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>swapId</code></td><td><code>string</code></td><td>UUID of this specific swap response.</td></tr><tr><td><code>providers</code></td><td><code>array</code></td><td>List of providers available for this route (<code>CHAINFLIP</code>, <code>THORHCAIN</code>etc.).</td></tr><tr><td><code>sellAsset</code></td><td><code>string</code></td><td>The asset being sold (e.g., <code>“ETH.ETH”</code>).</td></tr><tr><td><code>buyAsset</code></td><td><code>string</code></td><td>The asset being bought (e.g., <code>“BTC.BTC”</code>).</td></tr><tr><td><code>sellAmount</code></td><td><code>string</code></td><td>Amount of the sell asset in smallest units.</td></tr><tr><td><code>expectedBuyAmount</code></td><td><code>string</code></td><td>Estimated amount of the buy asset to be received.</td></tr><tr><td><code>expectedBuyAmountMaxSlippage</code></td><td><code>string</code></td><td>Worst-case buy amount considering max slippage.</td></tr><tr><td><code>tx</code></td><td>varies</td><td>Explained below</td></tr><tr><td><code>approvalTx</code></td><td><code>object</code></td><td>For EVM sell chain. When a token approval transaction is required to be submitted before the <code>tx</code> can be broadcasted.</td></tr><tr><td><code>targetAddress</code></td><td><code>string</code></td><td>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 <code>tx</code> we return, unless you are an advanced user.</td></tr><tr><td><code>memo</code></td><td><code>string</code></td><td>Optional. Memo with instructions for swap.</td></tr><tr><td><code>fees</code></td><td><code>array</code></td><td>List of fees applied to the swap (inbound, network, affiliate, service).</td></tr><tr><td><code>estimatedTime</code></td><td><code>object</code></td><td>Estimated time for different phases of the swap.</td></tr><tr><td><code>totalSlippageBps</code></td><td><code>number</code></td><td>Expected total slippage.</td></tr><tr><td><code>legs</code></td><td><code>array</code></td><td>The different involved steps in the swap.</td></tr><tr><td><code>warnings</code></td><td><code>array</code></td><td>Potential warnings about this swap provider.</td></tr><tr><td><code>meta</code></td><td><code>object</code></td><td>Other information about the transaction. </td></tr><tr><td><code>nextActions</code></td><td><code>object</code></td><td>Data about next request to make in the flow.</td></tr></tbody></table>

#### &#x20;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.&#x20;

* 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:

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

***

### **Swap Errors**

<table><thead><tr><th width="179">Field</th><th width="154">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>provider</code></td><td><code>string</code></td><td>Specific provider name</td></tr><tr><td><code>errorCode</code></td><td><code>string</code></td><td>One of the possible error codes listed below.</td></tr><tr><td><code>message</code></td><td><code>string</code></td><td>Message related to the error.</td></tr></tbody></table>

#### **Error codes and messages**

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

***

### 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.&#x20;

  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.&#x20;

Some of these can be skipped by using the optional parameters listed in the [request schema](#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` &#x20;