Operational Details

Obtaining a license

To use the Totle API clients first must sign a licensing agreement with Totle (instructions here)

Submitting a Request

The curl command below shows how a client can make requests to the Totle API providing input parameters, which are listed under Inputs for each of the API endpoints in the API Documentation section below.

curl 'https://services.totlesystem.com/suggester' -X POST \

-H 'Accept: application/json, text/plain, */*' \

-H 'Content-Type: application/json;charset=UTF-8' \

--data-binary ‘{<input parameters="">}’

Setting Allowances

Clients of Totle’s API retain custody of their funds at all times (i.e. there are no trader deposits). Totle’s smart contracts move tokens directly into and out of trader wallets. In order to execute non-custodial swaps the settlement smart contracts must have permission to move ERC20 tokens directly from counterparty wallets. The ERC20 standard specifies an approve/transferFrom mechanism that DEX contracts use to accomplish this.

Trades that involve selling (i.e. spending) ERC20 tokens from the trader’s wallet will only execute successfully if the trader has first executed an approve transaction allowing the DEX settlement contract to transfer those tokens. The amount of coins that a trader allows the smart contract to spend is called an allowance. A trader making a single trade may set a fixed allowance, or, when making several trades spending the same token with the same contract, may prefer to set an infinite allowance so they don’t have to continually replenish the allowance with additional approve transactions.

Every ERC20 token that a DEX contract will transfer from the trader’s wallet requires a prior approve transaction. When trading directly with multiple DEXs an approve transaction needs to be executed for each token and each DEX. Totle simplifies this by only requiring users to approve an allowance for the Totle TokenTransferProxy Contract.

Clients who wish to sell ERC20 tokens should execute the approve method of each ERC20 token contract passing Totle’s TokenTransferProxy Contract address. If the client sets the allowance for the exact amount of tokens to sell, then it must set the allowance again each time it wishes to sell more tokens. Alternatively, clients may set an unlimited allowance once and then trade the token an unlimited amount of times without having to go through this step again.

Below is an example of how to set an unlimited allowance for the Totle TokenTransferProxy.

const contract = new web3.eth.Contract(ERC20_ABI, TOKEN_ADDRESS)

const newAllowance = String((2 ** 256) - 1)

const data = contract.methods.approve(

TOKEN_TRANSFER_PROXY_ADDRESS, newAllowance).encodeABI()

const txPromise = wallet.sendTransaction({

to: TOKEN_ADDRESS,

value: '0',

gas,

gasPrice,

data

})

Displaying a Summary

The payload returned by the getOrders API endpoint is optimized for smart contracts and not human readable. If the trader is a human being signing a transaction, it’s often helpful to display a summary of what they’re signing. For this reason, the getOrders API returns a summary of the trades that will be executed as part of the transaction. The summary JSON looks something like this:

"summary": {

"sells": [

{

"token": "0xe41d2489571d322189246dafa5ebde1f4699f498",

"exchange": "Kyber",

"price": "0.003428358245615946",

"amount": "1000000000000000000",

"fee": "0"

}

],

"buys": [

{

"token": "0x1985365e9f78359a9b6ad760e32412f4a445e862",

"exchange": "AirSwap",

"price": "0.073153949999999993",

"amount": "1000000000000000000",

"fee": "0"

}

]

}

The “sells” array enumerates the ERC20 tokens that will be transferred from the client’s wallet and the buys array enumerates the ERC20 tokens that will be transferred to the client’s wallet. Each entry includes the token identifier (see the getTokens API endpoint below for how to obtain a human readable map of these values), exchange that will perform the transfer, the price and amount.

Signing and Submitting a Transaction

After receiving a response to the getOrders API call, the payload needs to be signed and submitted to the Ethereum network for mining. Both of these things can be done using web3 library functions signTransaction and sendTransaction. For example, using the gas, ethValue, and payload fields returned from getOrders, one can construct a transaction to sign and send it as follows:

var Tx = require('ethereumjs-tx');

var privateKey = WALLET_PRIVATE_KEY;

var rawTx = {

nonce: nextNonce,

gasPrice: gas.price,

gas: gas.limit,

to: TOTLE_PRIMARY_CONTRACT_ADDRESS,

value: ethValue,

data: payload.data

}

var tx = new Tx(rawTx);

tx.sign(privateKey);

var serializedTx = tx.serialize();

web3.eth.sendSignedTransaction('0x' + serializedTx.toString('hex'))

.on('receipt', console.log);

Gas

When signing and submitting transactions for execution most wallets provide the option of setting the gas price for the transaction. In general, setting a higher gas price results in the transaction getting mined sooner because miners try to maximize their fees when constructing blocks. However, because setting a higher gas price is a common way to front-run DEX transactions, some DEXs try to combat this by setting limits on gas price. So setting a gas price above those limits will result in the transaction failing.To assist clients in determining the right gas price certain Totle API calls include a “gas” field in the response, which looks like this:

"gas": {

"price": "10000000000",

"strict": false,

"limit": "1360000"

}

The gas.price field is the suggested gas price for the payload provided. A higher gas price can be set, however, if the gas.strict flag is set to true, we strongly recommend using gas.price to prevent the transaction from failing. Our API optimizes the gas values for optimal execution.

The gas.limit field is the suggested minimum gas limit for the payload provided. It is based on the number and complexity of orders that will be settled and the Suggester’s knowledge of the average gas consumed by trades on the various DEXs. We strongly recommend setting a gas limit at or above the value for gas.limit.

API Overview

API Endpoints

Smart Contracts

Looking for something else? Send us your feedback.