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:

FieldDescription

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.

Quote

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

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

Body ParameterDescription

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).

venue

(optional string) Switch between propeller (classic swap) or helix (intent based swap). Default is propeller

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:

Body ParameterDescription

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

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:

Query ParameterDescription

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

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:

Query ParameterDescription

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

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:

Query ParameterDescription

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

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.

PreviousTarget ContractsNextIntent API

Last updated