Totle API

Totle API Developer Hub

Welcome to the Totle API docs!

Get Started

API Overview

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

  • Find the best prices for a given ERC20 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
  • Send payments to a designated recipient

Backend Integration with DEXs

Totle’s backend integrates with leading DEXs, allowing it to find liquidity and the best prices for ERC20 tokens available.

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 (e.g., 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 you.

Totle also integrates 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 compares prices against 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.

Sample Use Cases

The following use cases demonstrate how the /swap and /pay endpoints can be used.

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 /swap endpoint using the swaps array of objects, 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.

Sample use case #3: Making Payments

Say the client has BAT tokens, and they want to pay the recipient in OMG. The recipient can be either a wallet or a Smart Contract. The user can send a request to Totle's pay endpoint, indicating that they would like to pay $9 worth of OMG.

However, due to fluctuations in prices, the client also needs to provide the maximum amount of BAT they're willing to spend to send $9 worth of OMG.

Totle's system settles the trade using ETH as the base pair. In this example, Totle will:

  1. Sell the maxSource amount of BAT tokens for ETH
  2. Use the ETH acquired in step 1 to acquire $9 worth of OMG

Any excess funds (in the form of ETH) from the trade will be sent back to the client initiating the transaction.


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

  1. The transaction succeeds, and the client’s trade criteria are satisfied
  2. 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.

Executing Trades

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

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

Finding and executing multiple trades atomically is a two-step process:

  1. Get orders to fill: The client submits a request to the /swap endpoint that includes the tokens they want to buy and sell. Totle's Suggester calculates the best way to execute the buy and sell transactions using its aggregated order books and real-time price information. Suggester returns a response to the client that contains a signable transaction payload consisting of orders that can be settled on the blockchain.

  2. Submit signed orders: The client digitally signs the transaction payload returned by Suggester and sends it, along with the private key for the appropriate wallet, to the Ethereum Network. The Totle Primary Contract translates the payload into a set of sub-transactions that execute on the involved exchanges. These exchanges execute transfers in the ERC-20 contracts for each trade.

Updated 5 months ago

API Overview

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.