Developer Docs
API
ParaSwap API
ParaSwap’s API provides the most straightforward and efficient access to the ParaSwap Protocol. It connects your application to a vast network of liquidity sources guaranteeing optimal token swap rates across multiple blockchain networks.
ParaSwap currently has two versions of its API available:
ParaSwap Delta API
Access an intent-based protocol that enables gas-less swaps where multiple agents compete to execute the trade at the best price possible. By using ParaSwap Delta, users don’t need to make a transaction themselves but only to sign a Delta Order.
ParaSwap Market API
Access a decentralized exchange aggregator that allows developers to access hundreds of DEXs and tens of thousands of liquidity pools in real-time.
ParaSwap Delta API
Here, you'll find everything you need to understand how the Delta API works and how to implement it. Start with our brief overview for a quick introduction to Delta's smart contract, then explore how to use its functions effectively.
Overview
ParaSwap Delta is a new set of smart contracts developed by ParaSwap. It's built on top of the Portikus Intents network and is currently available on the Ethereum network and Base. This development unlocks several benefits for swapping tokens, including:
Gas-less trading: users can submit a trade without using a gas token, as Delta will execute the trades on their behalf.
MEV Protection: By submitting your trade through ParaSwap Delta, you can protect your users’ swaps from events like sandwich attacks.
Price Competition: ParaSwap Delta is increasingly competitive as different agents compete to deliver the best possible prices to users.
Simple Delta flow using API with axios looks like this:
1. Request prices for a token pair
This function is used to fetch a price quote for swapping
In this case, we’re swapping 100 DAI for PSP tokens on Ethereum (chainId: 1) using ParaSwap’s Delta API.
2. Build a Delta order
On this section, partners can pick between two models:
Fee Model: It allows partners to take up to 2% of the trade in partner fees (200 bps)
Surplus Model: Which only works if a surplus is generated from the trade. On this case, the partner will collect 50% of the order surplus instead of a flat percent fee to the specified partner address.
3. Sign the received Order
This part of the code uses EIP-712 for Signing, which is a standard for signing structured data on Ethereum, allowing off-chain signatures that can be verified on-chain without gas costs. This ensures a secure, gas-efficient, and human-readable signing process.
4. Submit the signed Order
At this stage, the signed order is sent and an auction is performed between all the available Agents.
5. Check the Order Auction Status
This function is used to check the status of an order and retrieve a result.
If the order status is executed, it means a taker has filled the order, and the swap has been completed.
If the status is still 'PENDING' or 'OPEN', the order is waiting for execution.
A more detailed example of Delta usage, including fallback to Market (traditional swapping flow), can be found in examples.
Contracts
Portikus Adapter
Portikus Adapter is ParaSwap's Delta contract
When working on the API implementation, you’ll use the following contract addresses at these stages:
Order creation
Signing order
Submitting Order to API
On-Chain Execution
Delta’s contract has been deployed on Ethereum Mainnet and on Base. It shares the same address across both chains.
Addresses of Delta contract
Retrieve Delta price with fallback to Market
Get Delta Price with fallback to Market
GET https://api.paraswap.io/quote
When implementing this endpoint, you can enable API to fallback to market prices if the Delta pricing is not available. If the quote obtained comes from Market pricing data, you’ll get the learn more about the cause in the fallback reason parameter.
Query Parameters
srcToken*
string
Source Token Address.
srcDecimals*
integer
Source Token Decimals.
destToken*
string
Destination Token Address.
destDecimals*
integer
Destination Token Decimals.
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
SELL | BUY
Default: SELL.
chainId*
string
Chain ID. (Mainnet - 1, Optimism - 10, BSC - 56, Polygon - 137, Fantom - 250, zkEVM - 1101, Base - 8453, Arbitrum - 42161, Avalanche - 43114, Gnosis - 100).
userAddress
string
User's Wallet Address.
partner
string
Partner string.
mode
ALL | DELTA | MARKET
Preferred mode for the trade. In case of "all", Delta pricing is returned, with Market as a fallback.
Default: ALL.
Query Modes Explained
The endpoint behaves differently based on the mode passed:
DELTA- will return the Delta pricing data in thedeltafield, which can then be used to build, sign and submit a Delta Order.MARKET- will return the Market pricing data in themarketfield , which is an equivalent to the successful response from/prices?version=6.2of the Paraswap API, which can then be used to build a swap transaction.ALL- default mode. Will return the Delta pricing data in thedeltafield. In case the Delta prices are unavailable, fallback toMARKETmode and returns the Market pricing data. Also specifies the fallback reason infallbackReasonfield. Refer here for example of usage of this mode.
Examples for Successful Responses for each mode.
Most common fallback reasons and error types
The following is a list of the most common error messages and fallback reasons of the /delta/quote 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.
ValidationError- validation for params failedUnsupportedChain- the chain ID is not supported by Delta.UnsupportedToken- the token is not supported by Delta.SourceEth- Native chain token cannot be used as source token in Delta.UnsupportedSide-BUYis not supported by Delta yet.PricingError- internal oracle failed to provide a price.GasCostExceedsTradeAmount- estimated value paid for gas is bigger than trade amount.
Build a Delta Order to Sign
Build a Delta Order to Sign
POST https://api.paraswap.io/orders/build
This section explains how to construct a Delta Order, which is essential for executing trades using the ParaSwap Delta API. The /orders/build endpoint retrieves a Delta price and allows fallback to market prices.
A successfully built order includes a structured object ready for signing.
Common errors include validation failures, unsupported assets, and signature mismatches.
Use this guide to generate a Delta Order and prepare it for signing before submission.
Query Parameters
chainId*
string
Chain ID. (Mainnet - 1, Optimism - 10, BSC - 56, Polygon - 137, Fantom - 250, zkEVM - 1101, Base - 8453, Arbitrum - 42161, Avalanche - 43114, Gnosis - 100).
owner*
string
Order owner address.
beneficiary
string
Order beneficiary. Default: zero address, meaning owner address.
slippage
number
Slippage in base points (100 is 1%). Default: 100.
deadline
number
Order expiry time as UNIX timestamp. Default: 1 hour from order creation.
nonce
string
Arbitrary uint256 value to be used as order nonce. Default: value generated with internal algos. It is recommended to omit this param.
permit
string
Encoded permit to be used in order settlement. Supported permit types are described here. Default: 0x.
partiallyFillable
boolean
If true, order will be generated as partially fillable. Default: false.
partnerAddress
string
Address of the partner. Used to collect fees from the order. Default: zero address.
partnerFeeBps
number
Partner fee percent in base points (100 is 1%). Max value is 200. Default: 0.
partnerTakesSurplus
boolean
If true, partner will collect 50% of the order surplus instead of flat percent fee. Default: false.
Most common error types
ValidationError- validation for params failedUnsupportedChain- the chain ID is not supported by Delta.UnsupportedToken- the token is not supported by Delta.InvalidHmac-hmaccheck failed, meaningpriceobject returned from/quoteendpoint was mutated.
Supported Permits
Permit(ERC-2612)- expected to have 224 bytes length.Permit2TransferFromformat - expected length is 96 bytes (32 for permitNonce, 64 for compact signature), amount and deadline should be the same as inOrder.Allowanceformat - expected length is 192 bytes.
DAI Style Permit- expected length is 256 bytes.0x01- specialpermitvalue that signifies existingPermit2allowance.
Delta Contract should be specified as a spender is a permit.
Sign an Order
Once the Delta Order is built, it must be signed using the EIP-712 standard before submission. This section provides a working example using ethers.js and axios.
Example:
Partner Fees
The fees are enabled by encoding partnerAndFee param of the order, before its signed by a user.
The param includes three values:
partnerAddress- on-chain address which will be able to collect the fees.partnerFeeBps- flat fee percent which will be taken from the order. The value is in base points (100is1%), which the maximum allowed value of200.partnerTakeSurplus- a flag that, if set, allows the partner to collect50%of thesurplusas fees instead of the flat fee specified withpartnerFeeBps.
These are encoded into a single uint256 value, which then is used as partnerAndFee.
Submit a Delta Order
Submit Delta Order for Auction
POST https://api.paraswap.io/delta/orders
The Submit Delta Order for Auction endpoint allows you to submit a Delta order to be auctioned on ParaSwap Delta. This enables decentralized and efficient execution of large token swaps through the Delta smart contract.
By sending a properly formatted request, you can specify order details such as the source and destination tokens, amounts, deadline, and additional parameters required for execution.
Use this endpoint to initiate a Delta auction order and optimize your trade execution on the ParaSwap Delta network.
Request Body Params
signature*
string
Signature of the order from order.owner address. EOA signatures must be submitted in ERC-2098 Compact Representation.
chainId*
string
Chain ID. (Mainnet - 1, Optimism - 10, BSC - 56, Polygon - 137, Fantom - 250, zkEVM - 1101, Base - 8453, Arbitrum - 42161, Avalanche - 43114, Gnosis - 100).
partiallyFillable
boolean
Allow the order to be filled in parts. Default: false
partner
string
Partner string.
Example Responses:
The first example response indicates a successful order submission because it includes an id, orderHash, status, and other relevant order details. The status is "NOT_STARTED", meaning the order has been created but not yet processed.
The second response, { "error": "Validation failed with error" }, indicates a failed submission due to a validation issue, likely caused by missing or incorrect parameters in the request.
Track Delta Order Auction Status
Get Delta Order Auction Status
GET https://api.paraswap.io/delta/orders/:orderId
This endpoint enables users to retrieve real-time details of a specific auction, ensuring transparency and efficient execution monitoring.
Get Delta Orders for a User
GET https://api.paraswap.io/delta/orders
The Get Delta Orders for a User endpoint allows integrators to fetch all orders associated with a specific address, making it invaluable for dashboards, trade history tracking, and compliance purposes.
Query Parameters
userAddress*
string
User Address.
chainId
string
Filters orders by Chain ID.
page
integer
Default: 1.
limit
integer
Default: 100.
Most common error messages
These are the two most common messages when using this endpoint.
ValidationError- validation for params failedUnsupportedChain- the chain ID is not supported by Delta.
To avoid running into ValidationError and UnsupportedChain errors when using this endpoint, here are some recommendations:
Avoiding ValidationError
ValidationErrorCheck Required Parameters: Ensure all mandatory parameters are included in your request. Missing or incorrectly formatted fields often trigger this error.
Validate Data Types: Confirm that parameters match the expected types (e.g., numbers vs. strings, correct JSON structure).
Follow API Documentation: Double-check the expected format for each parameter in the official API documentation.
Avoiding UnsupportedChain
UnsupportedChainVerify Supported Chains: Check the API documentation or a dedicated "supported chains" endpoint to ensure the chain ID is compatible with Delta.
Use Correct Chain IDs: Some APIs require chain IDs in decimal format, while others expect hex. Ensure you’re using the correct format.
Example: Quote With Fallback
This example shows an implementation for token swapping using the ParaSwap API, particularly focusing on getting a quote for a token swap and handling both Delta pricing and a fallback to market pricing when Delta fails.
Example:
Expected Behavior for Integrators:
When executed, this script:
Connects to an Ethereum wallet.
Retrieves the user's wallet address and prepares to swap 100 DAI for PSP tokens on Ethereum Mainnet (Chain ID: 1).
Requests a quote from ParaSwap with the
mode: "all", meaning it will prioritize Delta pricing but fall back to market pricing if Delta is unavailable.If Delta pricing is available, the script:
Builds an order for execution.
Signs the order using EIP-712 structured signing.
Submits the order for execution through the Delta auction system.
Polls the order status to confirm whether it was executed.
If Delta pricing is not available, the script:
Logs the reason for the fallback.
Retrieves a market price route instead.
Builds a transaction using the market price.
Submits the transaction directly to the Ethereum network using the user's wallet.
This example ensures the swap execution is optimized for efficiency while providing a fail-safe fallback in case Delta pricing is unavailable. As a developer, you should expect a seamless experience for token swaps with automatic routing adjustments.
ParaSwap Market API
In this guide, you'll explore the ParaSwap Market API, its different versions, and the various actions it enables.
Start by reading the Overview section to better understand how the Market API aggregates liquidity across multiple DEXs and AMMs to provide optimal trade execution.
This guide will help you to:
Leverage the API effectively.
Retrieve a price and get the most optimal route for a trade.
Build parameters for a transaction with the response from the prices endpoint.
Find the optimal fee strategy for your integration.
Overview
ParaSwap Market API is the most straightforward and efficient way to access to the ParaSwap Protocol. It connects your application to a vast network of liquidity sources guaranteeing optimal token swap rates across multiple blockchain networks.
To get started, we recommend familiarizing yourself with the available API versions to understand their unique features and differences. From there, dive into the various endpoints tailored for specific tasks, whether you need to fetch a price quote, construct a transaction, or streamline both processes using the all-in-one Swap endpoint.
You’ll also find a practical example to guide you through the implementation process, making it easier to integrate ParaSwap into your application.
If you'd like to find the latest integrations, feel free to use DexLib, our open-source library that contains all live and pending DEX integrations.
API Versions
In this section you can find all the information related to ParaSwap API available versions
ParaSwap currently has two versions of its API available. It is highly recommended to integrate or upgrade to v6.2, the latest version of the Market API, to take full advantage of its latest innovations.
v6.2 introduces key enhancements, including gas optimizations and greater flexibility for partners in managing their fees.
API v6.2
Introduction to ParaSwap API v6.2
ParaSwap v6.2 has been released! See what's new here: https://twitter.com/paraswap/status/1803435422011498551
ParaSwap V6.2's main goal is to provide the best possible gas-optimized protocol for order routing. It has significant improvements in terms of smart contract architecture that achieve both best-in-class gas efficiency and scalability through modularity.
To use V6.2, you need to pass &version=6.2 query param when calling /prices. The process for swapping remains the same:
Call
GET /pricesto retrieve an optimal price for a given pair & amount.Call
POST /transactionsfor retrieving the Transaction Object that includes the call dataAlternatively, you can use GET
/swapto retrieve both the price config & Transaction Object.
You can also use the JavaScript/TypeScript SDK for easier integrations: https://github.com/paraswap/paraswap-sdk
No longer need to approve a different smart contract for ERC20 tokens. Augustus V6.2 is the only contract you need to interact with. More details here.
More control over partner fees: should you choose to take a surplus fee, you can cap it to 1% of the trade volume as protection for your users if it applies to your specific case. You can also send partner fees directly to the user. Take a look at the new params (
isCapSurplus,isSurplusToUser,isDirectFeeTransfer) params in /transactions section.Flat fees are capped at 2% as a security protection for users.
excludeDirectContractMethodsis no longer supported in /prices. It has been replaced byexcludeContractMethodsWithoutFeeModel, which ensures all swaps can be monetized.
Supported methods:
SELL:
swapExactAmountIn
swapExactAmountInOnUniswapV2
swapExactAmountInOnUniswapV3
swapExactAmountInOnBalancerV2
swapExactAmountInOnCurveV1
swapExactAmountInOnCurveV2
swapOnAugustusRFQTryBatchFill
swapExactAmountInOutOnMakerPSM
BUY:
swapExactAmountOut
swapExactAmountOutOnUniswapV2
swapExactAmountOutOnUniswapV3
swapExactAmountOutOnBalancerV2
swapOnAugustusRFQTryBatchFill
swapExactAmountInOutOnMakerPSM
API v5
Introduction to ParaSwap API version 5
Please note that as of the launch of v6.2, ParaSwap no longer maintains v5. We recommend all v5 integrations to upgrade to v6.2.
ParaSwap's goal is to deliver the best market prices by aggregating over multiple decentralized exchanges, market makers, and lending protocols.
ParaSwap API allows users to fetch optimal prices to swap from one token to another and then build transaction data that can be used to execute transactions on-chain. Currently, ParaSwap only supports EVM-based networks (Ethereum, BSC, Polygon, etc) and tokens following ERC20 standard.
Before you get deeper into the docs, here is a quick overview of the general flow you will use to interact with the ParaSwap API. Let's take the example of you wanting to swap 10 ETH to DAI.
First, you should call
/pricesendpoint (detailed documentation here) using an HTTP query likeGET https://api.paraswap.io/prices/?srcToken=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&destToken=0x6b175474e89094c44da98b954eedeac495271d0f&amount=10000000000000000000&srcDecimals=18&destDecimals=18&side=SELL&network=1&version=5. This will return the optimal prices using ParaSwap's Hopper AlgorithmIf you are satisfied with the price, you can call the
/transactionsendpoint (detailed documentation here). This will return a transaction object.You should then give the appropriate allowance to the
tokenTransferProxyfor the source token. You can find the address oftokenTransferProxyin the payload returned in the price endpoint. You can skip this step if a high enough allowance was already given.You can finally use this transaction data to execute the swaps on-chain by sending it to the provider.
Check out the following pages to understand the ParaSwap v5 API. To try out all API endpoints, visit the Open-API documentation of ParaSwap v5.
Developers can also use our JS/TS SDK for web and Node.js integrations https://github.com/paraswap/paraswap-sdk
If you want to do some swaps, you can directly use our UI.
Supported methods:
SELL:
simpleSwap
multiSwap
megaSwap
swapOnUniswapV2Fork
directUniV3Swap
directCurveV1Swap
directCurveV2Swap
directBalancerV2GivenInSwap
BUY:
simpleBuy
buy
buyOnUniswapV2Fork
directUniV3Buy
directBalancerV2GivenOutSwap
Retrieve a price: /prices
Get Price Route
GET https://api.paraswap.io/prices
This endpoint gets the optimal price and price route required to swap from one token to another.
You’ll find the parameters to build a successful query below:
Query Parameters
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.
All supported DEXs by chain can be found here
eg: UniswapV3, CurveV1
excludeDEXS
string
Comma Separated List of DEXs to exclude.
All supported DEXs by chain can be found here
eg: UniswapV3, CurveV1
excludeRFQ
boolean
Exclude all RFQs from pricing
eg: AugustusRFQ, Hashflow
Default: false
includeContractMethods
string
excludeContractMethods
string
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.
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
excludeContractMethodsWithoutFeeModel
boolean
Specify that methods without fee support should be excluded from the price route. Default: false
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
Here are two examples of a successful price response and a failed query.
The first query was a sell price request on Ethereum Mainnet (chainId: 1) using ParaSwap’s Market API. The request aimed to swap 1,000 USDC for ETH (destToken: 0xeeee...eeee) while retrieving the best possible route for the trade.
As a result, it successfully retrieved an optimized route for swapping 1,000 USDC to ETH via Uniswap V3, with minimal slippage and efficient execution while estimating gas costs.
Most common error messages
The following is a list of the most common error messages of the /prices 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.
Invalid route, from token should be the first token of the routeInvalid route, to token should be the last token of the routeToken not found. Please pass srcDecimals & destDecimals query params to trade any tokens-Check the doc for more details https://developers.paraswap.network/api/get-rate-for-a-token-pairInvalid tokens- (srcToken and destToken) or (route) params are not passedIf receiver is defined userAddress should also be definedIt is not allowed to pass both params: "positiveSlippageToUser" and "takeSurplus".- We advice removing "positiveSlippageToUser", because it is deprecatedexcludeDirectContractMethods param is deprecated, please use excludeContractMethodsWithoutFeeModel for newer versionsInvalid Amount- amount param is not a valid numberValidation failed: <error>- params validation failed (message has the exact reason for failure)Price Timeout- reverts when a query takes more time than expectedNo routes found with enough liquidityBad USD price
- src or dest tokens don’t have valid usd price Estimated_loss_greater_than_max_impactInternal Error while computing the price- something went wrong during the price route calculationInvalid max USD impact- maxUSDImpact is not a valid numberError while handling price request- something went wrong during the price route calculation
Build a transaction: /transactions
Build Transaction
POST https://api.paraswap.io/transactions/:network
Build parameters for a transaction with the response from /prices endpoint.
Path Parameters
Path parameters define the network on which the transaction will be executed. Since blockchain networks operate independently, specifying the correct network ensures that the API queries the right environment for liquidity and transaction execution.
network
number
Network ID. (Mainnet - 1, Optimism - 10, BSC - 56, Polygon - 137, Fantom - 250, zkEVM - 1101, Base - 8453, Arbitrum - 42161, Avalanche - 43114, Gnosis - 100).
Query Parameters
As an integrator, you can modify the behavior of the API call based on the Query parameters. This allows you to customize the response based on your needs.
gasPrice
string
Gas-price to be used for the transaction in wei.
ignoreChecks
boolean
Allows the API to skip performing on-chain checks such as balances, allowances, as well as possible transaction failures.
*Note: The response does not contain gas parameter when ignoreChecks is set to true.
Default: false
ignoreGasEstimate
boolean
Allows the API to skip gas checks
*Note: The response does not contain gas parameter when ignoreGasEstimate is set to true.
Default: false
onlyParams
boolean
Allows the API to return the contract parameters only.
Default: false
eip1559
boolean
Allows the API to return EIP-1559 styled transaction with maxFeePerGas and maxPriorityFeePerGas paramters.
*Note: We currently support EIP1559 transactions in the following chains:
Mainnet, Ropsten, and Avalanche.
Default: false
Request Body
The request body provides the details needed to execute a swap, including token details, amounts, pricing data, and user-specific parameters.
srcToken
string
Destination Token Address. Only Token Symbol could be specified for tokens from /tokens.
srcDecimals
integer
Source Token Decimals. (Can be omitted if Token Symbol is provided for srcToken).
destToken
string
Destination Token Address. Only Token Symbol could be specified for tokens from /tokens.
destDecimals
integer
Destination Token Decimals. (Can be omitted if Token Symbol is provided for destToken).
srcAmount
integer
Source Amount with decimals. Required if side=SELL. Could only be omitted if slippage is provided when side=BUY
destAmount
integer
Destination amount with decimals. Required if side=BUY. Could only be omitted if slippage is provided when side=SELL.
priceRoute
object
priceRoute from response body returned from /prices endpoint. priceRoute should be sent exactly as it was returned by the /prices endpoint.
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
userAddress
string
Address of the caller of the transaction (msg.sender)
txOrigin
string
Whenever msg.sender (userAddress) i.e. address calling the ParaSwap contract is different than the address sending the transaction, txOrigin must be passed along with userAddress.
receiver
string
Address of the Receiver (that will receive the output of the swap). Used for Swap&Transfer.
partnerAddress
string
Address that will be entitled to claim fees or surplus.
*Note: Fees have to be claimed from the Fee Claimer contract unless isSurplusToUser or isDirectFeeTransfer are used
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)
*Note: Fees have to be claimed from the Fee Claimer contract unless isSurplusToUser or isDirectFeeTransfer are used
partner
string
Your project name.
Used for providing analytics on your project swaps.
permit
string
Hex string for the signature used for Permit. This can be used to avoid giving approval. Helps in saving gas.
deadline
integer
Timestamp (10 digit/seconds precision) till when the given transaction is valid. For a deadline of 5 minute, deadline: Math.floor(Date.now()/1000) + 300
E.g.: 1629214486
isCapSurplus
boolean
Allows for capping the surplus at 1% maximum.
Default: true
takeSurplus
boolean
Allows to collect surplus. Works with partnerAddress
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
Example:
Here’s an example of a successful and failed transaction.
Most common error messages
The following is a list of the most common error messages of the /transactions 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.
Validation failed: permit signature should be lower than 706Validation failed: <error>- params validation failed (message has the exact reason of failure)Missing price route- price route param is not passedMissing srcAmount(sell)Cannot specify both slippage and destAmount(sell)Missing slippage or destAmount(sell)Missing slippage or srcAmount(buy)Source Amount Mismatch(sell)Destination Amount Mismatch(buy)Missing destAmount(buy)Cannot specify both slippage and srcAmount(buy)Network MismatchSource Token MismatchDestination Token MismatchContract method doesn't support swap and transferSide MismatchSource Decimals MismatchDestination Decimals MismatchIt is not allowed to pass both params: "positiveSlippageToUser" and "takeSurplus".- We advise removing "positiveSlippageToUser" because it is deprecatedWhen "isSurplusToUser"="true", "takeSurplus" must be also "true" and either "partnerAddress" or "partner" must be setWhen "isDirectFeeTransfer"="true", please also set "takeSurplus"="true" and provide partner/fee information via "partnerFeeBps" & "partnerAddress" or valid "partner" params; or add "referrer" paramInternal Error while building transaction- something went wrong during the transaction buildUnable to build transaction <code>- something went wrong during the transaction buildIt is not allowed to have limit-orders Dex or paraswappool Dex in route and 'ignoreChecks=true' together. Consider requesting the price with excluded limit-orders if you want to use 'ignoreChecks': &excludeDEXS=ParaSwapPool,ParaSwapLimitOrdersIt seems like the rate has changed, please re-query the latest PriceThe rate has changed, please re-query the latest PriceThis transaction has some errors and may fail. Please contact support for more detailsNot enough <token> balanceNot enough <token> allowance given to TokenTransferProxy(<spender>)Unable to check price impact- src or dest tokens don’t have valid usd price
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.
It is designed to simplify the trading process by combining price estimation and transaction calldata generation into a single API call. This makes it a convenient option for users who want a quick and streamlined way to execute trades without handling multiple requests. However, while it offers ease of use, it also comes with certain limitations.
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 & Transaction Building
GET https://api.paraswap.io/swap
This endpoint gets the optimal price and price route required to swap from one token to another.
Additionally the swap endpoint also generates the parameters required for the transaction.
Query Parameters
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)
*Note: Fees have to be claimed from the Fee Claimer contract unless isSurplusToUser or isDirectFeeTransfer are used
partnerAddress
string
Address that will be entitled to claim fees or surplus.
*Note: Fees have to be claimed from the Fee Claimer contract unless isSurplusToUser or isDirectFeeTransfer are used
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
Example:
Here’s an example of an integrator that used the swap function to request a price and generate a transaction.
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 APICan not receive price route- failed to receive price route from the pricing API response
Example: Fetch Price & Build Transaction
Here’s an example of an implementation for ParaSwap's Market API. It utilizes ParaSwap's endpoints to fetch pricing information and build transactions for token swaps.
Get Tokens List
Get tokens list for a network
GET https://api.paraswap.io/tokens/:network
This endpoint allows you to obtain a list of tokens curated by ParaSwap.
Path Parameters
network
number
Network ID. (Mainnet - 1, Optimism - 10, BSC - 56, Polygon - 137, Fantom - 250, zkEVM - 1101, Base - 8453, Arbitrum - 42161, Avalanche - 43114, Gnosis - 100).
Default: 1.
ParaSwap's API is not limited to the tokens that are listed on the tokens endpoint. Tokens endpoint is merely a list of tokens curated by ParaSwap. This list is not actively maintained and will soon be deprecated. To use a more up-to-date list of tokens it is suggested to use token-lists.
Limit Orders
What is ParaSwap Limit Order Protocol?
ParaSwap Limit Order Protocol is a set of smart contracts developed by ParaSwap and available in Ethereum, Polygon, Binance Smart Chain, Fantom, Avalanche, Arbitrum, and Optimism.
The goal of ParaSwap’s Multichain Limit Order Protocol is to become a public good with which anyone can interact and build dApp use cases in a completely decentralized way.
Introduction
Key Features
The protocol goes beyond ERC-20 token limit orders and enables, among others, ERC721 NFT limit orders, peer-to-peer, RFQ, and OTC trading.
Top gas efficiency: ParaSwap’s limit orders offer the most gas-efficient transactions in the market. Our benchmark shows that ParaSwap limit orders are 6% more gas efficient than 1inch and 8% better than 0x.
Greater flexibility for users: the protocol allows not only token-to-token trade but also token-to-NFT, multiple token-to-NFT trading, and NFT-to-NFT swap. Moreover, it allows users to buy & sell ERC721 in the token of their choosing, independently of the other party’s token choice.
How can it be used? Web, mobile, and API
ParaSwap Limit Order Protocol can be accessed via ParaSwap's web and mobile apps and through ParaSwap Limit Orders API.
Limit orders are created and stored off-chain, and signed according to EIP-712. They are recorded on-chain once filled.
Supported chains and tokens
Chains
Ethereum
Arbitrum
Avalanche
BSC
Fantom
Optimism
Polygon
Tokens
ERC-20
ERC721
ERC1155
Contracts
AugustusRFQ
AugustusRFQ is ParaSwap's limit order contract
Addresses of AugustusRFQ contract
Polygon zkEVM
On chain Data Structure
ERC20: Order structure
maker: address of owner of the order. (The user or contract who want to swapmakerAssettotakerAsset).taker: address that can fulfilled this order on chain.taker == 0: anybody can fill the ordertaker != 0: during the execution we will verify thatmsg.sender == taker. (taker needs to be the contract or user who fill an order).
nonceAndMeta: This field combine nonce value (guarantee uniqueness of the order) and some meta dataexpiry: expiry timestamp in seconds. Can also be set 0 for an order that never expiresmakerAsset: address of ERC20 token that maker want to sell to the taker.takerAsset: address of ERC20 token that maker want to buy from the taker.makerAmount: amount ofmakerAssetthat maker want to swap to taker.takerAmount: amount ofmakerAssetthat maker want to swap to taker.signature: EIP712 Signature of a JSON Object with all above fields signed with the private key of maker.
ERC 20/721/1155: Order structure
Token type encoding
maker: address of owner of the order. (The user or contract who want to swapmakerAssettotakerAsset).taker: address that can fulfilled this order on chain.taker == 0: anybody can fill the ordertaker != 0: during the execution we will verify thatmsg.sender == taker. (taker needs to be the contract or user who fill an order).
nonceAndMeta: This field combine nonce value (guarantee uniqueness of the order) and some meta dataexpiry: expiry timestamp in seconds. Can also be set 0 for an order that never expiresmakerAsset: Packed field containing address of an ERC20/721/1155 token that maker want to sell to the taker (between0-19 bits). Token type encoded as show above on20-21 bits.makerAssetId: ignored for ERC20. For ERC/721/1155 themakertoken.takerAsset: Packed field containing address of an ERC20/721/1155 token that maker want to sell to the taker (between0-19 bits). Token type encoded as show above on20-21 bits.makerAssetId: ignored for ERC20. For ERC/721/1155 thetakertoken.makerAmount: amount ofmakerAsset(at idmakerAssetIdfor ERC/721/1155) that maker want to swap to taker.takerAmount: amount oftakerAsset(at idtakerAssetIdfor ERC/721/1155) that maker want to swap to taker.signature: EIP712 Signature of a JSON Object with all above fields signed with the private key of maker.
Data structure in our centralized system
This page explains the data structure of ParaSwap's centralized service handling limit orders. It's adding some features like:
tracking maker
balanceandallowancefor ERC20 tokens.tracking state of orders
Fulfillment.
Cancellation.
Expiration.
Partially fulfillment.
For more information, please refer to the following document:
On chain Data StructureERC20: Order structure
Difference with on-chain limit order
nonceAndMeta: In our centralized system we force nonce and meta to be constructed from an address plus a random integer between0and2 ^ 53 - 1shifted 160 bits. The address that we pack is the actual taker address. (The address that swaptakerAssettomaketAsset)
takerFromMeta: is the decoded taker fromnonceAndMeta. In Augustus contract we check the actualtakerAddress(The address who swaptakerAssettomakerAsset) by extracting its value fromnonceAndMeta.fillableBalance: is the amount that remains to be filled and can be used to check if the amount is partially filled. (fillableBalance≠makeAmount)swappableBalance: is the actual amount that can be filled at this time.makerBalance: max amountmakerAddresscan fill the limit order.orderHash: hash of the on-chain Data structure.permitMakerAsset: always null for now will be used to store permit.
type:P2P/LIMITdifferentiatep2pfrom normal ordersP2P: hastakerFromMetaset to some specific address.LIMIT: hastakerFromMetaset to0x....0.
state:PENDING/FULFILLED/EXPIRED/CANCELLED.PENDING: order is still usable.FULFILLED: order is fully fulfilled.EXPIRED: order is expired.CANCELLED: order is canceled.
NFT ERC 20/721/1155 Order structure
Difference with on-chain NFT order
makerAsset: is the decoded address of themakerAssetfrom our limit order contract.makerAssetId: is the decoded token type from themakerAssetfrom our limit order contract.takerAsset: is the decoded address of themakerAssetfrom our limit order contract.takerAssetId: is the decoded token type from thetakerAssetfrom our limit order contract.takerFromMeta: is the decoded taker fromnonceAndMeta. In Augustus contract we check the actualtakerAddress(The address who swaptakerAssettomakerAsset) by extracting its value fromnonceAndMeta.fillableBalance: is the amount that remains to be filled and can be used to check if the amount is partially filled. (fillableBalance≠makeAmount)orderHash: hash of the on-chain Data structure.permitMakerAsset: always null for now will be used to store permit.
type:P2P/LIMITdifferentiatep2pfrom normal ordersP2P: hastakerFromMetaset to some specific address.LIMIT: hastakerFromMetaset to0x....0.
state:PENDING/FULFILLED/EXPIRED/CANCELLED.PENDING: order is still usable.FULFILLED: order is fully fulfilled.EXPIRED: order is expired.CANCELLED: order is canceled.
API References
API Architecture
API is separated in two different endpoints:
/ft/for fungible token: this endpoints is to interact with limit orders from one ERC20 to another ERC20./ft/orders/: to interact with limit orders fillable by anybody./ft/p2p/: to interact with p2p orders.
/nft/for non fungible token: this endpoints is used to interact with limit orders from any supported token to any supported token./nft/p2p/to interact with limit orders fillable by anybody./nft/orders/to interact with p2p orders.
Fungible tokens
/ft/ fungible api
Create a limit order
POST /ft/orders/:chainId/
Examples
The data to be sent to the endpoint consists of limit order parameters and a signature of those parameters produced by order maker.
Generating this data consists of these steps:
1. compose order parameters
2. sign an object with these parameters with eth_signTypedData
3. combine order parameters with the signature.
The resulting data will be validated and accepted by the POST endpoint and will have the specified shape.
Query parameters:
chainId:network id (Ethereum Mainnet = 1)
Body parameters
Important notice:
nonceAndMeta: needs to be encoded as described in:
Response
Understand the response by checking our dedicated page:
Data structure in our centralized systemCreate a p2p limit order
You can notice the difference between p2p and normal limit orders by looking at the path.
POST /ft/p2p/:chainId/
Examples
The process of composing the order and the payload to POST to API endpoint is pretty much the same as with usual non-p2p orders.
The only differences are:
slightly different route (
/ft/p2p/...instead of/ft/orders/...)taker should contain Augustus Swapper address
the intended order taker is encoded in the nonceAndMeta field
Query parameters:
chainId:network id (Ethereum Mainnet = 1)
Body parameters
Important notice:
nonceAndMeta: needs to be encoded as described in (here we are in the p2p case so we should add the address of the person you want to execute a trade innonceAndMeta):
Response
Understand the response by checking our dedicated page:
Data structure in our centralized systemGet limit orders by maker
GET /ft/orders/:chainId/maker/:address
Examples
GET /ft/p2p/:chainId/maker/:address (for p2p)
Examples
Query parameters:
chainId:network id (Ethereum Mainnet = 1).address: will return you the orders in whichmaker == address.limit(Optional): max count of orders.offset(Optional): pagination offset.hideSmallBalances(Optional, default: false): boolean if true will hide all orders in which 99.99% of the value has already been swapped.
Response
Understand the response by checking our dedicated page:
Data structure in our centralized systemGet limit orders by taker
GET /ft/orders/:chainId/taker/:address
Examples
GET /ft/p2p/:chainId/taker/:address (for p2p)
Examples
Query parameters:
chainId:network id (Ethereum Mainnet = 1).address: will return you the orders in which
taker == address.limit(Optional): max count of orders.offset(Optional): pagination offset.hideSmallBalances(Optional, default: false): boolean if true will hide all orders in which 99.99% of the value has already been swapped.
Response
Understand the response by checking our dedicated page:
Data structure in our centralized systemGet Pairs
Get Orderbook
GET /ft/orders/:chainId/orderbook/
Examples
Query parameters:
makerAsset: address of an ERC20 token
takerAsset: address of an ERC20 token
Response
Data structure in our centralized systemThis is returning you all the orders which respect makerAsset == makerAsset and takerAsset == takerAsset.
Fill a limit order
In order to fill an order, a SwappableOrder data is required as an input.
It can be retrieved from API web service or composed by maker.
Parameters
This data can then be supplemented by additional required params and sent to ParaSwap web API to generate Augustus Swapper route for the fulfilment transaction:
The returned transaction params can be used to send a transaction.
Example
Cancel a limit order
To cancel an earlier placed order(s), a transaction AugustusRFQ.cancelOrder (or CancelOrders) needs to be sent on behalf of the order's maker.
Transaction parameters:
orderHash: limit order unique id
Example
NFT
/nft/ non-fungible api
Create an order
POST /nft/orders/:chainId/
Examples
The process of composing an NFT order and the payload to POST to API endpoint is pretty much the same as with usual "fungible to fungible token" orders.
The only differences are:
slightly different endpoint route (
/nft/orders/...instead of/ft/orders/...)makerAssetTypeandtakerAssetTypefields are requiredmakerAssetandtakerAssetcontain not plain token addresses, but token address and token type encoded as described in Body parameterstakerAssetIdandmakerAssetIdwill contain NFTtokenId. If it's "NFT to fungible" order,takerAssetId= 0 andmakerAssetId= tokenID. If it's "fungible to NFT", then the opposite.
Query parameters:
chainId:network id (Ethereum Mainnet = 1)
Body parameters
nonceAndMeta: needs to be encoded as described in:
makerAssetandtakerAssetneeds to be encode as packed field containing address of an ERC20/721/1155 token that maker want to sell to the taker (between0-19 bits). Token type encoded as show above on20-21 bits.
Example encoding in JavaScript:
Response
Understand the response by checking our dedicated page:
Data structure in our centralized systemCreate a p2p order
You can notice the difference between p2p and normal limit orders by looking at the path.
POST /nft/p2p/:chainId/
Examples
The process of composing the order and the payload to POST to API endpoint is pretty much the same as with usual non-p2p orders.
The only differences are:
slightly different route (
/nft/p2p/...instead of/nft/orders/...)taker should contain Augustus Swapper address
the intended order taker is encoded in the nonceAndMeta field````
Query parameters:
chainId:network id (Ethereum Mainnet = 1)
Body parameters
nonceAndMeta: needs to include the actual taker as described here:
makerAssetandtakerAssetneeds to be encode as packed field containing address of an ERC20/721/1155 token that maker want to sell to the taker (between0-19 bits). Token type encoded as show above on20-21 bits.
Example encoding in JavaScript:
Response
Understand the response by checking our dedicated page:
Data structure in our centralized systemGet NFT orders by maker
GET /nft/orders/:chainId/maker/:address
Examples
GET /nft/p2p/:chainId/maker/:address (for p2p)
Examples
Query parameters:
chainId:network id (Ethereum Mainnet = 1).address: will return you the orders in whichmaker == address.
Response
Understand the response by checking our dedicated page:
Data structure in our centralized systemGet NFT orders by taker
GET /ft/orders/:chainId/taker/:address
Examples
GET /ft/p2p/:chainId/taker/:address (for p2p)
Examples
Query parameters:
chainId:network id (Ethereum Mainnet = 1).address: will return you the orders in which
taker == address.
Response
Understand the response by checking our dedicated page:
Data structure in our centralized systemGet orderbook
GET /nft/orders/:chainId/orderbook/
Query parameters:
makerAsset (optional): address of an ERC20/721/1155 token
makerAssetType (optional): encoded token type ERC20/721/1155 (0: ERC20, 1: ERC1155, 2: ERC721)
takerAsset (optional): address of an ERC20/721/1155 token
takerAssetType (optional): encoded token type ERC20/721/1155 (0: ERC20, 1: ERC1155, 2: ERC721)
Example:
Get the whole orderbook
Get orderbook where
makerAssetequal0x2953399124f0cbb46d2cbacd8a89cf0599974963
Get orderbook where
makerAssettype isERC1155andtakerAssetisERC20:
Response
Fill a limit order
In order to fill an order, a SwappableNFTOrder data is required as an input.
It can be retrieved from API web service or composed by maker.
Parameters
This data can then be supplemented by additional required params and sent to ParaSwap web API to generate Augustus Swapper route for the fulfilment transaction:
The returned transaction params can be used to send a transaction.
Example
Cancel a limit order
The cancellation of an NFT order works in the same way as the cancelation of "fungible tokens" order
Transaction parameters:
orderHash: limit order unique id
Example
Typescript
SDK for the ParaSwap API
Refer to the documentation of the ParaSwap API: https://developers.paraswap.network
Features
Versatility: works with both web3 and ethers without direct dependency
Canonical: bring only the functions you actually need
Lightweight: 400B Gzipped for the minimal variant
Installing ParaSwap SDK
Using ParaSwap SDK
There are multiple ways to use ParaSwap SDK, ranging from a simple construct-and-use approach to a fully composable bring what you need approach which allows for advanced tree-shaking and minimizes bundle size.
Simple SDK
Can be created by providing chainId and either axios or window.fetch (or alternative fetch implementation). The resulting SDK will be able to use all methods that query the API.
If optional providerOptions is provided as the second parameter, then the resulting SDK will also be able to approve Tokens for swap.
Composed SDK
Import the necessary functions
Construct the ParaSwap object
To approve ParaSwap contracts to swap an ERC20 token
To get the rate of a token pair
Where priceRoute contains the rate and the distribution among exchanges, checkout the OptimalRates type for more details.
To build a transaction
To sign a Limit Order
Playground
Interact with the ParaSwap SDK in a CodeSandbox playground here
Bundle Optimization
For bundle-size savvy developers, you can construct a lightweight version of the SDK and bring only the functions you need.
e.g. for only getting rates and allowances:
Legacy
The ParaSwap class is exposed for backwards compatibility with previous versions of the SDK.
Or you can use ethers in place of web3
By analogy to constructPartialSDK, you can leverage a lightweight version of the sdk for fetching only.
Refer to this README for depecreated documentation for functions usage.
Refer to SDK API documentation for detailed documentation on the methods provided in this SDK.
Tests
To run yarn test it is necessary to provide PROVIDER_URL=<mainnet_rpc_url> environment variable. If it is necessary to run tests against a different API endpoint, provide API_URL=url_to_API environment variable.
Python
https://github.com/paraswap/paraswap-python-sdk
AugustusRFQ API Specification
Want to become a market maker on ParaSwap? This document describes the API you need to provide to us to make that happen!
Objectives
This is intended to be a common API format for all market makers to use, substantially reducing the amount of work we have to do to integrate a new market maker, and most of the back and forth agreeing a protocol between us.
This specification is newly created for new market makers wanting to integrate against ParaSwap via our efficient AugustusRFQ protocol smart contracts.
How does it work?
In ParaSwap, market makers are enabled by them providing us with an API (one for each chain) to get information on what tokens they support, which base/quote pairs, and the price grid containing something akin to an order book with lists of bids and asks defining the pricing curve.
This information is regularly requested to keep the prices up to date. To enable more control on update of prices, and also save bandwidth potentially, it is recommended to support streaming price grid updates to us via WebSockets.
When a user on ParaSwap requests pricing, we go through all DEXs and market makers, computing prices. For market makers, this means using the previously cached price grid. We cannot do a request for (indicative) quote on each user individually, as that would make a huge volume of requests and add unwanted latency.
When a user comes to actually make a swap using a market maker, we then contact the market maker for a firm quote, in the form of a signed order, which can be executed on chain using ParaSwap's AugustusRFQ contract. This may be requested for an amount in either the bought or sold asset.
Users may be blacklisted by a market maker for making too many swap requests without actually executing the swap on chain. To avoid issues, we request market makers to provide a list of blacklisted users. This allows us not to provide pricing to that user for the market maker that has blacklisted them, and prevents subsequent failure on transaction building.
Should a market maker not fulfill their promise to provide a signed order for a given amount when requested, or give a bad price in the order that is returned (i.e. deviating from the price they have given in the price grid) they may be punished by having their market making disabled in ParaSwap. This may also happen if the signature cannot be validated (as either EOA or via smart contract), there is insufficient allowance to AugustusRFQ contract, or insufficient funds in the maker wallet.
Endpoints
All regular HTTP endpoints (except WebSockets) should have a common base URL that we can use to make requests. These endpoints must be secured using the procedures described below, however they may also employ IP whitelisting of ParaSwap servers for additional security. All endpoints should return JSON data as a response at all times, even if there is an error. All error responses should return an unsuccessful HTTP response code (4xx or 5xx) and in the body a JSON object with the key "error" containing a string describing the error. All non-error responses may include a "message" key in the top level object, alongside the normal payload data, the contents of which will be logged on ParaSwap servers for any request.
A WebSocket API is optional and may be configured on a different URL than the other endpoints (but it could also use the same URL with /ws at the end, as you prefer...).
Authentication (optional)
There are three key pieces of information we require from a market maker for security purposes:
Domain - this is a string you can use to identify traffic coming from us (in case you want to enable market making with someone else), and optionally to differentiate between production, staging and test. In the simplest case this can simply be the string
"paraswap".Access Key - this is a string that we will send back to you in request headers as a kind of passcode to quickly check that the request is coming from us. It may be different for each domain and it should not be shared with anyone except ParaSwap.
Secret Key - this is a string used by us to authenticate our requests to your servers as detailed below. It may be different for each domain and it should not be shared with anyone except ParaSwap.
In order to authenticate our requests we will do the following:
Get the current timestamp as milliseconds since Unix epoch (i.e. that returned by
Date.now()in JavaScript)Compute the payload to be signed by concatenating the following (with no spaces or other separator between):
Timestamp (as a string in decimal form)
HTTP method in UPPERCASE (will be
GETorPOST)Path of the request (the part after the domain, beginning with a
/) e.g./prices. Note that if the base URL already contains a path e.g./mainnetit will be included.Query parameters that were passed in the URL exactly as given including the initial
?e.g.?base=WETH"e=USDC. If there are no query parameters, use an empty string instead. Note that none of the endpoints in this specification use query parameters, so this part will normally be an empty string.If present, the payload sent in a e.g.
POSTrequest, exactly as sent and received. This will always be a JSON object in this specification, enclosed by{}. If no payload e.g. forGETrequest, use an empty string.
So a full payload may look something like this (if the URL used is e.g.
https://pspool.org/endpoint?key=value):1234512345123POST/endpoint?key=value{"amount":"123"}For WebSockets connection opening we assume current timestamp, method ofGET, the path of the URL used to connect, no query parameters and no payload.Compute the HMAC-SHA256 of this payload in hexadecimal using the Secret Key as the key. We would do this using Node.js crypto library (can be used as a reference) e.g.
const { createHmac } = require('crypto'); const hmac = createHmac('sha256', '<secret key>'); hmac.update('<payload>'); console.log(hmac.digest('hex'));Attach the following headers to the request:
X-AUTH-DOMAIN- the Domain as described earlierX-AUTH-ACCESS-KEY- the Access Key specified for the DomainX-AUTH-TIMESTAMP- the timestamp used to create the signatureX-AUTH-SIGNATURE- the HMAC-SHA256 computed in the previous step
It is mandatory for the market maker to verify all these headers are correct/matching and the timestamp is sufficiently close to the current time (e.g. +/- 30 seconds). Otherwise, the request should be rejected with an appropriate error message to describe the issue.
Tokens endpoint
Path: /tokens
Method: GET
This endpoint provides details of all tokens used by the market maker. The response should be a JSON object with the key "tokens", which in turn contains an object containing a number of entries, the key of which is a Token ID (recommended to use the token's symbol if it is unique), and the value is an object with the following fields (most are just for informational purposes):
"symbol"(string) - the token's symbol as determined by the market maker (should probably be the same as the one provided by the token's contract)"name"(string) - a full name for the token as determined by the market maker (should probably be the same as the one provided by the token's contract)"description"(string) - a description of the token, noting any important details where appropriate e.g. if it has been deprecated in favour of another token"address"(string) - the address of the token (case is ignored and normalized to lowercase on our side)"decimals"(number) - the number of decimals this token has i.e. which power of 10 value represents one whole token when it is processed on chain, normally the value returned by thedecimals()method of the token's contract"type"(string) - type of token, for now we only support"ERC20"for market making (but we may also support"ERC1155"or"ERC721"in future since they are implemented in the smart contract)
This is an example of what to return from this endpoint (but without the newlines, indentation, spacing etc. that are not required, and given here to improve readability):
Pairs endpoint
Path: /pairs
Method: GET
This endpoint provides a list of trading pairs supported by this market maker (or recently disabled), mapping Pair IDs to base and quote Token IDs, and also giving an estimated indication of liquidity in USD terms associated with this pair (this is used to assist with finding routes between tokens). Pairs should normally only be given in one direction of base vs. quote since the pricing of the other direction can be easily derived.
The response should be a JSON object containing the key "pairs", which in turn contains a JSON object containing a number of entries, the key of which is the Pair ID, and the value being a JSON object with the following:
"base"(string) - Token ID representing the base token of this pair (the token which the bids/asks are for)"quote"(string) - Token ID representing the quote token of this pair (the token in which prices are given)"liquidityUSD"(number) - an estimate of the liquidity the market maker has backing this pair, in US dollar terms (could be the maximum the market maker is willing to sell in both tokens, converted to USD and added together)
The Pair ID is recommended to be base token ID/symbol followed by / then the quote token ID/symbol. Here is an example payload returned from this endpoint (again ignoring newlines/indentation/spacing):
Prices endpoint
Path: /prices
Method: GET
This endpoint provides the full grid of price curves for all the supported pairs, which ParaSwap will store in its cache, and can also specify pairs to remove from the cache, or even restrict trading to a single direction.
The response should be a JSON object containing the key "prices", which in turn contains a JSON object with a number of entries, with the key being a Pair ID, and the value being an object which may contain the keys "bids" and "asks" (omitting either key means that trading in that direction is disabled and the corresponding cache entry will be cleared; to disable the pair entirely, both can be omitted so the object is empty {}).
Both "bids" and "asks" if present, should consist of an array of [price, amount] tuples defining the price curve as an order book, where price is a string representing the price of one base token in terms of the quote token, and amount is a string representing the amount of base token for this entry. We use bignumber.js library to parse these strings as decimal numbers with high precision. When computing a price the "orders" (tuples) are filled in sequential order, until the desired amount is reached. As such it is expected that the entries start with the best price and get progressively worse (however this is not enforced, so any price curve can be used). It is also expected that the best ask price is above the best bid price (this is not enforced neither, so market makers can risk arbitrage to deliver market beating prices and/or accelerate trading volume if they so wish).
Here is an example payload (newlines/indentation/spacing may be removed in the real thing):
In this example, trading for WETH/USDT is disabled (the cached prices for it will be cleared). A user selling 1.5 WETH to this market maker should receive 1540 * 0.5 + 1500 * 1 = 2270 USDC (average price 1513.333 USDC), whereas buying 10 WETH from the market maker, they would spend 1560 * 1 + 1580 * 1.5 + 1600 * 2 + 1650 * 5.5 = 16205 USDC (average price 1620.5 USDC). For computing prices based on a quote token amount (USDC in this case) we invert the order book (bids become asks and vice versa, new price is computed as 1 / price, and new amount is price * amount), then use the same process.
Note that if you wish to remove a pair from trading, it should not be removed from /pairs endpoint straight away. Instead, it must be retained there and given prices of {} as shown above for WETH/USDT for a period of time, after which it can finally be removed.
Failing to respond to this endpoint or responding with an error will cause market making to be temporarily disabled for this market maker, which may be done intentionally if you wish to cease trading entirely for a period of time.
Firm quotes endpoint
Path: /firm
Method: POST
This endpoint is used to obtain a firm rate from the market maker, which is represented as a signed order for the AugustusRFQ smart contract.
For use in the ParaSwap system the taker is set as a ParaSwap contract (depending on execution context it can be Augustus V5, Augustus V6 or another contract) and the user of ParaSwap (the msg.sender to AugustusSwapper) is encoded as metadata in the nonceAndMeta field; AugustusSwapper or other contracts are programmed to always check the user and metadata are matching when interacting with AugustusRFQ, so that no one can steal the order from the user and importantly to avoid users spamming requests for firm quotes, since they have to use a real user address and this address can be blacklisted by the market maker if they do so.
The body of the POST request will contain the following in a JSON object:
"makerAsset"(string) - address of the token the maker is selling"takerAsset"(string) - address of the token the taker is selling"makerAmount"or"takerAmount"(string) - amount of the maker or taker asset respectively that is to be traded (only one may be specified and the other is calculated by the market maker based on current prices), this is specified as an integer by scaling up by 10^decimals"userAddress"(string) - address of the user as described above"takerAddress"(string) - address of the ParaSwap contract that fills the order passed by ParaSwap on calling POST /firm (either Augustus or another contract depending on the execution context. For V5 it's always AugustusV5, for V6 it's either AugustusV6 or Executors). These addresses can be verified in the documentation here or by the API endpoint here.
Here is an example payload sent to market maker (will be sent without newlines/indentation/spacing, the case of alphabetic characters in addresses is not specified, it may be all lowercase/uppercase or checksum encoded, the market maker should normalize it to the desired format):
This request represents a user selling 1.5 WETH for USDC.
Note that the specified amount specified in taker or maker asset may be slightly larger than the amount the user is able to swap, so that there is some flexibility if e.g. it is part of a multihop and the user receives less/more of the taker asset from a previous swap.
The response to this request should be a JSON object containing the key "order", which in turn contains a JSON object with the following fields:
"nonceAndMeta"(string) - a number (uint256) which encodes the user's address in the lower 160 bits and is otherwise filled with random/unpredictable data i.e. to calculate this, convert the address to an integer, and add it to a random integer shifted left by 160 bits (the random integer must be less than 2^96), e.g. in Python(random.randint(0, 2**96 - 1) << 160) + int(address, 16)"expiry"(number) - the time in seconds past UNIX epoch at which this order becomes no longer executable, this should be at least 2 minutes in the future"makerAsset"(string) - same as one passed in"takerAsset"(string) - same as one passed in"maker"(string) - this is the address containing the market maker's funds and it must have approved the AugustusRFQ contract to spend them, it is also the signer of the order if it is an EOA, otherwise it is a smart contract implementing EIP-1271"taker"(string) - the address of the contract that fills the order which can be picked from the request payload (either Augustus or another contract depending on the execution context. Augustus addresses can be verified here)"makerAmount"(string) - same as that passed in or calculated from the taker amount"takerAmount"(string) - same as that passed in or calculated from the maker amount"signature"(string) -0xfollowed by any number of bytes encoded in hexadecimal (lowercased) representing thebytessignature in the AugustusRFQ smart contract (the order hash of all other fields listed here is computed using EIP-712, and this must be signed using either an EOA or a smart contract EIP-1271 signature)
For creating the signature using an EOA maker address, please refer to the ParaSwap SDKs (TypeScript or Python) for sample code or even consider using them directly. For example in the Python SDK you can use the function create_managed_p2p_order to create a suitable order and OrderHelper.sign_order to sign it using web3. If you use a EIP-1271 signature it depends on your smart contract how the signing will work, so you may need custom code.
Here is an example response payload (yet again ignore newlines/indentation/spacing):
This payload corresponds to previously given examples regarding assets and prices etc.
If the request cannot be processed because the user address is blacklisted, and only in this case, you can return a successful response without any "order" key. Optionally, this can contain a "message" field explaining that the user was blacklisted and even having a reason why. When a user is detected blacklisted in this way it is added to the cache just as if it was received in the /blacklist endpoint described below.
You could also use our SDK for order signing. Please note, that you should pass takerAddress from the payload (whitelisted ParaSwap contract) as contractTaker, and userAddress (actual user address) as taker, as described in the example here.
Blacklist endpoint
Path: /blacklist
Method: GET
This endpoint is used to list any user addresses which are currently blacklisted. The payload is simply a JSON object with a key "blacklist" containing an array of blacklisted user addresses. This should not contain duplicate entries! Here is an example:
WebSocket connection (optional)
Market makers may optionally provide a WebSocket interface, in addition to the other endpoints. This is a one way channel from market maker to ParaSwap, intended to serve pricing updates more efficiently. Each message is a JSON object, and it can be used to send any information from other endpoints at any time, except for "order", however instead of sending the complete data each time (except for the very first message), it sends updates (creating or updating entries only, not deleting them). Here are specific details for each possible key:
"tokens"should contain details of any newly supported tokens or corrections to existing ones"pairs"should contain any newly added pairs or corrections to existing ones, it is not recommended to update"liquidityUSD"by WebSockets since it is not used from this source and it is anyhow constantly changing"prices"should contain any pairs which need their prices updated, refreshed in the cache (after not being updated for too long), or that should be removed from the cache (bids, asks or both)"blacklist"should contain only newly added user addresses"message"can be used at any time to cause information to be logged on ParaSwap servers
When the WebSocket is connected the first message should contain the complete responses to /tokens, /pairs, /prices and /blacklist endpoints in one JSON object (so that they don't need to be requested separately and potentially introduce synchronization issue). Once the connection is established the /blacklist endpoint will still be queried periodically in order to refresh the blacklisted status of all blacklisted users, which is only stored in cache temporarily.
Should the market maker wish to stop trading entirely, the websocket connection can simply be disconnected and refuse to reconnect until they wish to start trading again.
Augustus Swapper
Augustus is the exchange proxy that enables swaps to happen in ParaSwap.
Introduction
In this section, we'll describe the architecture of Augustus Swapper and its different internal mechanisms.
Simple-Path Swaps (Simple Swap)
Simple Swap is the simplest way for swapping tokens where there is no need to use any intermediary token.
Eg: Swapping 50 ETH --> MKR through one or more DEXs.
Multi-Path Swaps
A multi-path swap corresponds to using one or multiple intermediary tokens in a single swap in order to maximize the gain of the destination Token.
An example would be 100 ETH --> USDT, where the best route could be:
First, swapping 100 ETH to DAI,
Then, swapping the corresponding DAI to USDT.
Here each step would use one or multiple DEXs.
Mega-path Swaps
Mega Path is a generalized case for Multi Swap. Here, a swap can be broken down into multiple Multi-Swaps. It's generally useful with larger amounts.
Fee Structure
Partners integrating with ParaSwap using the ParaSwap API can control the fee structure of their integration, deciding whether to charge a swap fee or participate in surplus sharing.
For more information on how Partner Fees are implemented, please refer to the API Partners - Revenue Share Overview Section.
Architecture
The primary AugustusSwapper contract acts as a proxy contract. It passes on the calls to respective routers as per the function signature. Each function call has its own specific router which needs to be registered by the admin.
Routers
For each specific trade type, we have built a separate router. Currently, we have routers for:
SimpleSwap,
Multipath (with Megapath included),
direct swaps on Uniswap V2 (and forks)
direct swaps on 0x V2 and V4 (used to execute RFQ orders from ParaSwapPools)
Additional helper functions (used by simple swap for example)
Multipath routers delegate calls to adapters.
Adapters
Adapters are a collection of different exchange handlers. The number of exchange handlers is limited by the quantity of code allowed in one contract, so multiple adapters may be in use to cover all possible exchanges.
Exchange Routers
These are not part of the Augustus architecture per se but independent contracts. These are for use with simple swap where normally we'd use the official router contract of a DEX, but instead we may use a customized router (optimized to save gas). Currently this is only done for Uniswap V2 and similar forks.
Augustus v6.2
Augustus is the exchange middleware that enables on-chain swaps
AugustusSwapper
The contract router is responsible for making swaps.
Avalanche: 0x6a000f20005980200259b80c5102003040001068
Polygon zkEVM: 0x6a000f20005980200259b80c5102003040001068
Interfaces
GenericSwapExactAmountIn
GenericSwapExactAmountOut
Fee Vault
Avalanche: 0x00700052c0608f670705380a4900e0a8080010cc
Polygon zkEVM: 0x00700052c0608f670705380a4900e0a8080010cc
Augustus Registry
Use AugustusRegistry to verify AugustusSwapper addresses.
Avalanche: 0xfD1E5821F07F1aF812bB7F3102Bfd9fFb279513a
Polygon zkEVM: 0x5f34ade3efb2a3f9137ae14568495e8065beea46
Augustus v5
Allowance should be given to TokenTransferProxy contract and not to AugustusSwapper, FUNDS MAY BE LOST OTHERWISE!
AugustusSwapper
The contract router is responsible for making swaps.
Avalanche: 0xDEF171Fe48CF0115B1d80b88dc8eAB59176FEe57
Polygon zkEVM: 0xb83b554730d29ce4cb55bb42206c3e2c03e4a40a
TokenTransferProxy
The Spender contract is responsible for moving ERC20 tokens (and equivalents on side chains). To get the address, you can call getTokenTransferProxy() on Augustus.
Avalanche: 0x216b4b4ba9f3e719726886d34a177484278bfcae
Polygon zkEVM: 0xc8a21fcd5a100c3ecc037c97e2f9c53a8d3a02a1
Augustus Registry
Use AugustusRegistry to verify AugustusSwapper addresses.
Avalanche: 0xfD1E5821F07F1aF812bB7F3102Bfd9fFb279513a
Polygon zkEVM: 0x5f34ade3efb2a3f9137ae14568495e8065beea46
AugustusSwapper (implements IParaswap through fallback method)
ABI (merged AugustusSwapper and IParaswap ABIs)
IAugustusSwapper
(Generated from AugustusSwapper ABI using ABI2Solidity tool then edited to add FeeStructure)
IParaswap
Utils
Fee Claimer
Avalanche: 0xbFcd68FD74B4B458961495F3392Bf96f46A29E67
Polygon zkEVM: 0x593f39a4ba26a9c8ed2128ac95d109e8e403c485
Subgraphs
Query historical ParaSwap swap transactions on all supported chains through a GraphQL api via TheGraph.
Security
In this page you can explore all the security details and audits of ParaSwap
Augustus V6.2
In this page you can find all the security details and audit reports relevant to Augustus V6.2
Augustus V6.2 refines the fee-claiming process for partners while maintaining the security standards of V6.1.
Since V6.2 introduces only minor changes to its predecessor, the five audits and verification by Certora for V6.1 remain relevant. Nonetheless, Augustus V6.2 was audited by three additional security firms to ensure protection against vulnerabilities.
Audits
Augustus V6.1
In this page you can find all the security details and audit reports relevant to Augustus V6.1
Security Improvements
Augustus V6.1 incorporates additional security measures to improve security and reliability, including:
Full re-audit by leading security firms Augustus V6.1 has undergone a rigorous audit process conducted by five leading security firms: Certora, Hexens, Peckshield, Hacken, and Astrasec. These comprehensive audits confirmed that Augustus V6.1 meets the highest security standards. In addition, Augustus V6.1 received a formal verification by Certora, providing an additional security guarantee and making ParaSwap the first DEX aggregator to achieve this formal verification.
An additional mechanism for accelerated threat response Augustus V6.1 is designed to be fully pausable, allowing swift response to potential issues. This means that if any suspicious activity is detected, it can be immediately halted.
TimeLock mechanism for Admin Actions Except for Pausing, all Augustus V6.1 contract admin actions are subject to a TimeLock, which makes it resilient to immediate changes.
Audits
Augustus RFQ
In this page you can find all the security details and audit reports relevant to Augustus RFQ
Augustus V5
In this page you can find all the security details and audit reports relevant to Augustus V6