\n\n# SDK for the Velora API\n\nRefer to the documentation of the Velora API: https://developers.velora.xyz/\n\n## Features\n\n**Versatility**: works with [web3](https://www.npmjs.com/package/web3) or [ethers](https://www.npmjs.com/package/ethers) without a direct dependency — or with [viem](https://viem.sh/) (also used internally for its utils)\n\n**Canonical**: bring only the functions you actually need\n\n**Lightweight**: 10KB Gzipped for the minimal variant\n\n## What's changed in v10\n\nv10 is a breaking update over the v9.x line. The key consumer-facing changes:\n\n### Delta is now v2 — orders are built server-side\n\n- **You no longer build the order locally.** Pass the quoted `route` + `side` (from `getDeltaPrice` / `quote.delta`) to `buildDeltaOrder` / `submitDeltaOrder`; the server returns the typed data to sign. You no longer pass local amounts.\n- **One signer for every family.** `signDeltaOrder(builtOrder)` signs Standard, External, TWAP Sell and TWAP Buy orders. The old per-family signers **`signExternalDeltaOrder`** and **`signTWAPDeltaOrder`** are removed.\n- **`getDeltaPrice` returns a route-based `DeltaPrice`** (`route` + `alternatives`). The old `BridgePrice` type is gone — cross-chain is handled in-route via `destChainId`.\n- **`getBridgeInfo` → `getBridgeRoutes`** (now returns a flat `BridgeRoute[]`), plus a new `getBridgeProtocols`.\n- **New `getAgentsList`** (`sdk.delta.getAgentsList`).\n- **New read-only order types** surface through the read paths: `ProductiveOrder` (server-managed, no builder) and `FillableOrder` (a `partiallyFillable` Standard order — treat the same as `Order`).\n- All Delta endpoints now use the `/v2/delta/...` prefix.\n\n### Legacy limit orders removed — OTC orders remain\n\nThe deprecated legacy (non-Delta) limit-order methods are gone. The OTC order functionality that lived alongside them is kept, now exposed under its own `otcOrders` name:\n\n- `sdk.limitOrders.*` → `sdk.otcOrders.*`\n- the constructors are OTC-named: `constructBuildOTCOrder`, `constructSignOTCOrder`, `constructPostOTCOrder`, `constructCancelOTCOrder`, `constructGetOTCOrders`, `constructApproveTokenForOTCOrder`, `constructFillOTCOrder`, `constructSubmitOTCOrder`, etc.\n\n### NFT orders removed\n\nThe deprecated NFT-orders feature is gone: `sdk.nftOrders.*` and all `construct*NFTOrder*` exports no longer exist.\n\n## Installing Velora SDK\n\n```bash\npnpm add @velora-dex/sdk\n```\n\n## Using Velora SDK\n\nThere are multiple ways to use Velora 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\nimport { constructSimpleSDK } from '@velora-dex/sdk';\nimport axios from 'axios';\n\n// construct minimal SDK with fetcher only\nconst minSDK = constructSimpleSDK({ chainId: 1, axios });\n// or\nconst minSDK = constructSimpleSDK({\n chainId: 1,\n fetch: window.fetch,\n version: '5',\n});\n\nconst ETH = '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee';\nconst DAI = '0x6B175474E89094C44Da98b954EedeAC495271d0F';\n\nasync function swapExample() {\n // or any other signer/provider\n const signer: JsonRpcSigner = ethers.Wallet.fromMnemonic('__your_mnemonic__');\n const senderAddress = signer.address;\n\n const priceRoute = await minSDK.swap.getRate({\n srcToken: ETH,\n destToken: DAI,\n amount: srcAmount,\n userAddress: senderAddress,\n side: SwapSide.SELL,\n });\n\n const txParams = await minSDK.swap.buildTx({\n srcToken,\n destToken,\n srcAmount,\n destAmount,\n priceRoute,\n userAddress: senderAddress,\n partner: referrer,\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\nconst providerOptionsEtherV5 = {\n ethersProviderOrSigner: provider, // JsonRpcProvider\n EthersContract: ethers.Contract,\n account: senderAddress,\n};\n\n// with ethers@6\nconst providerOptionsEtherV6 = {\n ethersV6ProviderOrSigner: provider, // JsonRpcProvider\n EthersV6Contract: ethers.Contract,\n account: senderAddress,\n};\n\n// or with viem (from wagmi or standalone)\nconst providerOptionsViem = {\n viemClient, // made with createWalletClient()\n account: senderAddress,\n};\n\n// or with web3.js\nconst providerOptionsWeb3 = {\n web3, // new Web3(...) instance\n account: senderAddress,\n};\n\nconst sdk = constructSimpleSDK({ chainId: 1, axios }, providerOptionsEtherV5);\n\n// approve token through sdk\nconst txHash = await sdk.approveToken(amountInWei, DAI);\n\n// await tx somehow\nawait provider.waitForTransaction(txHash);\n```\n\n### Full SDK\n\n```typescript\nimport {\n constructFullSDK,\n constructAxiosFetcher,\n constructEthersContractCaller,\n} from '@velora-dex/sdk';\n\nconst signer = ethers.Wallet.fromMnemonic('__your_mnemonic__'); // or any other signer/provider\nconst account = '__signer_address__';\n\nconst contractCaller = constructEthersContractCaller(\n {\n ethersProviderOrSigner: signer,\n EthersContract: ethers.Contract,\n },\n account\n); // alternatively constructViemContractCaller or constructWeb3ContractCaller\nconst fetcher = constructAxiosFetcher(axios); // alternatively constructFetchFetcher\n\nconst sdk = constructFullSDK({\n chainId: 1,\n fetcher,\n contractCaller,\n});\n```\n\n### Partial SDK\n\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 {\n constructPartialSDK,\n constructFetchFetcher,\n constructGetRate,\n constructGetBalances,\n} from '@velora-dex/sdk';\n\nconst fetcher = constructFetchFetcher(window.fetch);\n\nconst sdk = constructPartialSDK(\n {\n chainId: 1,\n fetcher,\n },\n constructGetRate,\n constructGetBalances\n);\n\nconst priceRoute = await sdk.getRate(params);\nconst allowance = await sdk.getAllowance(userAddress, tokenAddress);\n```\n\n---\n\n### Basic usage\n\nThe easiest way to make a trade is to rely on the Quote method that communicates with the `/v2/quote` API endpoint. With `mode: 'all'` it returns Delta v2 pricing when possible, falling back to the current market price (use `mode: 'delta'` or `mode: 'market'` to request a single source).\n\n```typescript\nimport axios from 'axios';\nimport { ethers } from 'ethersV5';\nimport { constructSimpleSDK } from '@velora-dex/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 currently\n // partner: \"...\" // if available\n});\n\nif ('delta' in quote) {\n // quote.delta is the v2 DeltaPrice (route-based)\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 // order building is server-side: pass the quoted route + side, no local amounts\n const deltaAuction = await simpleSDK.delta.submitDeltaOrder({\n route: deltaPrice.route, // or any deltaPrice.alternatives[i]\n side: deltaPrice.side,\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 slippage: 50, // 50 bps = 0.5%\n });\n\n // stop polling on any terminal status — COMPLETED already accounts for any dest-chain bridge\n const SETTLED = ['COMPLETED', 'FAILED', 'CANCELLED', 'EXPIRED', 'REFUNDED'];\n function startStatusCheck(auctionId: string) {\n const intervalId = setInterval(async () => {\n const auction = await simpleSDK.delta.getDeltaOrderById(auctionId);\n if (SETTLED.includes(auction.status)) {\n clearInterval(intervalId);\n console.log(`Order settled: ${auction.status}`);\n }\n }, 3000);\n setTimeout(() => clearInterval(intervalId), 60000 * 5); // stop after 5 minutes\n }\n\n startStatusCheck(deltaAuction.id);\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**Velora Delta** is an intent-based protocol that enables a Velora 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\n(For **Crosschain Delta Orders** refer to a separate documentation page [DELTA.md](./docs/DELTA.md#crosschain-delta-orders) )\n\nIn v2 the Order is **built by the server** from the quoted route — you sign the returned typed data and post it. After getting **deltaPrice**, there are a few steps to sign the Order and wait for its execution.\n\n### 1. Get deltaPrice\n\n```ts\nconst amount = '1000000000000'; // wei\nconst Token1 = '0x1234...';\nconst Token2 = '0xabcde...';\n\n// ... from the quote endpoint (mode: 'delta' or 'all')\nconst quote = await simpleSDK.quote.getQuote({\n srcToken: Token1,\n destToken: Token2,\n amount,\n userAddress: account,\n srcDecimals: 18,\n destDecimals: 18,\n mode: 'delta',\n side: 'SELL',\n // partner: \"...\" // if available\n});\nconst deltaPrice = quote.delta;\n\n// ... or straight from the Delta price endpoint\nconst deltaPriceDirect = await simpleSDK.delta.getDeltaPrice({\n srcToken: Token1,\n destToken: Token2,\n amount,\n srcDecimals: 18,\n destDecimals: 18,\n userAddress: account,\n // destChainId: 42161, // for cross-chain — bridge details land in deltaPrice.route.bridge\n});\n```\n\n### 2. Approve srcToken for DeltaContract\n\n```ts\nconst approveTxHash = await simpleSDK.delta.approveTokenForDelta(\n amount,\n Token1\n);\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 [Velora documentation](https://developers.velora.xyz/api/velora-api/velora-delta-api/build-a-delta-order-to-sign#supported-permits)\n\n### 3. Build, sign and post a Delta Order\n\n```ts\n// build is server-side — pass the quoted route + side and your slippage\nconst built = await simpleSDK.delta.buildDeltaOrder({\n route: deltaPrice.route, // or any deltaPrice.alternatives[i]\n side: deltaPrice.side,\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 slippage: 50, // 50 bps = 0.5%\n // partner, partnerFeeBps — forwarded to the server\n});\n\n// one signer for every order family (Order / ExternalOrder / TWAPOrder / TWAPBuyOrder)\nconst signature = await simpleSDK.delta.signDeltaOrder(built);\n\nconst deltaAuction = await simpleSDK.delta.postDeltaOrder({\n order: built.toSign.value,\n signature,\n // partner: \"...\",\n // partiallyFillable: true, // allow the Order to be partially filled as opposed to fill-or-kill\n});\n```\n\n#### 3.a.\n\nAs an option the `buildDeltaOrder + signDeltaOrder + postDeltaOrder` can be combined into one SDK call with the following code\n\n```ts\nconst deltaAuction = await simpleSDK.delta.submitDeltaOrder({\n route: deltaPrice.route,\n side: deltaPrice.side,\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 // partiallyFillable: true, // allow the Order to be partially filled as opposed to fill-or-kill\n slippage: 50,\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 is collected as a partner fee when `partner` (and optionally `partnerFeeBps`) is provided to `buildDeltaOrder` / `submitDeltaOrder`. In v2 these are forwarded to the server, which encodes them into `Order.partnerAndFee`. You can inspect the default partner-fee parameters with `getPartnerFee`:\n\n```ts\nconst partnerFeeResponse = await simpleSDK.delta.getPartnerFee({ partner });\n```\n\n### 4. Wait for Delta Order execution\n\n```ts\n// stop polling on any terminal status — COMPLETED already accounts for any dest-chain bridge\nconst SETTLED = ['COMPLETED', 'FAILED', 'CANCELLED', 'EXPIRED', 'REFUNDED'];\nfunction startStatusCheck(auctionId: string) {\n const intervalId = setInterval(async () => {\n const auction = await simpleSDK.delta.getDeltaOrderById(auctionId);\n if (SETTLED.includes(auction.status)) {\n clearInterval(intervalId); // stop interval once the order is settled\n console.log(`Order settled: ${auction.status}`);\n }\n }, 3000);\n // stop polling after 5 minutes\n setTimeout(() => clearInterval(intervalId), 60000 * 5);\n}\n\nstartStatusCheck(deltaAuction.id);\n```\n\n#### A more detailed example of Delta Order usage can be found in [examples/delta](./src/examples/delta.ts)\n\nFor more Delta protocol usage, and **Crosschain Delta Orders**, refer to [DELTA.md](./docs/DELTA.md)\n\nFor **External Delta Orders** (orders that delegate token handling to an external handler contract, enabling complex DeFi strategies like Aave collateral/debt swaps), refer to [EXTERNAL_ORDERS.md](./docs/EXTERNAL_ORDERS.md)\n\n---\n\n### Advanced Delta usage\n\n#### TWAP order\n\nA TWAP sell splits `totalSrcAmount` into `numSlices` equal slices executed `interval` seconds apart. Price is quoted for a single slice — the server multiplies amounts internally.\n\n```ts\nconst perSliceAmount = (BigInt(totalSrcAmount) / BigInt(numSlices)).toString();\n\nconst slicePrice = await simpleSDK.delta.getDeltaPrice({\n srcToken: Token1,\n destToken: Token2,\n amount: perSliceAmount,\n srcDecimals: 18,\n destDecimals: 18,\n userAddress: account,\n});\n\nawait simpleSDK.delta.approveTokenForDelta(totalSrcAmount, Token1);\n\nconst twapAuction = await simpleSDK.delta.submitTWAPDeltaOrder({\n onChainOrderType: 'TWAPOrder', // or 'TWAPBuyOrder'\n route: slicePrice.route,\n owner: account,\n totalSrcAmount,\n numSlices,\n interval: 300, // seconds (min 60)\n slippage: 50,\n});\n```\n\n#### Partial SDK\n\nFor bundle-savvy code, pull only the Delta constructors you need — they tree-shake cleanly.\n\n```ts\nimport {\n constructPartialSDK,\n constructFetchFetcher,\n constructGetDeltaPrice,\n constructGetDeltaOrders,\n constructGetBridgeRoutes,\n} from '@velora-dex/sdk';\n\nconst sdk = constructPartialSDK(\n { chainId: 1, fetcher: constructFetchFetcher(fetch) },\n constructGetDeltaPrice,\n constructGetDeltaOrders,\n constructGetBridgeRoutes\n);\n\nconst price = await sdk.getDeltaPrice({\n /* ... */\n});\nconst orders = await sdk.getDeltaOrders({\n userAddress: account,\n page: 1,\n limit: 50,\n});\n```\n\nA complete example (standard, external handler, TWAP, and order listing) is in [examples/delta](./src/examples/delta.ts).\n\n#### Productive Orders (read-only)\n\nAlongside the four buildable families (`Order`, `ExternalOrder`, `TWAPOrder`, `TWAPBuyOrder`), the SDK surfaces a fifth `onChainOrderType` — **`ProductiveOrder`** — through the read endpoints (`sdk.delta.getDeltaOrderById`, `sdk.delta.getDeltaOrders`, etc.). Productive orders are produced and managed entirely by the server: there are deliberately **no `buildProductiveOrder`, `signProductiveOrder`, or `submitProductiveOrder` helpers**. The shape is wired through `OnChainOrderType` and `OnChainOrderMap` so that consumers iterating over an order list can type-narrow on `onChainOrderType === 'ProductiveOrder'` and read the order safely — productive orders carry no `OrderKind`, so the side is always `SELL`.\n\n`OnChainOrderType` additionally includes **`'FillableOrder'`**, which maps to the same shape as a Standard `'Order'` (`DeltaAuctionOrder`). It is not a separate buildable family — it's the `onChainOrderType` the server reports for a `partiallyFillable` Standard order, so treat it the same as `'Order'` when narrowing.\n\n#### Order helpers\n\n`OrderHelpers` exposes `{ checks, getters }` for auctions returned by `sdk.delta.*` read/post methods (`status: DeltaOrderStatus`, `input`/`output`, flat `transactions`, explicit `side`):\n\n```ts\nimport { OrderHelpers } from '@velora-dex/sdk';\n\nconst { checks, getters } = OrderHelpers;\n\nif (checks.isProductiveAuction(auction)) {\n // read-only, no SDK builder\n} else if (\n checks.isFillableAuction(auction) ||\n checks.isDeltaAuction(auction)\n) {\n // treat FillableOrder the same as a standard Order\n}\n\nif (checks.isCompletedAuction(auction)) {\n const { expected, executed } = getters.getAuctionAmounts(auction);\n // `executed` — matches the API convention\n}\n\nconst unified = getters.getUnifiedDeltaOrderData(auction);\n// { srcChainId, destChainId, srcToken, destToken, swapSide, filledPercent, amounts, ... }\n```\n\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 /v2/quote\n\n```ts\nconst amount = '1000000000000'; // wei\nconst Token1 = '0x1234...';\nconst Token2 = '0xabcde...';\n\nconst quote = await simpleSDK.quote.getQuote({\n srcToken: Token1,\n destToken: Token2,\n amount,\n userAddress: account,\n srcDecimals: 18,\n destDecimals: 18,\n mode: 'market',\n side: 'SELL', // or 'BUY'\n // partner: \"...\" // if available\n});\n\nconst priceRoute = quote.market;\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 [Velora documentation](https://developers.velora.xyz/api/velora-api/velora-market-api/build-parameters-for-transaction)\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 [Velora documentation](https://developers.velora.xyz/api/velora-api/velora-market-api/build-parameters-for-transaction)\n\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 `pnpm 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","readmeFilename":"README.md"}
![](\"https://cdn.paraswap.io/brand/velora_banner_dark.svg\")
\n