> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cosmos.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Smart Swap

> This page introduces the Smart Swap functionality provided by the Skip Go API to improve swap speed, price, and customization.

## Introduction

Smart Swap refers to a feature set that improves swap speed, price, and control.

It currently allows for:

* [External routers](#feature-use-external-routers-to-improve-price-execution) (e.g. Hallswap and Osmosis SQS) for better price execution
* [Route splitting](#feature-route-splitting) for better price execution
* [EVM swaps](#feature-evm-swaps)

<Warning>
  If you're using the deprecated `@skip-router` library, you must use version v4.0.0+ to enable Smart Swap.

  We strongly recommend using the `@skip-go/client` [TypeScript package](https://www.npmjs.com/package/@skip-go/client), which is actively maintained.
</Warning>

The rest of this document will show you how to use Smart Swap with the `@skip-go/client` library. The only changes you'll notice between this context and the REST API are naming conventions.

# Smart Swap Features

Set your Smart Swap settings in your `skipClient` function call or REST API request body.

## Feature: Use External Routers to Improve Price Execution

The Skip Go API considers multiple internal and external routers to find the route with the best price execution.

Currently supported external swap routers:

1. Skip Go API's in-house Router
2. Hallswap's Dex Aggregator
3. Osmosis's Sidecar Query Service (SQS) (Used in the Osmosis frontend)

### Usage

Pass an empty `smartSwapOptions` object into your route request.

<CodeGroup>
  ```ts TypeScript (Client) theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
  const route = await skipClient.route({
    smartSwapOptions: {}, // You're not required to activate a particular flag for this feature
    sourceAssetDenom: "uusdc",
    sourceAssetChainID: "noble-1",
    destAssetDenom: "utia",
    destAssetChainID: "celestia",
    amountIn: "1000000", // 1 uusdc
    cumulativeAffiliateFeeBPS: "0"
  }
  ```

  ```JSON JSON (REST API) theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
  // POST /v2/fungible/route
  {
    "amount_in": "1000000",
    "source_asset_denom": "uusdc",
    "source_asset_chain_id": "noble-1",
    "dest_asset_denom": "utia",
    "dest_asset_chain_id": "celestia",
    "cumulative_affiliate_fee_bps": "0",
    "allow_multi_tx": true,
    "smart_swap_options": {}
  }
  ```
</CodeGroup>

That's it! Skip Go API will now consider supported external routers and return the best available option.

## Feature: Route Splitting

Route splitting involves dividing a user's trade into multiple parts and swapping them through different pools. This reduces price impact and can increase the user's output compared to using a single route. It works especially well when one or both tokens being swapped are commonly paired with other assets on a DEX (e.g., OSMO on Osmosis).

### Usage

Pass the `splitRoutes` flag in the `smartSwapOptions` object.

<CodeGroup>
  ```ts TypeScript (Client) theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
  const route = await skipClient.route({
    smartSwapOptions: {
      splitRoutes: true
    }, // smart swap object
    sourceAssetDenom: "uusdc",
    sourceAssetChainID: "noble-1",
    destAssetDenom: "utia",
    destAssetChainID: "celestia",
    amountIn: "1000000", // 1 uusdc
    cumulativeAffiliateFeeBPS: "0"
  }
  ```

  ```JSON JSON (REST API) theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
  // POST /v2/fungible/route
  {
    "amount_in": "1000000",
    "source_asset_denom": "uusdc",
    "source_asset_chain_id": "noble-1",
    "dest_asset_denom": "utia",
    "dest_asset_chain_id": "celestia",
    "cumulative_affiliate_fee_bps": "0",
    "allow_multi_tx": true,
    "smart_swap_options": {
      "split_routes": true
    }
  }
  ```
</CodeGroup>

### Response Changes when using Split Routes

We've added a new `swapType` called `SmartSwapExactCoinIn` that's returned in the `routeResponse` and `msgsDirectResponse` when the provided route is a split route. This new `swapType` has fields that allow for multiple routes, across multiple swap venues.

```ts theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
export type SmartSwapExactCoinIn = {
  swapVenue: SwapVenue;
  swapRoutes: SwapRoute[];
};

export type SwapRoute = {
  swapAmountIn: string;
  denomIn: string;
  swapOperations: SwapOperation[];
};
```

## Feature: EVM Swaps

Smart Swap supports bidirectional EVM swaps: go from any asset on an EVM chain to any asset on a Cosmos chain and back again. With EVM swaps, users can onboard to your IBC connected chain in 1 transaction from a broad range of EVM assets, including the memecoins retail loves to hold!

Currently, the API supports EVM swapping on Velodrome (Optimism) & Aerodrome (Base), and swapping on official Uniswap V3 deployments on the following chains:

| Network      | Chain ID |
| ------------ | -------- |
| Ethereum     | 1        |
| Polygon      | 137      |
| Optimism     | 10       |
| Arbitrum One | 42161    |
| Base         | 8453     |
| BNB Chain    | 56       |
| Avalanche    | 43114    |
| Blast        | 81457    |
| Celo         | 42220    |

### Usage

Set the `evmSwaps` flag to true in the `smartSwapOptions` object. If using the deprecated `@skip-router` library, you must be on v5.1.0+ (we strongly recommend migrating to `@skip-go/client` as soon as possible).

<CodeGroup>
  ```ts TypeScript (Client) theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
  const route = await skipClient.route({
    sourceAssetDenom: "arbitrum-native",
    sourceAssetChainID: "42161",
    destAssetDenom: "ibc/8E27BA2D5493AF5636760E354E46004562C46AB7EC0CC4C1CA14E9E20E2545B5",
    destAssetChainID: "dydx-mainnet-1",
    amountIn: "10000000000000000000",
    cumulativeAffiliateFeeBPS: "0",
    smartRelay: true,
    smartSwapOptions: {
      evmSwaps: true
    },
  }
  ```

  ```JSON JSON (REST API) theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
  { // POST /v2/fungible/route
    "amount_in": "10000000000000000000",
    "source_asset_denom": "arbitrum-native",
    "source_asset_chain_id": "42161",
    "dest_asset_denom": "ibc/8E27BA2D5493AF5636760E354E46004562C46AB7EC0CC4C1CA14E9E20E2545B5",
    "dest_asset_chain_id": "dydx-mainnet-1",
    "cumulative_affiliate_fee_bps": "0",
    "allow_multi_tx": true,
    "smart_relay": true,
    "smart_swap_options": {
    	"evm_swaps": true
    },
  }
  ```
</CodeGroup>

### How do EVM Swaps Change the `route` Response?

When an EVM swap occurs in a route, a new operation of type `evm_swap` is returned in the array of `operations` in the `v2/route` and `v2/msgs_direct` response.

<Warning>
  If your API use follows the `v2/route` then `v2/msgs` call pattern, this new operation type must be passed to the `v2/msgs` endpoint, so make sure you use the latest [Skip Go Client version](https://www.npmjs.com/package/@skip-go/client) and decode the operation properly.
</Warning>

The `evm_swap` operation type is as follows:

<CodeGroup>
  ```ts TypeScript theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
  export type EvmSwap = {
    inputToken: string;
    amountIn: string;
    swapCalldata: string;
    amountOut: string;
    fromChainID: string;
    denomIn: string;
    denomOut: string;
    swapVenues: SwapVenue[];
  }
  ```

  ```JSON JSON theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
  {
    "evm_swap": {
      "input_token": "ox",   // string (token contract address if an ERC20 token, blank if native)
      "amount_in": "100",    // string
      "swap_calldata": "0x", // string
      "amount_out": "123",   // string
      "from_chain_id": "1",  // string
      "denom_in": "0x",      // string
      "denom_out": "0x",     // string
      "swap_venues": [],     // []swap_venue
    }
  }
  ```
</CodeGroup>

### How does this Change the `/msgs` and `/status` Response?

Nothing new in particular! The `msg_type` used for EVM swaps is the same `evm_tx` type used for all of our EVM transactions. Similarly, there is no new `transfer_event` type; the swap is atomic with the bridging action (Axelar or CCTP), so the same types are used (`axelar_transfer_info` and `cctp_transfer_info` respectively).

<Info>
  **Have questions or feedback? Help us get better!**

  Join [our Discord](https://discord.com/invite/interchain) and select the "Skip Go Developer" role to share your questions and feedback.
</Info>