Classic Swap API

Quote and Solve

Classic Swap has the following endpoints:

• Quote: Returns a quote (but no route). Optimized for response time.

• Solve: Returns quote and transaction instructions. Optimizes for solution quality.

Use /quote to display price and gas quotes with low latency.

Use /solve to build transactions for the user to execute.

Both endpoints use the same format order object to specify user orders.

Token Endpoints

The API also has the following token endpoints:

• Tokens: Get the list of tokens supported by the solver.

• Token Price: Get the token's price denominated in the chain's native token.

• Native Token USD Price: Get the native token to USD price.

Order Object

Definition

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

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

Request

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 details).
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/partner/v2/solver/quote' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: <api-key>' \
  -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"
    }
  ]
}

Where 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

POST https://api.propellerheads.xyz/partner/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 details).
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/partner/v2/solver/solve' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: <api-key>' \
  -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).

Details on parameters:

AMMs

Both Quote and Solve endpoints support the amms input parameter. amms lets you specify 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 set amms=["+uniswap_v2"]. If you want to exclude only a particular protocol, you would set amms=["+all", "-uniswap_v2"].

Example

Request example using the AMMs filter:

curl -X 'POST' \
  'https://api.propellerheads.xyz/partner/v2/solver/solve?blockchain=ethereum&slippage=0.0005&return_routes=false' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: <api-key>' \
  -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", ...}."

Return Routes

The return_routes parameter in the Solve endpoint lets you specify if you want to receive the routes included in the swap in a structured format (for example, to display the route to users). By default, it is set to False). If set True, the routes used in each solution will be returned in the response. The routes are aggregated per in_token.

Example

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.

Tokens

Get the list of tokens supported by the solver.

GET https://api.propellerheads.xyz/partner/v2/solver/tokens

Request

The query parameters needed to call the tokens endpoint are:

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

Example

curl -X 'GET' \
  'https://api.propellerheads.xyz/partner/v2/solver/tokens?blockchain=ethereum&page=0&limit=5' \
  -H 'accept: application/json' \
  -H 'x-api-key: <api-key>'

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 a token denominated in the chain's native token.

GET https://api.propellerheads.xyz/partner/v2/solver/token_price

Request

The query parameters needed to call the token_price endpoint are:

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

Example

curl -X 'GET' \
  'https://api.propellerheads.xyz/partner/v2/solver/token_price?blockchain=ethereum&token_address=0x2260fac5e5542a773aa44fbcfedf7c193bc2c599' \
  -H 'accept: application/json' \
  -H 'x-api-key: <api-key>'

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 Token USD Price

Get the native token to USD price.

GET https://api.propellerheads.xyz/partner/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.

Example

curl -X 'GET' \
  'https://api.propellerheads.xyz/partner/v2/solver/native_usd_price?blockchain=ethereum' \
  -H 'accept: application/json' \
  -H 'x-api-key: <api-key>'

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 Example:

  • We regret to inform you that we're currently unable to find quote for the provided currency pair.

• Status: 404 Not found Example:

  • Unsupported AMM found. Supported AMM's are ... - PropellerSolver does not yet support AMM.

• Status: 422 Invalid format Example:

  • 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. Example:

  • Token '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' not found - the PropellerSolver does not yet support tokens.

• Status: 500 Internal Server Error. Please contact us for assistance.

• Status: 503 Internal timeout. Try again later. Example:

  • Apologies for the inconvenience. We were unable to generate the quote within the specified timeframe.