Totle API

Totle API Developer Hub

Welcome to the Totle API docs!

Get Started

Operational Details

Displaying a Summary

The payload returned by the swap and pay endpoints is optimized for Smart Contracts and is not easily read by end users. However, all endpoints return a human-readable summary of the trades that will be executed as part of the transaction. This is helpful to those who wish to review the transaction before signing it. The summary uses JSON formatting:

"summary": [
  {
    "baseAsset": {
      "address": "0x0...00",
      "symbol": "ETH",
      "decimals": "18"
    },
    "sourceAsset": {
      "address": "0x0...7ef",
      "symbol": "BAT",
      "decimals": "18"
    },
    "sourceAmount": "100000000000000000",
    "destinationAsset": {
      "address": "0x0...7ef",
      "symbol": "BAT",
      "decimals": "18"
    },
    "destinationAmount": "100108060297981726",
    "notes": [],
    "rate": "1.00108060297981726",
    "market": {
      "rate": "1.00108060297981726",
      "slippage": "0%"
    },
    "runnerUpRoutes": [
      {
        "sourceAsset": {
          "address": "0x0...7ef",
          "symbol": "BAT",
          "decimals": "18"
        },
        "sourceAmount": "100000000000000000",
        "destinationAsset": {
          "address": "0x0...7ef",
          "symbol": "BAT",
          "decimals": "18"
        },
        "destinationAmount": "99657574026640315"
      }
    ],
    "trades": [
      {
        "sourceAsset": {
          "address": "0x0...7ef",
          "symbol": "BAT",
          "decimals": "18"
        },
        "sourceAmount": "100000000000000000",
        "destinationAsset": {
          "address": "0x0...00",
          "symbol": "ETH",
          "decimals": "18"
        },
        "destinationAmount": "91588661679677",
        "orders": [
          {
            "sourceAsset": {
              "address": "0x0...ef",
              "symbol": "BAT",
              "decimals": "18"
            },
            "sourceAmount": "100000000000000000",
            "destinationAsset": {
              "address": "0x0...00",
              "symbol": "ETH",
              "decimals": "18"
            },
            "destinationAmount": "91588661679677",
            "exchange": {
              "id": 11,
              "name": "Uniswap"
            },
            "fee": {
              "percentage": "0.3",
              "amount": "300000000000000",
              "asset": {
                "address": "0x0...ef",
                "symbol": "BAT",
                "decimals": "18"
              }
            }
          }
        ],
        "runnerUpOrders": [
          {
            "sourceAsset": {
              "address": "0x0...ef",
              "symbol": "BAT",
              "decimals": "18"
            },
            "sourceAmount": "100000000000000000",
            "destinationAsset": {
              "address": "0x0...00",
              "symbol": "ETH",
              "decimals": "18"
            },
            "destinationAmount": "91176512702118",
            "exchange": {
              "id": 2,
              "name": "Kyber"
            },
            "fee": {
              "percentage": "0",
              "amount": "0",
              "asset": {
                "address": "0x0...7ef",
                "symbol": "BAT",
                "decimals": "18"
              }
            }
          }
        ]
      },
      {
        "sourceAsset": {
          "address": "0x0...00",
          "symbol": "ETH",
          "decimals": "18"
        },
        "sourceAmount": "91588661679677",
        "destinationAsset": {
          "address": "0x0...ef",
          "symbol": "BAT",
          "decimals": "18"
        },
        "destinationAmount": "100108060297981726",
        "orders": [
          {
            "sourceAsset": {
              "address": "0x0...00",
              "symbol": "ETH",
              "decimals": "18"
            },
            "sourceAmount": "91588661679677",
            "destinationAsset": {
              "address": "0x0...7ef",
              "symbol": "BAT",
              "decimals": "18"
            },
            "destinationAmount": "100108060297981727",
            "exchange": {
              "id": 2,
              "name": "Kyber"
            },
            "fee": {
              "percentage": "0",
              "amount": "0",
              "asset": {
                "address": "0x0...00",
                "symbol": "ETH",
                "decimals": "18"
              }
            }
          }
        ],
        "runnerUpOrders": [
          {
            "sourceAsset": {
              "address": "0x0...00",
              "symbol": "ETH",
              "decimals": "18"
            },
            "sourceAmount": "91588661679677",
            "destinationAsset": {
              "address": "0x0...7ef",
              "symbol": "BAT",
              "decimals": "18"
            },
            "destinationAmount": "99400877710875856",
            "exchange": {
              "id": 11,
              "name": "Uniswap"
            },
            "fee": {
              "percentage": "0.3",
              "amount": "274765985039",
              "asset": {
                "address": "0x0...00",
                "symbol": "ETH",
                "decimals": "18"
              }
            }
          }
        ]
      }
    ],
    "totleFee": {
      "asset": {
        "address": "0x0...00",
        "symbol": "ETH",
        "decimals": "18"
      },
      "percentage": "0.5",
      "amount": "457943308398"
    },
    "partnerFee": {
      "asset": {
        "address": "0x0...00",
        "symbol": "ETH",
        "decimals": "18"
      },
      "percentage": "0",
      "amount": "0"
    }
  }
]

Signing and Submitting a Transaction

The response from the swap and pay endpoints includes a payload that needs to be signed and submitted to the Ethereum network for mining. You can do this using the web3 library's signTransaction and sendTransaction functions.

One way to construct the transaction is 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);

The Totle API will construct the transaction object on your behalf:

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

Slippage

There are two forms of slippage that you can control through Totle's API: market slippage and execution slippage.

Execution slippage refers to the change between the quoted price and the actual execution price. You may specify what the allowable execution slippage is when you make a request to the API, otherwise Totle will use a default value of 3%. Any trades where the execution slippage exceeds the allowable value will fail, and none of the client's tokens will move.

Market slippage refers to the difference between the quoted price and the price of 0.1 units of the swap's source token. Higher volume trade requests require our engine to go deeper into the order books to find suitable orders, and on-chain pool exchanges quote increasingly higher prices for taking a greater number of tokens from their liquidity pool. We allow clients to specify the allowable market slippage on a per-request basis. The API will return an error for unfavorable trade prices based on market slippage.

Token Amounts

When providing token amounts to the API for the /swap and /pay endpoints, the amount you provide should be in the token's base unit of decimals.

The conversation factor to get this high-precision decimal number is 1*10^(-x) where x is the token decimals. For example, if you're working with 1 MKR, its representation using the token's base unit of decimals is 0.000000000000000001 MKR.

Gas

Most wallets provide you with the option of setting the gas price for the transaction before you sign and submit it for execution.

In general, setting a higher gas price results in the transaction getting mined sooner, since miners try to maximize the fees they collect when constructing blocks. However, setting a higher gas price is a common way to front-run DEX transactions, so some DEXs try to combat this by setting limits on the gas price. If you set a gas price above these limits, the transaction will fail.

To assist you in finding the appropriate gas price, the /pay and /swap endpoints includes gas parameters in the response to your call:

"gas": {    
    "price": "10000000000",
    "strict": false,
    "limit": "1360000"
}

The price parameter of the gas object is the suggested gas price for the provided payload. You can set a higher gas price, but if the strict flag is set to true, we recommend using the suggested gas price to minimize the likelihood that the transaction fails. The Totle API selects the gas values to optimize the likelihood the transaction succeeds while also providing you with a fair value.

The limit field is the suggested minimum gas limit for the payload provided. It is based on the number of orders to be settled, as well as their complexity, and Suggester's knowledge of the average gas consumed by trades on various DEXs. We recommend setting a gas limit at or above the suggested value.

Operational Details


Suggested Edits are limited on API Reference Pages

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