API Endpoints

getOrders

POST /

This endpoint takes a set of trade criteria expressed as buys and sells and returns a transaction payload that can be submitted to the blockchain for settlement. Clients can optionally white list or black list specific exchanges using the “exchanges” input parameter.

Inputs

address - string - the wallet address to transfer tokens to/from
exchanges (optional) - array - specifies exchanges to white or black list

list - array - the ids of the exchanges to white/black list (see the getExchanges API endpoint for a mapping)

type - string ("white" or "black") - tells whether to white or black list the exchanges

buys - array - lists the trades where the user acquires tokens for ETH

sells - array - lists the ERC20 tokens the user is selling for ETH

The objects in both buys and sells arrays have the following properties:

token - string - identifier of the token to acquire (see the getTokens API endpoint for a mapping)

amount - integer - the amount of the token to acquire

isOptional (optional) - boolean (default false) - tells if a trade can be skipped

minFillPercent - integer (optional, default 100) - minimum percentage of the amount to be filled that is acceptable. When orders fail and Totle can still fill some of the orders, this percentage determines whether or not enough orders have been filled for the transaction to succeed. The actual minimum threshold also takes into account minSlippagePercent (described below). For example if minFillPercent=80 and minSlippagePercentage=5, then the minimum threshold for success is 75%.

minSlippagePercent - integer (optional, default 3) - minimum percentage of slippage (versus the quoted price) that the client is willing to accept
breakdown - boolean (optional, default false) - when true the API returns extra information about the trades

breakdown - boolean (optional, default false) - when true the API returns extra information about the trades

Example request

{

"address": "0xD18CEC4907b50f4eDa4a197a50b619741E921B4D",

"exchanges": { // optional, default: search all exchanges

"list": [ 4, 7 ],

"type": "black" // or "white"

},

"buys": [

{

"token": "0x1985365e9f78359a9b6ad760e32412f4a445e862",

"amount": "1000000000000000000"

}

],

sells": [

{

"token": "0xe41d2489571d322189246dafa5ebde1f4699f498",

"amount": "1000000000000000000",

"isOptional": true, // default: false

"minFillPercent": 85, // default: 100

"minSlippagePercent": 1 // default: 3

}

],

"breakdown": true // Get extra debugging information for each trade

}

Outputs

contractAddress ​- the address of the Totle’s Primary Smart Contract that transactions are sent to.

ethValue ​- the total amount of Ether (in Wei) that will need to be transferred from the user’s wallet in order to fill all the orders.

summary ​- user readable details of all the orders that the Suggester has found. The summary provides information for each buy and sell order. The buys and sells fields each contain an array of orders with the following information

token - string - identifier of the token to buy/sell (see the getTokens API endpoint for a mapping)

exchange - the name of the DEX that will settle the trade

price - the expected exchange rate (exact for limit orders)

amount - the amount of the token that will be bought/sold

fee - additional fees charged by the DEX (if any). For buys, the fee is denominated in ETH but for sells it is denominated in the token that is being sold

payload ​- the set of orders encoded in smart contract readable form (data) and optionally human readable form (breakdown).

data - the data that is signed and sent as a transaction to the Totle Primary Smart Contract, which executes the orders.

breakdown - a human readable list of order details is returned if breakdown was set to true on the input

Example response

{

"success": true,

"response": {

"contractAddress": "0x55251f1733c0004c3e86ec39893d782c8bc50fe0",

"ethValue": "71817359507015568",

"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"

}

]

},

"payload": {

"data": "0xa4ead2b5000000",

"breakdown": [

{

"isSell": true,

"tokenAddress": "0xe41d2489571d322189246dafa5ebde1f4699f498",

"tokenAmount": "1000000000000000000",

"optionalTrade": true,

"minimumExchangeRate": "3325507498247468",

"minimumAcceptableTokenAmount": "850000000000000000",

"orders": [

{

"exchangeHandler": "0x8Ce714e6F9fF6bCD36",

"genericPayload": "0x0000000000000000000e"

},

{

"exchangeHandler": "0xAC025aB3de12",

"genericPayload":

"0x000000000000000"

}

]

},

{

"isSell": false,

"tokenAddress": "0x1985365e9f78359a9b6ad760e32412f4a445e862",

"tokenAmount": "1000000000000000000",

"optionalTrade": false,

"minimumExchangeRate": "13259707780646159132",

"minimumAcceptableTokenAmount": "970000000000000000",

"orders": [

{

"exchangeHandler": "0xAC025aB3de12",

"genericPayload": "0x000000000000000000000000155f8"

}

]

}

]

},

"gas": {

"price": "10000000000",

"strict": false,

"limit": "1360000"

}

}

}

getTokens

This endpoint provides a map of human readable token names to contact addresses that are used as inputs and outputs to other endpoints to identify tokens by their contract address.

GET / tokens

Inputs

None

Outputs

tokens - the list of all known ERC20 tokens including their names, addresses, and other information

name - the long name of the token

symbol - the ticker symbol of the token

address - the contract address that should be used to identify the token in all API calls

decimals - the number of decimal places implemented by the token

tradable - true if the token can be traded on DEXs

Example response

{

"tokens": [

{

"name": "Student Coin",

"symbol": "STU"

"address": "0x0371a82e4a9d0a4312f3ee2ac9c6958512891372",

"decimals": 18,

"tradable": true

},

{

"name": "Zilliqa",

"symbol": "ZIL"

"address": "0x05f4a42e251f2d52b8ed15e9fedaacfcef1fad27",

"decimals": 12,

"tradable": true

},

// ....

]

}

getExchanges

This endpoint provides a map of human readable token names to contact addresses that are used as inputs and outputs to other endpoints to identify tokens by their contract address.

GET / exchanges

Inputs

None

Outputs

id - the identifier for the exchange that should be used in all API calls (e.g. to black or white list an exchange)name - the commonly used name of the exchange

Example Response

{

"exchanges": [

{

"id": 1,

"name": "EtherDelta",

},

{

"id": 2,

"name": "Kyber",

},

// …

}

API Overview

Operational Details

Smart Contracts

Looking for something else? Send us your feedback.