Skip to content

Latest commit

 

History

History
215 lines (156 loc) · 7.17 KB

smart-swap-options.mdx

File metadata and controls

215 lines (156 loc) · 7.17 KB
title description
Smart Swap
This page introduces the Smart Swap functionality provided by the Skip API to improve swap speed, price, and customization.

Introduction

Smart Swap refers to a broad range of functionality we're building out to improve swap speed, price, and customization.

At this time, the main use case for smart swap is improving trade execution price by enabling third-party routers (e.g. Hallswap) and trade splitting. But much more is on the way!

This doc covers:

  • All the different features Smart Swap enables
  • Describes how to use each of them
**`@skip-router` 4.0.0+ required**

If you're using the @skip-router library, you must use v4.0.0 or later to use Smart Swap.

How to Use Smart Swap

All Smart Swap features are controlled with a single configuration object:

  1. @skip-router library: smartSwapOptions object passed inSkipRouter.route options SkipRouter.msgsDirect options
  2. REST API: smart_swap_options parameter passed in /v2/fungible/route and /v2/fungible/msgs_direct

Read on for more info about the individual features and how to use each of them.

(For the rest of this doc, examples will show how to use Smart Swap with the @skip-router library by configuring it on SkipRouter.route. The only changes you'll notice between this context and the REST API is naming conventions)

Smart Swap Features

Feature: Use 3rd-party routers to improve price

What is it

The Skip API searches over multiple 1st and 3rd-party routers to find the route that gives you best execution. This has a chance of improving the price at which your user's swap executes.

The swap routers currently supported are:

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

How to use it

Just pass the smartSwapOptions object into your route request. You're not required to activate a particular flag.

const route = await skipClient.route({
  smartSwapOptions: {}, // smart swap object
  sourceAssetDenom: "uusdc",
  sourceAssetChainID: "noble-1",
  destAssetDenom: "utia",
  destAssetChainID: "celestia",
  amountIn: "1000000", // 1 uusdc
  cumulativeAffiliateFeeBPS: "0"
}

That's it! Skip API will now consider all routers we have available and give your user the best one.

Feature: Route Splitting

What is it

Route splitting is a technique in swap optimization where a user's trade is split into several parts and swapped through separate pools. It can help lower price impact and increase output for the user, compared to swapping with a single route. This technique is especially effective when one or both of the tokens the user is swapping is a commonly paired asset on a DEX (e.g. OSMO is paired with almost everything on Osmosis).

How to use it

Just pass the splitRoutes flag in the smartSwapOptions object.

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"
}

Feature: EVM Swaps

What is it

The API supports swapping on an EVM chain, followed by a CCTP/Axelar transfer over to the Cosmos ecosystem. This allows a user to onboard on 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 swapping on official Uniswap V3 deployments on the following chains (and their respective chain IDs):

  1. Ethereum (1)
  2. Polygon (137)
  3. Optimism (10)
  4. Arbitrum One (42161)
  5. Base (8453)
  6. BNB Chain (56)
  7. Avalanche (43114)
  8. Blast (81457)
  9. Celo (42220) - SOON

How to use it

Just set the evmSwaps flag to true in the smartSwapOptions object. If using the @skip-router library, you must be on version 5.1.0 or above.

```text TypeScript 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 }, } ``` 
{
  "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
  },
}

What to expect from the route response

When an EVM swap occurs in a route, a new operation type evm_swap is returned in the array of operations in the v2/route and v2/msgs_direct responses. If your API usage 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 are on the latest router SDK version and/or are decoding the operation properly. The evm_swap operation type is as follows:

export type EvmSwap = {
  inputToken: string;
  amountIn: string;
  swapCalldata: string;
  amountOut: string;
  fromChainID: string;
  denomIn: string;
  denomOut: string;
  swapVenues: SwapVenue[];
}

{
  "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
  }
}

What to expect differently from the /msgs and /status responses

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 to be aware of, since the swap is atomic with the bridging action (Axelar or CCTP), the same types are used (axelar_transfer_info and cctp_transfer_info respectively).

Response Changes using Smart Swap

We've added a new swapType called SmartSwapExactCoinIn you can expect to be returned in the routeResponse and msgsDirectResponse to take advantage of the new capabilities Smart Swaps offers! This new swap type has fields that allow for multiple routes, across multiple swap venues.

  • Note: this new SmartSwapExactCoinIn type will currently only be returned if the route provided back is a split route.
export type SmartSwapExactCoinIn = {
  swapVenue: SwapVenue;
  swapRoutes: SwapRoute[];
};

export type SwapRoute = {
  swapAmountIn: string;
  denomIn: string;
  swapOperations: SwapOperation[];
};
**Want to help us get better? Have questions or feedback?**

You can reach us easily by joining our Discord and grabbing the "Skip API Developer" role.