Swap

Swap tokens at the best pricing available.

post
/swap

https://api.totle.com/swap
The endpoint allows you to trade one token for the equivalent value of another token. This can be used to trade single pairs or multiple pairs.
Request
Response
Request
Body Parameters
apiKey
required
string
Your Totle partner identifier
partnerContract
optional
string
The smart contract address if you're a Totle partner
address
optional
string
The msg.sender wallet address. Although optional, you will only receive a payload if you include the address
config
optional
object
Transaction/trade-related configuration options
config.exchanges
optional
object
Information about the exchanges to be used (or not used)
config.exchanges.list
optional
array
IDs of the exchanges to whitelist/blacklist. Use /exchanges endpoint for IDs to use (an array of integers)
config.exchanges.type
optional
string
Whether the exchange(s) should be whitelisted/blacklisted. Use white for whitelisting and black for blacklisting
config.transactions
optional
boolean
Whether transactions objects are returned or not. The default setting for this parameter is false which will return a quote. Settings this to true will execute a transaction and requires you to include the address. We encourage you to only set this to true when you intend to submit a trade.
config.fillNonce
optional
boolean
Whether the nonce field in the transaction objects are populated or not. Defaults to true
config.skipBalanceChecks
optional
boolean
Whether the API should validate the source asset balance of the wallet given in the address field. Defaults to true
swap
required
object
Information about the single trading pair to be executed (submit either swap OR swaps; do not submit both to the API)
swap.sourceAsset
required
string
Identifier of the token to sell (either token address OR symbol)
swap.sourceAmount
required
integer
The amount of tokens to sell in the token's base unit of decimals (include either sourceAmount OR destinationAmount)
swap.destinationAsset
optional
string
Identifier of the token to buy (either token address or symbol)
swap.isOptional
optional
boolean
If this is true then the entire transaction won't revert if this swap fails. Defaults to false
swap.maxExecutionSlippagePercent
optional
integer
Percentage of maximum acceptable slippage of quoted rate from the API response to the settled rate on-chain. Defaults to 3. Value must be between 0-99, inclusive
swaps
required
array
Your Totle information about the swap (one or more) to be executed (submit either swap OR swaps; do not submit both to the API)
Response
200: OK
If the swap was successful.
{
"success": true,
"response": {
"id": "0x...353",
"summary": [ ... ],
"transactions": [ ... ],
"expiration": { ... }
}
}
For failures:
{
"success": false,
"response": {
"code": 3100,
"name": "Error Name",
"message": "Error message",
"link": "",
"info": "Detailed error information"
}
}

Swap Vs Swaps - Executing Multiple Swaps in One Call To execute multiple swaps, submit a request using the swaps array of objects, where each object within the array contains information about a single swap (i.e., to swap two token pairs, include two objects within the swaps array).

cURL
Node
Ruby
JavaScript
Python
cURL
curl -X POST \
https://api.totle.com/swap \
-H 'content-type: Application/JSON' \
-d '{
"swap":{
"sourceAsset":"ETH",
"destinationAsset":"DAI",
"sourceAmount":"1000000000000000000",
"maxMarketSlippagePercent":"10",
"maxExecutionSlippagePercent":"3"
}
}'
Node
var request = require("request")
var body = {
"swap":{
"sourceAsset":"ETH",
"destinationAsset":"DAI",
"sourceAmount":"1000000000000000000",
"maxMarketSlippagePercent":"10",
"maxExecutionSlippagePercent":"3"
}
}
var options = {
method: 'POST',
url: 'https://api.totle.com/swap',
headers: {'content-type': 'application/json'},
body: JSON.stringify(body)
}
request(options, function (error, response, body) {
if (error) throw new Error(error)
console.log(body)
})
Ruby
require 'uri'
require 'net/http'
url = URI("https://api.totle.com/swap")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["content-type"] = 'Application/JSON'
request.body = "{\"swap\":{\"sourceAsset\":\"ETH\",\"destinationAsset\":\"DAI\",\"sourceAmount\":\"1000000000000000000\",\"maxMarketSlippagePercent\":\"10\",\"maxExecutionSlippagePercent\":\"3\"}}"
response = http.request(request)
puts response.read_body
JavaScript
var data = "{\"swap\":{\"sourceAsset\":\"ETH\",\"destinationAsset\":\"DAI\",\"sourceAmount\":\"1000000000000000000\",\"maxMarketSlippagePercent\":\"10\",\"maxExecutionSlippagePercent\":\"3\"}}";
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://api.totle.com/swap");
xhr.send(data);
Python
import requests
url = "https://api.totle.com/swap"
payload = "{\"swap\":{\"sourceAsset\":\"ETH\",\"destinationAsset\":\"DAI\",\"sourceAmount\":\"1000000000000000000\",\"maxMarketSlippagePercent\":\"10\",\"maxExecutionSlippagePercent\":\"3\"}}"
headers = {
'content-type': "Application/JSON"
}
response = requests.request("POST", url, data=payload, headers=headers)
print(response.text)