API Endpoints

tokens

GET /tokens

curl 'https://services.totlesystem.com/tokens' -X GET

Returns a map of token names to contact addresses.

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 Totle

Sample response

{

"tokens": [

{

"name": "Student Coin",

"symbol": "STU"

"address": "0x0371a82e4a9d0a4312f3ee2ac9c6958512891372",

"decimals": 18,

"tradable": true

},

{

"name": "Zilliqa",

"symbol": "ZIL"

"address": "0x05f4a42e251f2d52b8ed15e9fedaacfcef1fad27",

"decimals": 12,

"tradable": true

},

// ....

]

}

prices

GET /tokens/prices

curl 'https://services.totlesystem.com/tokens/prices' -X GET

Returns prices for all token trading pairs on all exchanges. Prices are updated at 1-minute intervals.

Inputs

None

Outputs

success - boolean - indicates whether the API call was successful or not. If not, the returned value equals false and is accompanied with an error message.

response - object - list of token-exchange info. For each token, a list of exchanges and bid/ask prices are given.

token exchange info - string - identifier of the token to which each exchange info applies (see the tokens API endpoint for a mapping)

exchange info - string - maps to the identifier of the exchange (see the exchanges API endpoint for a mapping)

bid - string - price in ETH a buyer is willing to buy the given token for on the exchange

ask - string - price in ETH a seller is willing to sell the given token for on the exchange

Sample response

{

"success": true,

"response": {

"0x41e5560054824ea6b0732e656e3ad64e20e94e45": {

"1": {

"bid": "0.000410511000000",

"ask": "0.000870000000000"

},
"2": {

"bid": "0.000464697638862",

"ask": "0.000470803740502"

},
},"11": {

"bid": "0.000185210252459",

"ask": "0.008855340398728"

},
// ...

}

}

}

exchanges

GET /exchanges

curl 'https://services.totlesystem.com/exchanges' -X GET

Returns a map of exchange names to exchange IDs.

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

Sample Response

{

"exchanges": [

{

"id": 1,

"name": "EtherDelta",

},

{

"id": 2,

"name": "Kyber",

},

// …

}

rebalance

POST /rebalance

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

-H 'Accept: application/json, text/plain, */*' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-binary ‘{<input parameters>}’

Accepts trade criteria expressed as buys and sells. Returns a transaction payload that can be submitted to blockchain for settlement.

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 exchanges API endpoint for a mapping)

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

affiliateContract (optional) - string - the address of the affiliate contract you want to use to collect fees

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

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

amount - integer - the amount of tokens to acquire in the token's base unit of decimals

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

minFillPercent - number (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 - number (optional, default 3) - minimum percentage of slippage (versus the quoted price) that the client is willing to accept

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

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

amount - integer - the amount of tokens to sell in the token's base unit of decimals

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

minFillPercent - number (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 - number (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

Sample request

{

"address": "0xD18CEC4907b50f4eDa4a197a50b619741E921B4D",

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

"list": [ 4, 7 ],

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

},

"affiliateContract": "0x...addressOfAffiliateContract",

"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

success ​- boolean - indicates whether the API call was successful or not. If not, the returned value equals false and is accompanied with an error message.

response ​- object - settlement information including smart contract address, payload, summary, and debug information.

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 tokens 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 WEI. For sells, it is denominated in the base units in decimals of the token 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

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

Sample response

{

"success": true,

"response": {

"id": "0x...fe0",

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

}

}

}

swap

POST swap

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

-H 'Accept: application/json, text/plain, */*' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-binary ‘{<input parameters>}’

Trades one token for an equivalent amount of another token.

Inputs

address - string - the wallet address to transfer tokens to/from

affiliateContract (optional) - string - the address of the affiliate contract you want to use to collect fees

exchanges (optional) - array - specifies exchanges to white or black list

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

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

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

swap - object - describes the parameters of the trade

from - string - identifier of the token to sell

to - string - identifier of the token to buy

amount - integer - the amount of tokens to sell in the token's base unit of decimals

minFillPercent - number (optional, default 100) - minimum percentage of the order that must be fulfilled for the transaction to succeed

minSlippagePercent - number (optional, default 3) - minimum percentage of slippage (versus the quoted price) that the client is willing to accept

Sample request

{

"address": "0xD18CEC4907b50f4eDa4a197a50b619741E921B4D",

"affiliateContract":"0x...addressOfAffiliateContract",

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

"list": [ 4, 7 ],

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

},

"swap": {

“from”: “0x1985365e9f78359a9b6ad760e32412f4a445e862",

“to”: “0xe41d2489571d322189246dafa5ebde1f4699f498",

“amount”: “1000000000000000000",

"minFillPercent": 100

"minSlippagePercent": 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 ​- object - two arrays, one for the buy trade and one for the sell trade. Contains user readable details of all the orders that the Suggester has found. 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 tokens 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 WEI. For sells, it is denominated in the base units in decimals of the token 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

Sample response

{

"success": true,

"response": {

"id": "0x...fe0",

"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": "0xa...00",

"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": "0xe...98",

"tokenAmount": "1000000000000000000",

"optionalTrade": true,

"minimumExchangeRate": "3325507498247468",

"minimumAcceptableTokenAmount": "850000000000000000",

"orders": [

{

"exchangeHandler": "0x8...36",

"genericPayload": "0x0000000000000000000e"

},

{

"exchangeHandler": "0xA...12",

"genericPayload":

"0x000000000000000"

}

]

}

]

},

"gas": {

"price": "10000000000",

"strict": false,

"limit": "1360000"

}

}

}

Looking for something else? Send us your feedback.