ParaSwapUser Documentation

Get Price & Calldata: /swap

The /swap endpoint allows you to make one API call to get both the priceRoute object as well as the Transaction Object.

Limitations

  • Lower rate limits

  • It doesn't check sufficient allowances and balances

  • It doesn't return the gas field in txParams, thus the transaction should be simulated locally

  • It automatically excludes RFQ-based DEXs such as AugustusRFQ & ParaSwapLimitOrders.

Get Price Route

GET https://api.paraswap.io/swap

This endpoint gets the optimal price and price route required to swap from one token to another.

Query Parameters

Name
Type
Description

srcToken*

string

Source Token Address. Instead Token Symbol could be used for tokens listed in the /tokens endpoint.

srcDecimals*

integer

Source Token Decimals. (Can be omitted if Token Symbol is used in srcToken).

destToken*

string

Destination Token Address. Instead Token Symbol could be used for tokens listed in the /tokens endpoint.

amount*

string

srcToken amount (in case of SELL) or destToken amount (in case of BUY). The amount should be in WEI/Raw units (eg. 1WBTC -> 100000000)

side

string

SELL or BUY. Default: SELL.

network

string

Network ID. (Mainnet - 1, Optimism - 10, BSC - 56, Polygon - 137, Fantom - 250, zkEVM - 1101, Base - 8453, Arbitrum - 42161, Avalanche - 43114, Gnosis - 100). Default: 1.

otherExchangePrices

boolean

If provided, others object is filled in the response with price quotes from other exchanges (if available for comparison). Default: false

includeDEXS

string

Comma Separated List of DEXs to include. Supported DEXs: Uniswap, Kyber, Bancor, AugustusRFQ, Oasis, Compound, Fulcrum, 0x, MakerDAO, Chai, Aave, Aave2, MultiPath, MegaPath, Curve, Curve3, Saddle, IronV2, BDai, idle, Weth, Beth, UniswapV2, Balancer, 0xRFQt, SushiSwap, LINKSWAP, Synthetix, DefiSwap, Swerve, CoFiX, Shell, DODOV1, DODOV2, OnChainPricing, PancakeSwap, PancakeSwapV2, ApeSwap, Wbnb, acryptos, streetswap, bakeryswap, julswap, vswap, vpegswap, beltfi, ellipsis, QuickSwap, COMETH, Wmatic, Nerve, Dfyn, UniswapV3, Smoothy, PantherSwap, OMM1, OneInchLP, CurveV2, mStable, WaultFinance, MDEX, ShibaSwap, CoinSwap, SakeSwap, JetSwap, Biswap, BProtocol eg: UniswapV3,0x

excludeDEXS

string

Comma Separated List of DEXs to exclude. (from the list of DEXs mentioned above).

includeContractMethods

string

Comma Separated List of Contract Methods to include without spaces. Available values: swapOnUniswap, buyOnUniswap, swapOnUniswapFork, buyOnUniswapFork, swapOnUniswapV2Fork, buyOnUniswapV2Fork, simpleBuy, simpleSwap, multiSwap, megaSwap, protectedMultiSwap, protectedMegaSwap, protectedSimpleSwap, protectedSimpleBuy, swapOnZeroXv2, swapOnZeroXv4, buy. eg: simpleSwap,multiSwap

excludeContractMethods

string

Comma Separated List of Contract Methods to exclude without spaces. (from the list of contract methods mentioned above).

userAddress

string

User's Wallet Address.

route

string

Dash (-) separated list of tokens (addresses or symbols from /tokens) to comprise the price route. Max 4 tokens. *Note: If route is specified, the response will only comprise of the route specified which might not be the optimal route.

partner

string

Partner string.

partnerFeeBps

string

If provided it is used together with partnerAddress. Should be in basis points percentage. Look at slippage parameter description for understanding better. Eg: 200 (for 2% fee percent)

partnerAddress

string

Address that will be entitled to claim fees or surplus.

slippage

integer

Allowed slippage percentage represented in basis points. Eg: for 2.5% slippage, set the value to 2.5 * 100 = 250; for 10% = 1000. Slippage could be passed instead of destAmount when side=SELL or srcAmount when side=BUY. Min: 0; Max: 10000

destDecimals*

integer

Destination Token Decimals. (Can be omitted if Token Symbol is used in destToken).

maxImpact

number

In %. It's a way to bypass the API price impact check (default = 15%).

receiver

String

Receiver's Wallet address. (Can be omitted if swapping tokens from and to same account)

srcTokenTransferFee

string

If the source token is a tax token, you should specify the tax amount in BPS.

*For example: for a token with a 5% tax, you should set it to 500 as [(500/10000)*100=5%]

**Note: not all DEXs and contract methods support trading tax tokens, so we will filter those that don't.

destTokenTransferFee

string

If the destination token is a tax token, you should specify the tax amount in BPS.

*For example: for a token with a 5% tax, you should set it to 500 as [(500/10000)*100=5%]

**Note: not all DEXs and contract methods support trading tax tokens, so we will filter those that don't.

srcTokenDexTransferFee

string

If the source token is a tax token, you should specify the tax amount in BPS. Some tokens only charge tax when swapped in/out DEXs and not on ordinary transfers.

*For example: for a token with a 5% tax, you should set it to 500 as [(500/10000)*100=5%]

**Note: not all DEXs and contract methods support trading tax tokens, so we will filter those that don't.

destTokenDexTransferFee

string

If the destination token is a tax token, you should specify the tax amount in BPS. Some tokens only charge tax when swapped in/out DEXs, not on ordinary transfers.

*For example: for a token with a 5% tax, you should set it to 500 as [(500/10000)*100=5%]

**Note: not all DEXs and contract methods support trading tax tokens, so we will filter those that don't.

version

number

To specify the protocol version. Values: 5 or 6.2 Default: 5

ignoreBadUsdPrice

boolean

If tokens USD prices are not available, Bad USD Price error will be thrown. Use this param to skip this check. Default: false

isSurplusToUser

boolean

Specify if user should receive surplus instead of partner. Default: false

isDirectFeeTransfer

boolean

Specify if fees should be sent directly to the partner instead of registering them on FeeClaimer.

Default: false

isCapSurplus

boolean

Allows for capping the surplus at 1% maximum.

Default: true

takeSurplus

boolean

Allows to collect surplus. Works with partnerAddress

Default: false

{
  "priceRoute": {
    "blockNumber": 20184108,
    "network": 1,
    "srcToken": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "srcDecimals": 6,
    "srcAmount": "1000000",
    "destToken": "0x6b175474e89094c44da98b954eedeac495271d0f",
    "destDecimals": 18,
    "destAmount": "997620341641628401",
    "bestRoute": [
      {
        "percent": 100,
        "swaps": [
          {
            "srcToken": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
            "srcDecimals": 6,
            "destToken": "0x6b175474e89094c44da98b954eedeac495271d0f",
            "destDecimals": 18,
            "swapExchanges": [
              {
                "exchange": "ShibaSwap",
                "srcAmount": "1000000",
                "destAmount": "997620341641628401",
                "percent": 100,
                "poolAddresses": [
                  "0x4610bA8d5D10FBa8C048A2051a0883CE04eaBAcE"
                ],
                "data": {
                  "router": "0xF9234CB08edb93c0d4a4d4c70cC3FfD070e78e07",
                  "path": [
                    "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
                    "0x6b175474e89094c44da98b954eedeac495271d0f"
                  ],
                  "factory": "0x115934131916C8b277DD010Ee02de363c09d037c",
                  "initCode": "0x65d1a3b1e46c6e4f1be1ad5f99ef14dc488ae0549dc97db9b30afe2241ce1c7a",
                  "feeFactor": 10000,
                  "pools": [
                    {
                      "address": "0x4610bA8d5D10FBa8C048A2051a0883CE04eaBAcE",
                      "fee": 30,
                      "direction": false
                    }
                  ],
                  "gasUSD": "5.515040"
                }
              }
            ]
          }
        ]
      }
    ],
    "gasCostUSD": "5.932529",
    "gasCost": "107570",
    "side": "SELL",
    "version": "6.2",
    "contractAddress": "0x6a000f20005980200259b80c5102003040001068",
    "tokenTransferProxy": "0x6a000f20005980200259b80c5102003040001068",
    "contractMethod": "swapExactAmountIn",
    "partnerFee": 0,
    "srcUSD": "1.0000000000",
    "destUSD": "0.9973641328",
    "partner": "anon",
    "maxImpactReached": false,
    "hmac": "39d19445379b69c115149340c5caaa05c898e840"
  },
  "txParams": {
    "from": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "to": "0x6a000f20005980200259b80c5102003040001068",
    "value": "0",
    "data": "0xe3ead59e0000000000000000000000005f0000d4780a00d2dce0a00004000800cb0e5041000000000000000000000000a0b86991c6218b36c1d19d4a2e9eb0ce3606eb480000000000000000000000006b175474e89094c44da98b954eedeac495271d0f00000000000000000000000000000000000000000000000000000000000f42400000000000000000000000000000000000000000000000000db4d11c67691ad50000000000000000000000000000000000000000000000000dd8426a4440caf10a8104c26c244959a1d46f205acc49520000000000000000000000000133fc2c00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000016000000000000000000000000000000000000000000000000000000000000001800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000016000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000160a0b86991c6218b36c1d19d4a2e9eb0ce3606eb480000006000240000ff00000300000000000000000000000000000000000000000000000000000000a9059cbb0000000000000000000000004610ba8d5d10fba8c048a2051a0883ce04eabace00000000000000000000000000000000000000000000000000000000000f42406a000f20005980200259b80c51020030400010680000008000240000ff0600030000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000f4240000000000000000000004de54610ba8d5d10fba8c048a2051a0883ce04eabace",
    "gasPrice": "16000000000",
    "chainId": 1
  }
}

🧙Though srcDecimals and destDecimals are optional parameters it is highly recommended to add them while doing the pricing. This will allow you to get prices for all the tokens, including the ones which are also not listed by ParaSwap.

Swaps fees and Swap&Transfer (where the receiver is not the same as the sender) don't work when swapOnUniswap, swapOnUniswapFork, swapOnZeroXv2, and swapOnZeroXv4 etc. contract methods are used.

If you would like to disable these methods you can do so by setting a whitelist for methods where Swap&Transfer is supportedincludeContractMethods=simpleSwap,multiSwap,megaSwap

Most common error messages

The following is a list of the most common error messages of the /swap endpoint. Most are self-explanatory and can be self-solved, but feel free to contact ParaSwap Support using the chat in the bottom right corner of this page.

  • Missing response from pricing API - failed to get a response from pricing API

  • Can not receive price route - failed to receive price route from the pricing API response

Last updated