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:

Order Object

Both endpoints use the Order object, which is defined as follows:

Quote

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

The parameters needed to call the quote endpoint are the following:

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"],
  "venue": "propeller"
}'

Solve

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

The parameters needed to call the solve endpoint are the following:

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
}'

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

The query parameters needed to call the tokens endpoint are:

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

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

The query parameters needed to call the token_price endpoint are:

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

Native Token USD Price

Get the native token to USD price.

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

The query parameter needed to call the native_usd_price endpoint is the following:

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

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.

Last updated