API overview

The Totle API gives you a simple, efficient, and cost-effective way to exchange multiple ERC-20 tokens in a single atomic transaction. You can use the Totle API to:

  • Return prices for all token trading pairs on all exchanges
  • Find the best prices for a given ERC-20 token across multiple decentralized exchanges, retrieve a set of orders that will satisfy trade criteria, and settle those orders atomically
  • Swap a specified amount of one token for an amount of another token type that is equal in value

Sample use case #1: Rebalancing

Say the client wishes to rebalance their portfolio by acquiring 10 BAT tokens, 20 OMG tokens, and 30 ZIL tokens with ETH. They can send those trade criteria to Totle’s rebalance API endpoint, and the Totle backend will send back a transaction payload containing a set of orders that will sell ETH for BAT, OMG, and ZIL on various exchanges.

If the client signs the payload with the private key controlling the ETH and submits the signed transaction to the Ethereum network, the Totle smart contract system will execute the trades on the various exchanges until the criteria is satisfied.

Sample use case #2: Swapping

Say the client has 10 ETH tokens, and they want to swap these for as many BAT tokens as possible.  The user can send a request to Totle’s swap endpoint, indicating they want to swap 10 ETH tokens in exchange for however many BAT tokens it takes to equal the value of the 10 ETH tokens.

The Totle backend will calculate the amount of BAT tokens that can be acquired given the current pricing and execute the trade if possible.

Outcomes

Since trades are executed as a single Ethereum transaction, there are only two possible outcomes:

  • The transaction succeeds, and the client’s trade criteria are satisfied
  • The transaction fails, and no tokens are transferred

Clients don’t need to worry about acquiring intermediate tokens required to facilitate the trades (e.g., WETH, ZRX, etc.) because the backend includes orders to acquire them in the payload as well.

Backend Integration with DEXs

Totle’s backend integrates with many leading DEXs, which allows it to find liquidity and the best prices for ERC20 tokens available across decentralized exchange landscape.

The Totle API provides a uniform interface to trading on heterogeneous DEXs that have different matching and settlement schemes. It does this by maintaining a local aggregated set of signed limit orders from order book based systems such as 0x and Ether Delta and performing real-time price discovery for market maker DEXs such as Bancor and Uniswap.

Unlike limit orders, the exact prices on market maker DEXs aren’t known a priori and will change with the size of the order. However, Totle’s backend has enough information and intelligence to compare market and limit orders and choose the ones that will result in the best prices for the client.

Totle is also integrated with dynamic matching DEXs (e.g., Airswap) where prices have to be negotiated in real time with the counterparty. Totle’s backend performs these negotiations and can compare these prices with limit and market orders from other exchanges. Doing this enables Totle’s matching system to combine real-time price information and aggregated order books to find the best available prices across a diverse set of DEXs.

Features and Functionality

The first version of the Totle API described here provides the minimal amount of functionality to enable atomic swaps involving multiple DEXs and tokens. It will be expanded in the future to support other features and use cases.

Executing Trades

Figure 1. Provides an overview of how an API client can use the Totle API to execute a set of trades involving multiple DEXs and/or tokens in a single atomic transaction.

Figure 1. Flow of API calls to find and settle trades

To find and execute multiple trades atomically API clients follow a basic two step process execute trades.

  • get orders to fill - An API client will submit a request to the rebalance API including the tokens they wish to buy and the tokens they wish to sell. The Suggester Engine then calculates the best way to execute the buys and sells using its aggregated order books and real time price information. It sends back a response containing a signable transaction payload consisting of orders that will be settled on the blockchain in step 2.
  • submit signed orders - the client digitally signs the payload returned in step 1 with the private key for the wallet and sends it to the Ethereum network. The Totle Primary Contract translates the payload into a set of subtransactions that are executed on the exchanges that are involved. Those exchanges execute transfers in the ERC20 contracts involved in each trade.

Looking for something else? Send us your feedback.