API Reference v2

The PropellerSolver API v2 has two main endpoints where you can request a solution for a token transaction: Quote and Solve. For both endpoints, PropellerSolver will determine the optimal route for you, ensuring the best price for a swap.
By querying the Quote endpoint, users can retrieve details on the current pricing and the estimated gas required to perform the transaction. This endpoint can be used to quickly get the best estimated buy amount for a swap. The Quote endpoint is faster than the Solve endpoint.
It is recommended to call the Quote endpoint before using the Solve endpoint. This way, the user can evaluate whether the current estimated buy amount is appealing enough before proceeding with the swap. This approach enables users to make informed decisions and assess the feasibility of executing the transaction based on the provided quote information.
In addition to the quote information, the Solve endpoint delivers the actual solution in the form of a transaction ready to be executed on-chain. Target contract can be found in the Solver Contracts section. This functionality allows users to seamlessly integrate the provided transaction data into their own systems or applications, simplifying the process of executing transactions on the blockchain.

v2 features

Previously limited to individual quotes, the Quote endpoint now provides enhanced functionality, supporting batch quoting operations.
The Solve endpoint now supports a receiver different from the origin address. It also returns detailed route information, including the protocols used for each solution.

Solve and Quote Endpoints

Order

Both endpoints use the Order object, which is defined as follows:
Field
Description
sell_token
(string) ERC20 token address of the token you want to sell.
buy_token
(string) ERC20 token address of the token you want to buy.
sell_amount
(string) The amount of sell_token (in sell_token base units) you want to send. Assumes the amount is given in WEI.
origin_address
(string) Wallet address with the funds.
receiver
(optional string) Receiver of the funds. Only pass if different from the origin_address
buy_amount
(optional string) The minimum amount of buy_token (in buy_token base units) you want to receive. If the solver can't find a solution with a better buy amount than this, it will fail immediately. Default is 0, meaning that your order will be solved at the current market price.

Example

{
"sell_token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"buy_token": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
"sell_amount": "1000000000",
"origin_address": "0x0000000000000000000000000000000000000000",
"receiver": "0x1230000000000000000000000000000000000000",
"buy_amount": "1000000000000000000000"
}

Quote

https://api.propellerheads.xyz/v2/solver/quote

Request

The quote endpoint is now POST. The parameters needed to call the quote endpoint are the following:
Body Parameter
Description
blockchain
(string) The blockchain on which to obtain quotes for orders.
orders
(list[Order]) A list of Order objects
amms
(optional list[string]) Protocols to include in the solution. By default, this is "+all", which includes all protocols (see AMMs for more)
deduct_gas_cost
(optional string) If passed, deducts the gas cost from the orders using the passed strategy. Currently the only strategy is "FirstOrder", which deducts the gas cost from the output of the first order.
The Order for the quote endpoint has an optional origin_address and receiver. If at least the origin_address is passed, the quote might be better than without it because the Solver will be able to tap into market makers (through Hashflow for example).

Example

curl -X 'POST' \
'https://api.propellerheads.xyz/v2/solver/quote' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"blockchain": "ethereum",
"orders": [
{
"sell_token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"buy_token": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
"sell_amount": "100000000"
}
],
"amms": ["+all"],
"deduct_gas_cost": "FirstOrder"
}'

Response

The response from the quote endpoint looks like:
{
"request_id": "quote-0868c67b",
"quotes": [
{
"sell_token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"buy_token": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
"sell_amount": "100000000",
"buy_amount": "99676294448336757728",
"external_id": "0"
}
],
"gas": 74100,
"target_address": "0x0000000000000000000000000000000000000000",
"buy_tokens": [
{
"symbol": "DAI",
"decimals": "18",
"address": "0x6B175474E89094C44Da98b954EedeAC495271d0F"
}
],
"sell_tokens": [
{
"symbol": "USDC",
"decimals": "6",
"address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
}
]
}
request_id is the unique ID used to identify the quote. The quotes are displayed in a list in the same order as the request. For each quote, the sell_token, buy_token, sell_amount and buy_amount are returned. gas is a rough gas estimation of what it would take to execute all quotes on chain and target_address is our router address on the target chain. Information on the sell_tokens and buy_tokens is also returned.

Solve

https://api.propellerheads.xyz/v2/solver/solve

Request

The parameters needed to call the solve endpoint are the following:
Body Parameter
Description
blockchain
(string) The blockchain on which to solve the orders.
orders
A list of orders to be solved.
amms
(optional list[string]) Protocols to include in the solution. By default, this is "+all", which includes all protocols (see AMMs for more).
slippage
(optional float) Represents the percentage of acceptable difference between the expected price of an order and the price when the order actually executes. The default value is 0.0005.
return_routes
(optional bool) If the user wants to have information on the solutions' routes in the response or not. Default false (see Routes for more)
curl -X 'POST' \
'https://api.propellerheads.xyz/v2/solver/solve' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"blockchain": "ethereum",
"orders": [
{
"origin_address": "0x0000000000000000000000000000000000000000",
"sell_token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"buy_token": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
"sell_amount": "1000000000",
"buy_amount": "1000000000000000000000"
},
{
"origin_address": "0x0000000000000000000000000000000000000000",
"sell_token": "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599",
"buy_token": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"sell_amount": "100000000",
"buy_amount": "18000000000000000000"
}
],
"amms": [
"+all"
],
"slippage": 0.005,
"return_routes": true
}'

Response

The response from the solve endpoint looks like:
{
"request_id": "solve-2969e7e0",
"solutions": [
{
"orders": [
{
"origin_address": "0x0000000000000000000000000000000000000000",
"sell_token": "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599",
"buy_token": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"sell_amount": "100000000",
"executed_sell_amount": "100000000",
"buy_amount": "18316566729202872755",
"executed_buy_amount": "18408609778093339453",
"external_id": "1",
"receiver": "0x0000000000000000000000000000000000000000"
}
],
"call_data": "0x6e5129d10000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000014000000000000000000000000000000000000000000000000000000000000000de0000000000000000000000000000000000000000000000000000000005f5e1002260fac5e5542a773aa44fbcfedf7c193bc2c599000000000000000000000000000000000000000000000000fe31846516e031b3c02aaa39b223fe8d0a0e5c4f27ead9083c756cc20000000000000000000000000000000000000000010000000000002260fac5e5542a773aa44fbcfedf7c193bc2c599c02aaa39b223fe8d0a0e5c4f27ead9083c756cc20001f40c0000000000000000000000000000000000000000004585fe77225b41b697c938b018e2ac67ac5a20c0010000000000000000000000000000000000000000000000000000000000000000000000000000418ab7ecf4e228d2e8fc10b67d677bdcc8ef94ace6fce5d37d7fc5b2ce9d438fee5447ea796c4425d4741394d805225fff20c49ca83b0b9534dc88cd771b949cd21c00000000000000000000000000000000000000000000000000000000000000",
"gas": "137100",
"target_address": "0x14f2b6ca0324cd2B013aD02a7D85541d215e2906"
}
],
"buy_tokens": [
{
"symbol": "WETH",
"decimals": "18",
"address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
}
],
"sell_tokens": [
{
"symbol": "WBTC",
"decimals": "8",
"address": "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599"
}
],
"routes": {
"1": [
[
{
"protocol": "uniswap_v3",
"in_token": "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599",
"out_token": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"split": 1
}
]
]
}
}
Where there is one solution per order that was in the request, the solution is defined by the same parameters as the order (to match order and solution) and the following parameters:
Field
Description
executed_buy_amount
(string) Optimised amount of buy_token that the solver found.
buy_amount
(string) Minimum amount that you will receive for your order, taking slippage into consideration
gas
(string) Estimated gas used in the txs
call_data
(string) Call data used to execute the txs found by the solver. This data is meant to be sent to our Solver Contracts.
target_address
(string) Contract address to send the txs to. This address should match our Solver Contracts.
Information on the sell_tokens and buy_tokens is returned. If return_routes is True, the routes used in each solution will also be returned (see Routes for more information).

More parameters

The following sections describe some extra parameters that can be tuned to improve your swapping experience.

AMMs

Both Quote and Solve endpoints support an amms input parameter. It takes a list of protocols to include in the solution. By default, it is ["+all"], which includes all protocols. If you want to include only a particular protocol, for example uniswap_v2, you would do amms=["+uniswap_v2"]. If you want to exclude only a particular protocol, you would do amms=["+all", "-uniswap_v2"].
Request example using the AMMs filter:
curl -X 'POST' \
'https://api.propellerheads.xyz/v2/solver/solve?blockchain=ethereum&slippage=0.0005&return_routes=false' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"orders": [
{
"origin_address": "0x0000000000000000000000000000000000000000",
"sell_token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"buy_token": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
"sell_amount": "10000000000000",
"buy_amount": "1000000000000000000000"
}
],
"amms": [
"+all",
"-maverick"
]
}'
If an AMM that is not supported is passed, the API will return a 400 error.
"Unsupported AMM found. Supported AMM's are {"uniswap_v2", ...}."

Routes

In the Solve endpoint, there is a parameter called return_routes (with a default value False). If this parameter is True, the routes used in each solution will be returned in the response. The routes are aggregated per in_token.
A simple solution to swap USDC for DAI would be:
[
[
{
"protocol": "uniswap_v2",
"in_token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"out_token": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
"split": "1.0"
}
]
]
This solution has only one swap in a uniswap v2 pool. The whole sell amount will be routed through this pool.
Let's have a look at a more complex example: swap WBTC for WETH.
[
[
{
"protocol": "balancer",
"in_token": "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599",
"out_token": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"split": 0.04,
},
{
"protocol": "curve_v2",
"in_token": "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599",
"out_token": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
"split": 0.34,
},
{
"protocol": "curve_v2",
"in_token": "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599",
"out_token": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"split": 0.62,
},
],
[
{
"protocol": "curve_v1",
"in_token": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
"out_token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"split": 1.0,
}
],
[
{
"protocol": "uniswap_v2",
"in_token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"out_token": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"split": 1.0,
}
],
]
Visually, the solution would be the following:
Where the splits represent the percentage of sell amount that goes into each pool.

Token Endpoints

Tokens

Get a list of on-chain tokens supported by the Propeller solver
https://api.propellerheads.xyz/v2/solver/tokens

Request

The query parameters needed to call the tokens endpoint are the following:
Query Parameter
Description
blockchain
(string) The blockchain on which to obtain the tokens
limit
(int) The number of results per page
page
(int) Which page number containing results to view
curl -X 'GET' \
'https://api.propellerheads.xyz/v2/solver/tokens?blockchain=ethereum&page=0&limit=5' \
-H 'accept: application/json'

Response

The response from the tokens endpoint looks like:
[
{
"address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
"symbol": "USDT",
"name": "Tether USD",
"decimals": 6,
"icon_url": "https://cdn.coinranking.com/mgHqwlCLj/usdt.svg",
"volume_24_hr": 179372070087,
"color": "#22a079"
},
{
"address": "0xc5f0f7b66764F6ec8C8Dff7BA683102295E16409",
"symbol": "FDUSD",
"name": "First Digital USD",
"decimals": 18,
"icon_url": "https://cdn.coinranking.com/Fsc8c3dOQ/Kegnv2no_400x400.PNG",
"volume_24_hr": 14319236504,
"color": "#000000"
},
{
"address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"symbol": "USDC",
"name": "USDC",
"decimals": 6,
"icon_url": "https://cdn.coinranking.com/jkDf8sQbY/usdc.svg",
"volume_24_hr": 7115854666,
"color": "#7894b4"
},
{
"address": "0x6982508145454Ce325dDbE47a25d4ec3d2311933",
"symbol": "PEPE",
"name": "PEPE",
"decimals": 18,
"icon_url": "https://cdn.coinranking.com/L9KYPBnG8/pepe_32.PNG",
"volume_24_hr": 2877306164,
"color": "#4f9842"
},
{
"address": "0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE",
"symbol": "SHIB",
"name": "Shiba Inu",
"decimals": 18,
"icon_url": "https://cdn.coinranking.com/fiZ4HfnRR/shib.png",
"volume_24_hr": 1449887675,
"color": "#fda32b"
}
]
The result is a list containing token objects, where each token object contains the following information.
Field
Description
address
(string) The address of the token.
symbol
(string) The symbol of the token.
name
(string) The name of the token
decimals
(int) The number of decimal places used in the token contract
icon_url
(string) A link to an image representation of the token
volume_24_hr
(int) The total volume of this token traded on-chain in the last 24 hours

Token Price

Get the price of an on-chain token in the blockchain's native token.
https://api.propellerheads.xyz/v2/solver/token_price

Request

The query parameters needed to call the token_price endpoint are the following:
Query Parameter
Description
blockchain
(string) The blockchain of the token for which we would like the price of.
token_address
(string) The address of the token that we would like the price of
curl -X 'GET' \
'https://api.propellerheads.xyz/v2/solver/token_price?blockchain=ethereum&token_address=0x2260fac5e5542a773aa44fbcfedf7c193bc2c599' \
-H 'accept: application/json'

Response

The response from the token_price endpoint looks like:
{
"price": 17.466318388278005
}
Where the "price" field represents our price for the given token in the blockchain's native token.

Native USD Price

Fetches the native token to USD price.
https://api.propellerheads.xyz/v2/solver/native_usd_price

Request

The query parameter needed to call the native_usd_price endpoint is the following:
Query Parameter
Description
blockchain
(string) The blockchain of the native token for which we would like the USD price of.
curl -X 'GET' \
'https://api.propellerheads.xyz/v2/solver/native_usd_price?blockchain=ethereum' \
-H 'accept: application/json'

Response

The response from the native_usd_price endpoint looks like:
{
"price": 3285.82039213321
}
Where the "price" field represents our price for the native token of the given blockchain in USD.

Error messages

The PropellerSolver API follows standard HTTP status codes to indicate success or failure. In case of an error, additional information is provided in the response body to help identify and resolve the issue.
  • Status: 204 No solution found: Our solvers were not able to find a solution for a given order Examples::
    • We regret to inform you that we're currently unable to find quote for the provided currency pair.
  • Status: 404 Not found Examples:
    • Unsupported AMM found. Supported AMM's are ... - AMM is not yet supported by PropellerSolver.
  • Status: 422 Invalid format Examples:
    • Invalid token address. Please input a valid hex string token address
    • Invalid AMM format. uniswap_v2 is missing prefix, either + or -
    • Request ambiguous found uniswap_v2 with + and - . Desired AMM's should only be featured once in the query.
  • Status: 400 Bad Request: This indicates an invalid request or missing parameters in the request. Examples:
    • Token '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' not found - token is not yet supported by the PropellerSolver.
  • Status: 500 Internal Server Error. Please contact us for assistance.
  • Status: 503 Internal timeout. Try again later. Examples:
    • Apologies for the inconvenience. We were unable to generate the quote within the specified timeframe.

Rate limiting

All endpoints have a rate limiting of 3 requests per second. If you need to support higher loads – please contact us to obtain an API key.

API Keys

Having an API key allows you to have better rate limits when requesting our API. The endpoints URL for partners are the same as before with a prepended /partner.
  • Quote
https://api.propellerheads.xyz/partner/v2/solver/quote
  • Solve
https://api.propellerheads.xyz/partner/v2/solver/solve
Request example using an API key:
curl -X 'POST' \
'https://api.propellerheads.xyz/partner/v2/solver/quote?blockchain=ethereum' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'x-api-key: <api-key>' \
-d '{
"orders": [
{
"sell_token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"buy_token": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
"sell_amount": "100000000"
}
]
}'
Last modified 1d ago