\n\n# SDK for the ParaSwap API\n\nRefer to the documentation of the ParaSwap API: https://developers.paraswap.network\n\n## Features\n**Versatility**: works with [web3](https://www.npmjs.com/package/web3), [ethers](https://www.npmjs.com/package/ethers) or [viem](https://viem.sh/) without direct dependency\n\n**Canonical**: bring only the functions you actually need\n\n**Lightweight**: 10KB Gzipped for the minimal variant\n\n## Installing ParaSwap SDK\n\n```bash\nyarn add @paraswap/sdk\n```\n\n## Using ParaSwap SDK\n\nThere 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.\n\nYou can see some examples in [/src/examples](src/examples) directory.\n\n### Simple SDK\n\nCan be created by providing `chainId` and either `axios` or `window.fetch` (or alternative `fetch` implementation), and an optional `version` (`'5'` or `'6.2'`) parameter that corresponds to the API version SDK will be making requests to. The resulting SDK will be able to use all methods that query the API.\n\n```ts\n import { constructSimpleSDK } from '@paraswap/sdk';\n import axios from 'axios';\n\n // construct minimal SDK with fetcher only\n const paraSwapMin = constructSimpleSDK({chainId: 1, axios});\n // or\n const paraSwapMin = constructSimpleSDK({chainId: 1, fetch: window.fetch, version: '5'});\n\n const ETH = '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee';\n const DAI = '0x6B175474E89094C44Da98b954EedeAC495271d0F';\n\n async function swapExample() {\n // or any other signer/provider \n const signer: JsonRpcSigner = ethers.Wallet.fromMnmemonic('__your_mnemonic__');\n const senderAddress = signer.address;\n\n const priceRoute = await paraSwapMin.swap.getRate({\n srcToken: ETH,\n destToken: DAI,\n amount: srcAmount,\n userAddress: senderAddress,\n side: SwapSide.SELL,\n });\n\n const txParams = await paraSwapMin.swap.buildTx(\n {\n srcToken,\n destToken,\n srcAmount,\n destAmount,\n priceRoute,\n userAddress: senderAddress,\n partner: referrer,\n } \n );\n\n const transaction = {\n ...txParams,\n gasPrice: '0x' + new BigNumber(txParams.gasPrice).toString(16),\n gasLimit: '0x' + new BigNumber(5000000).toString(16),\n value: '0x' + new BigNumber(txParams.value).toString(16),\n };\n\n const txr = await signer.sendTransaction(transaction);\n }\n```\n\nIf optional `providerOptions` is provided as the second parameter, then the resulting SDK will also be able to approve Tokens for swap, sign Orders, etc.\n\n```ts\n // with ethers@5\n const providerOptionsEtherV5 = {\n ethersProviderOrSigner: provider, // JsonRpcProvider\n EthersContract: ethers.Contract,\n account: senderAddress,\n };\n\n // with ethers@6\n const providerOptionsEtherV6 = {\n ethersV6ProviderOrSigner: provider, // JsonRpcProvider\n EthersV6Contract: ethers.Contract,\n account: senderAddress,\n };\n\n // or with viem (from wagmi or standalone)\n const providerOptionsViem = {\n viemClient, // made with createWalletClient()\n account: senderAddress,\n };\n\n // or with web3.js\n const providerOptionsWeb3 = {\n web3, // new Web3(...) instance\n account: senderAddress,\n };\n\n const paraSwap = constructSimpleSDK({chainId: 1, axios}, providerOptionsEtherV5);\n\n // approve token through sdk\n const txHash = await paraSwap.approveToken(amountInWei, DAI);\n\n // await tx somehow\n await provider.waitForTransaction(txHash);\n```\n\n### Full SDK \n```typescript\nimport { constructFullSDK, constructAxiosFetcher, constructEthersContractCaller } from '@paraswap/sdk';\n\nconst signer = ethers.Wallet.fromMnmemonic('__your_mnemonic__'); // or any other signer/provider \nconst account = '__signer_address__';\n\nconst contractCaller = constructEthersContractCaller({\n ethersProviderOrSigner: signer,\n EthersContract: ethers.Contract,\n}, account); // alternatively constructViemContractCaller or constructWeb3ContractCaller\nconst fetcher = constructAxiosFetcher(axios); // alternatively constructFetchFetcher\n\nconst paraswap = constructFullSDK({\n chainId: 1,\n fetcher,\n contractCaller,\n});\n```\n\n### Partial SDK\nFor bundle-size savvy developers, you can construct a lightweight version of the SDK and bring only the functions you need.\n\ne.g. for only getting rates and allowances:\n\n```typescript\nimport { constructPartialSDK, constructFetchFetcher, constructGetRate, constructGetBalances } from '@paraswap/sdk';\n\nconst fetcher = constructFetchFetcher(window.fetch);\n\nconst minParaSwap = constructPartialSDK({\n chainId: 1,\n fetcher,\n}, constructGetRate, constructGetBalances);\n\nconst priceRoute = await minParaSwap.getRate(params);\nconst allowance = await minParaSwap.getAllowance(userAddress, tokenAddress);\n```\n--------------\n\n### Basic usage\n\nThe easiest way to make a trade is to rely on Quote method that communicates with [/quote API endpoint](https://developers.paraswap.network/api/paraswap-delta/retrieve-delta-price-with-fallback-to-market-quote)\n\n```typescript\nimport axios from 'axios';\nimport { ethers } from 'ethersV5';\nimport { constructSimpleSDK } from '@paraswap/sdk';\n\nconst ethersProvider = new ethers.providers.Web3Provider(window.ethereum);\n\nconst accounts = await ethersProvider.listAccounts();\nconst account = accounts[0]!;\nconst signer = ethersProvider.getSigner(account);\n\nconst simpleSDK = constructSimpleSDK(\n { chainId: 1, axios },\n {\n ethersProviderOrSigner: signer,\n EthersContract: ethers.Contract,\n account,\n }\n);\n\nconst amount = '1000000000000'; // wei\nconst Token1 = '0x1234...'\nconst Token2 = '0xabcde...'\n\nconst quote = await simpleSDK.quote.getQuote({\n srcToken: Token1, // Native token (ETH) is only supported in mode: 'market'\n destToken: Token2,\n amount,\n userAddress: account,\n srcDecimals: 18,\n destDecimals: 18,\n mode: 'all', // Delta quote if possible, with fallback to Market price\n side: 'SELL', // Delta mode only supports side: SELL currenly\n // partner: \"...\" // if available\n});\n\nif ('delta' in quote) {\n const deltaPrice = quote.delta;\n\n const DeltaContract = await simpleSDK.delta.getDeltaContract();\n\n // or sign a Permit1 or Permit2 TransferFrom for DeltaContract\n await simpleSDK.delta.approveTokenForDelta(amount, Token1);\n\n const slippagePercent = 0.5;\n const destAmountAfterSlippage = BigInt(\n // get rid of exponential notation\n\n +(+deltaPrice.destAmount * (1 - slippagePercent / 100)).toFixed(0)\n // get rid of decimals\n ).toString(10);\n\n const deltaAuction = await simpleSDK.delta.submitDeltaOrder({\n deltaPrice,\n owner: account,\n // beneficiary: anotherAccount, // if need to send the output destToken to another account\n // permit: \"0x1234...\", // if signed a Permit1 or Permit2 TransferFrom for DeltaContract\n srcToken: Token1,\n destToken: Token2,\n srcAmount: amount,\n destAmount: destAmountAfterSlippage, // minimum acceptable destAmount\n });\n\n // poll if necessary\n const auction = await simpleSDK.delta.getDeltaOrderById(deltaAuction.id);\n if (auction?.status === 'EXECUTED') {\n console.log('Auction was executed');\n }\n} else {\n console.log(\n `Delta Quote failed: ${quote.fallbackReason.errorType} - ${quote.fallbackReason.details}`\n );\n const priceRoute = quote.market;\n\n const TokenTransferProxy = await simpleSDK.swap.getSpender();\n\n // or sign a Permit1 or Permit2 TransferFrom for TokenTransferProxy\n const approveTxHash = simpleSDK.swap.approveToken(amount, Token1);\n\n const txParams = await simpleSDK.swap.buildTx({\n srcToken: Token1,\n destToken: Token2,\n srcAmount: amount,\n slippage: 250, // 2.5%\n priceRoute,\n userAddress: account,\n // partner: '...' // if available\n });\n\n const swapTx = await signer.sendTransaction(txParams);\n}\n```\n\n### Delta Order handling\n\n#### A more detailed overview of the Trade Flow, Delta Order variant.\n\n**ParaSwap Delta** is an intent-based protocol that enables a ParaSwap user to make gasless swaps where multiple agents compete to execute the trade at the best price possible.\nThis way the user doesn't need to make a transaction themselve but only to sign a Delta Order.\n\nAfter getting **deltaPrice** from **/quote** endpoint, there are additional steps to sign the Order and wait for its execution.\n\n### 1. Get deltaPrice from /quote\n\n```ts\nconst amount = '1000000000000'; // wei\nconst Token1 = '0x1234...'\nconst Token2 = '0xabcde...'\n\nconst quote = await simpleSDK.quote.getQuote({\n srcToken: Token1, // Native token (ETH) is only supported in mode: 'market'\n destToken: Token2,\n amount,\n userAddress: account,\n srcDecimals: 18,\n destDecimals: 18,\n mode: 'delta' // or mode: 'all'\n // partner: \"...\" // if available\n})\n\n// if used mode: 'all'\nif ('delta' in quote) {\n const deltaPrice = quote.delta;\n}\n\n// if used mode: 'delta'\nconst deltaPrice = quote.delta;\n```\n\n\n### 2. Approve srcToken for DeltaContract\n\n```ts\nconst approveTxHash = await simpleSDK.delta.approveTokenForDelta(amount, Token1);\n```\n\nAlternatively sign Permit (DAI or Permit1) or Permit2 TransferFrom with DeltaContract as the verifyingContract\n\n```ts\nconst DeltaContract = await simpleSDK.delta.getDeltaContract();\n\n// values depend on the Permit type and the srcToken\nconst signature = await signer._signTypedData(domain, types, message);\n```\n\nSee more on accepted Permit variants in [ParaSwap documentation](https://developers.paraswap.network/api/paraswap-delta/build-and-sign-a-delta-order#supported-permits)\n\n\n### 3. Sign and submit a Delta Order\n\n```ts\n// calculate acceptable destAmount\nconst slippagePercent = 0.5;\n const destAmountAfterSlippage = (\n +deltaPrice.destAmount *\n (1 - slippagePercent / 100)\n ).toString(10);\n\nconst signableOrderData = await simpleSDK.delta.buildDeltaOrder({\n deltaPrice,\n owner: account,\n // beneficiary: anotherAccount, // if need to send the output destToken to another account\n // permit: \"0x1234...\", // if signed a Permit1 or Permit2 TransferFrom for DeltaContract\n srcToken: Token1,\n destToken: Token2,\n srcAmount: amount,\n destAmount: destAmountAfterSlippage, // minimum acceptable destAmount\n // partner: \"...\" // if available\n});\n\nconst signature = await simpleSDK.delta.signDeltaOrder(signableOrderData);\n\nconst deltaAuction = await simpleSDK.delta.postDeltaOrder({\n // partner: \"...\" // if available\n // partiallyFillabel: true, // allow the Order to be partially filled as opposed to fill-or-kill\n order: signableOrderData.data,\n signature,\n});\n```\n\n#### 3.a.\n\nAs an option the `buildDeltaOrder + signDeltaOrder + signDeltaOrder` can be combined into one SDK call with the following code\n\n```ts\nconst deltaAuction = await simpleSDK.delta.submitDeltaOrder({\n deltaPrice,\n owner: account,\n // beneficiary: anotherAccount, // if need to send output destToken to another account\n // permit: \"0x1234...\", // if signed a Permit1 or Permit2 TransferFrom for DeltaContract\n // partiallyFillabel: true, // allow the Order to be partially filled as opposed to fill-or-kill\n srcToken: Token1,\n destToken: Token2,\n srcAmount: amount,\n destAmount: destAmountAfterSlippage, // minimum acceptable destAmount\n});\n```\n\nThis allows to simplify the flow at the expense of control over the Order signing.\n\n#### 3.b adding partner fee\n\nA portion of destToken will be collected as a partner fee if `partner` parameter is provided to `buildDeltaOrder` (and `submitDeltaOrder`). The `partnerFee` itself is `deltaPrice.partnerFee`\n\nTo examine the default partnerFee parameters (`{partnerAddress: Address, partnerFee: number, takeSurplus: boolean}`), you can call `getPartnerFee` method. These parameters are then encoded in Order.partnerAndFee field.\n\n```ts\nconst partnerFeeResponse = await simpleSDK.delta.getPartnerFee({ partner });\n```\n\nAlternatively, you can supply your own partnerFee parameters that will be encoded in Order.partnerAndFee field\n\n```ts\nconst signableOrderData = await simpleSDK.delta.buildDeltaOrder({\n deltaPrice,\n owner: account,\n // beneficiary: anotherAccount, // if need to send the output destToken to another account\n // permit: \"0x1234...\", // if signed a Permit1 or Permit2 TransferFrom for DeltaContract\n // partiallyFillabel: true, // allow the Order to be partially filled as opposed to fill-or-kill\n srcToken: Token1,\n destToken: Token2,\n srcAmount: amount,\n destAmount: destAmountAfterSlippage, // minimum acceptable destAmount\n partnerAddress: '0x1234...',\n partnerFee: 0.12,\n takeSurplus: true,\n});\n```\n\n### 4. Wait for Delta Order execution\n\n```ts\n// poll if necessary\nconst auction = await simpleSDK.delta.getDeltaOrderById(deltaAuction.id);\nif (auction?.status === 'EXECUTED') {\n console.log('Auction was executed');\n}\n```\n\n#### A more detailed example of Delta Order usage can be found in [examples/delta](./src/examples/delta.ts)\n\n#### For more Delta protocol usage refer to [DELTA.md](./docs/DELTA.md)\n------------\n\n### Market Swap handling\n\n#### A more detailed overview of the Trade Flow, Market variant.\n\nUnlike the Delta Order, a Market swap requires the user themselves to submit a Swap transaction\n\n### 1. Get Market priceRoute from /quote\n\n```ts\nconst amount = '1000000000000'; // wei\nconst Token1 = '0x1234...'\nconst Token2 = '0xabcde...'\n\nconst quote = await simpleSDK.quote.getQuote({\n srcToken: Token1, // Native token (ETH) is only supported in mode: 'market'\n destToken: Token2,\n amount,\n userAddress: account,\n srcDecimals: 18,\n destDecimals: 18,\n mode: 'market'\n // partner: \"...\" // if available\n})\n\n// if used mode: 'all'\nif ('market' in quote) {\n const priceRoute = quote.market;\n}\n\n// if used mode: 'market'\nconst priceRoute = quote.market;\n```\n\n\n### 2. Approve srcToken for TokenTransferProxy\n\n```ts\nconst approveTxHash = simpleSDK.swap.approveToken(amount, DAI_TOKEN);\n```\n\nAlternatively sign Permit (DAI or Permit1) or Permit2 TransferFrom with TokenTransferProxy as the verifyingContract\n\n```ts\nconst TokenTransferProxy = await simpleSDK.swap.getSpender();\n\n// values depend on the Permit type and the srcToken\nconst signature = await signer._signTypedData(domain, types, message);\n```\n\nSee more on accepted Permit variants in [ParaSwap documentation](https://developers.paraswap.network/api/build-parameters-for-transaction)\n\n\n### 3. Send Swap transaction\n\n```ts\nconst txParams = await simpleSDK.swap.buildTx({\n srcToken: Token1,\n destToken: Token2,\n srcAmount: amount,\n slippage: 250, // 2.5%\n // can pass `destAmount` (adjusted for slippage) instead of `slippage`\n priceRoute,\n userAddress: account,\n // partner: '...' // if available\n // receiver: '0x123ae...' // if need to send the output destToken to another account\n});\n\nconst swapTxHash = await signer.sendTransaction(txParams);\n```\n\n#### See more details on `buildTx` parameters in [ParaSwap documentation](https://developers.paraswap.network/api/build-parameters-for-transaction)\n\n------------------------\n\n### Legacy\nThe `ParaSwap` class is exposed for backwards compatibility with previous versions of the SDK.\n\n```typescript\nimport { ParaSwap } from '@paraswap/sdk';\nimport axios from 'axios';\nimport Web3 from 'web3';\n\nconst web3Provider = new Web3(window.ethereum);\nconst account = '__user_address__';\n\nconst paraswap = new ParaSwap({chainId: 1, web3Provider, account, axios});\n\n```\n\n\nOr you can use `ethers` in place of `web3`\n\n```typescript\nimport { ParaSwap } from '@paraswap/sdk';\nimport { ethers } from \"ethers\";\n\nconst ethersProvider = new ethers.providers.Web3Provider(window.ethereum)\nconst account = '__user_address__';\n\nconst paraswap = new ParaSwap({\n chainId: 1,\n account,\n ethersDeps: {\n ethersProviderOrSigner: ethersProvider;\n EthersContract: ethers.Contract;\n },\n fetch: window.fetch,\n });\n\n```\n\nBy analogy to ```constructPartialSDK```, you can leverage a lightweight version of the sdk for fetching only.\n\n```typescript\nimport { ParaSwap } from '@paraswap/sdk';\n\nconst paraswap = new ParaSwap({chainId: 1, fetch: window.fetch});\n\n```\n\nRefer to [this README for depecreated documentation](https://github.com/paraswap/paraswap-sdk/blob/c4c70c674fb2be4ec528064649d992d4b38c654b/README.md) for functions usage.\n\n\nRefer to [SDK API documentation](docs/md/modules.md) for detailed documentation on the methods provided in this SDK.\n\n## Tests\n\nTo run `yarn test` it is necessary to provide `PROVIDER_URL=` environment variable.\nIf it is necessary to run tests against a different API endpoint, provide `API_URL=url_to_API` environment variable.\n\n","readmeFilename":"README.md"}
![](\"https://cdn.paraswap.io/brand/paraswap.png\")
\n \n![](\"./docs/passed_tests.png\")
","readmeFilename":"README.md"}