V2 Migration Guide

In this guide, we explore the key updates introduced with Odos V2. Notably, it includes new features that enhance the functionality and performance of your API usage. At the same time, some changes will be required to adapt to this new version. The guide is designed to help you understand these modifications and smoothly transition to Odos V2, ensuring that you can make the most of these new capabilities.

Breaking Changes

/sor/quote deprecation

In order to support new features and to better version our API going forward, we are deprecating /sor/quote in favor of /sor/quote/{version}. For the migration to V2, you will need to change your usage of the quote endpoint to /sor/quote/v2.

The input parameters for this endpoint have changed slightly. For the inputTokens amount parameter, we previously supported both integer and string inputs. We now only allow for string inputs. You will need to stringify the token amount before making a quote request.

The /sor/assemble endpoint is exactly the same and is not versioned.

/sor/swap deprecation

We are removing the swap endpoint to reduce the number of fully assembled transactions we are creating that are never executed. We ask that /sor/assemble is only called when you have a quote that you are expecting to execute. Previously, swap was a meta endpoint for calling quote and assemble in a single HTTP call.

Please refactor to call /sor/quote/v2 and only assemble quotes when a transaction is intended to be executed. Refer to the Quick Start Guide if you have any questions.

/info/contract-info/{chain_id} deprecation

Just like the quote endpoint, we are deprecating the unversioned contract-info endpoint in favor of a versioned one. The response is exactly the same. The only change is the version path parameter. It should be safe to find and replace all usage of /info/contract-info/ with /info/contract-info/v2.

New API Features

Referral Codes

Odos V2’s powerful new feature, referral codes, allows partners to track volume and monetize through the quote/v2 API. By registering a referral code, partners can optionally add a fee - 80% of which will be transferred to them during the swap, with 20% retained by the protocol. Even without monetization, partners can still register a code for potential future benefits from Odos.

Refer to the Referral Code documentation for more information about this feature.

Compact Call Data

In order to make L2’s even better for Odos, we’ve created compact call data which aims to reduce the cost of transactions on L2 rollups. This uses custom decoder written in yul to allow for significantly less calldata to be necessary to describe the swap than the normal endpoints. Although yul typically has low readability, security assumptions for these two functions are low since they make a call to the same internal function that is callable with arbitrary parameters via the normal endpoint.

When requesting a quote using the /sor/quote/v2 endpoint, you can optionally request regular or compact call data using the compact parameter. The default value is true.

Like-asset Routing

We’re excited to announce the new ‘Like-Asset Routing’ feature in our service. When enabled, this feature checks if the assets being traded are pegged to the same underlying. If so, it restricts routing through those like assets, significantly reducing the potential for slippage. This allows users to set a much tighter slippage tolerance. However, please note that this might restrict liquidity and may result in an equal or worse quote. Please note that this feature won’t affect volatile pairs (where the two assets are of different types), and can be left on if a user wants this enhanced stable token trading experience.