Welcome to Totle’s Developer Portal!

Find all of the resources you need to tap into Totle’s DEX liquidity network. Understand Totle’s smart contract architecture, how to earn fees, and how to configure Totle’s powerful API to make the most out of your trading experience.

Totle’s 2 Step Integration 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.


How do I sign transactions?

To sign a Totle transaction (tx), a developer should first understand how to digest Totle’s Swap API response. The API response will include a tx object in the following format:

"tx": {

"to": "0x0d8775f648430679a709e98d2b0cb6250d2887ef",
"from": "0x5c1739f2a9dcb46e5c2fbac81300af6369e167ef",
"data": "0x...ff",
"gasPrice": "15001500000",
"gas": "47233",
"nonce": "7"


This tx object is ready to be signed using the private key pair to the public key that made the request to Totle’s API.
If you haven’t already found a wallet provider for your integration, you can use the standard web3 library and call a `sendTransaction` function, including the tx object above as the argument. More details can be found here.

How do I make an allowance to Totle’s Smart Contract?

Setting allowances to smart contracts is a tedious process, especially when you’re trying to trade across a multitude of protocols. Totle has designed their system to take one time allowances through a proxy contract, so that developers don’t need to maintain multiple allowances.

An allowance is exactly what it sounds like - you agree to allow Totle’s smart contract to move funds from your wallet to a DEX smart contract to execute an atomic swap.

Totle’s API will check if the public address calling the API has set an allowance yet. If it has not, the API response will include 2 tx objects - the first being for the allowance, and the second being for the swap tx. You need to sign and submit both of these transactions to the Ethereum network.

How do I earn fees?

Totle has implemented a trustless mechanism for developers to earn fees. Simply login to Totle Console with your Metamask extension, and deploy as many fee contracts as you wish. Once the fee contract has been deployed, you can find it’s contract address in the Console and pass it along as a parameter with every API call you make to Totle.

Totle transactions take 2 forms - either we find a direct market route from Token A → Token B, or we go from Token A → Token C → Token B.

Transactions going directly from Token A → Token B earn fees for Totle and developers in Token B. Transactions going from Token A → Token C → Token B earn fees in Token C.

For example, a 0.5 ETH → 100 DAI trade where Totle and the developer both earn 0.25% will result in 0.25 DAI being earned by both Totle and the developer.

What are Totle’s fees?

Totle earns a 0.25% minimum on the value of every transaction. We’ve implemented such a fee for a multitude of reasons that we believe are competitive to our strategy.

To attract market makers to our platform, we’re implementing a fee that gives us room to share revenues with market makers. This will bring more price competitiveness to Totle and our clients, saving you more money at the end of the day.

How do I know how much gas to use for any given transaction?

Totle’s API prefills gas price and gas limits for our clients so they don't have to. Although developers can change these fields when submitting their txs to the network, we strongly recommend against this practice. We’re carefully designing gas parameters that are dynamic to every trade and guarantee the highest success rate. 

What are Totle’s gas costs versus going directly to a DEX?

Totle’s gas costs are more expensive than going directly to a DEX. Totle saves money by finding the best price across all DEX markets, and has employed other mechanisms increasing the tx success rate, such as backup orders in the event a primary order has been taken by another taker during block settlement times.

Does Totle have a market making program for market makers?

As alluded to in a previous FAQ, Totle is designing market maker incentive programs to bring more price competitive quotes to Totle takers. The details of this program are still in development, but one can expect rebate mechanisms favouring more settled txs and exclusive liquidity.

How does Totle deal with front-running on DEXs?

Totle and their partners work diligently to combat front-running by employing mechanisms that increase transaction success rates in the event primary orders are taken. Some of our integrated exchange partners set gas limits that Totle abides by. This makes it difficult for malicious takers to outbid resting orders in the mempool that are pending to be included in the next available block. Totle also includes backup orders in the payload returned by the API that we can fall back to if a primary order is taken.

Does Totle have a referral program?

Yes! You can deploy a partner fee contract using Totle Console. Once you’ve deployed the fee contract, you can refer users to Totle Swap using the URL format swap.totle.com/p/`yourPartnerContractAddress`. Any transactions going through Totle on this link will earn you the fee you specified when you deployed the fee contract.