Delta swaps with the SDK

A swap in Velora settles through one of two execution paths: Delta (this page) or Market. Delta wraps the Delta API: gasless, MEV-protected swaps where the user signs an off-chain order, and a network of solvers (Portikus) competes to provide the best fill. The user pays no gas; settlement happens through the Delta flow. Delta is also the engine behind two other products in the SDK: Limit orders (a Delta order with a target price) and TWAP (a Delta order split into scheduled slices). This page covers the market Delta order, and those pages build on the same flow.

Delta orders are server-built: you don’t compose EIP-712 typed data locally. getDeltaPrice returns a recommended route plus alternatives, buildDeltaOrder returns ready-to-sign typed data, and order history is paginated.

When to use this

The user shouldn’t pay gas, or doesn’t have gas on the source chain.
You want MEV protection. Orders fill via private auction, not the public mempool.
You want one signed intent to settle crosschain. See Crosschain Delta.

For swaps where the user submits the transaction themselves, see Market.

How it’s exposed

Delta lives at two layers in the SDK:

sdk.delta.* is the pre-bound bag attached to constructSimpleSDK / constructFullSDK: sdk.delta.getDeltaPrice, sdk.delta.submitDeltaOrder, sdk.delta.signDeltaOrder, etc. This is what most consumers use.
The bare construct* functions and types are exported at the package root for advanced wiring (e.g., constructPartialSDK) and type annotations: constructBuildDeltaOrder, constructSubmitDeltaOrder, constructAllDeltaOrdersHandlers, and types like DeltaPrice, DeltaRoute, BuiltDeltaOrder, DeltaAuction, BridgeRoute.

The flow

Get a Delta price

Call sdk.delta.getDeltaPrice with source/destination tokens, amount, decimals, and partner. The response includes the recommended route plus alternatives and the contract spender to approve.

Approve the source token (or sign a Permit)

Call sdk.delta.approveTokenForDelta(amount, srcToken), or sign a Permit / Permit2 message with the Delta contract (returned in price.spender) as the verifying contract. Native tokens skip this step.

Build, sign, and post the order

Either call the one-shot orchestrator sdk.delta.submitDeltaOrder, or run the three steps yourself (buildDeltaOrder → signDeltaOrder → postDeltaOrder) when you need control over signing.

Poll for execution

Use sdk.delta.getDeltaOrderById (or getDeltaOrderByHash) on a timer until status is COMPLETED.

One-call submit

submitDeltaOrder runs build → sign → post in a single call. This is the recommended path for most flows.

const price = await sdk.delta.getDeltaPrice({
  srcToken: USDC,
  destToken: ETH,
  amount: "10000000000", // 10,000 USDC
  srcDecimals: 6,
  destDecimals: 18,
  userAddress: account,
  partner: "my-app-name",
});

await sdk.delta.approveTokenForDelta("10000000000", USDC);

const auction = await sdk.delta.submitDeltaOrder({
  route: price.route,
  side: price.side,
  owner: account,
  partner: "my-app-name",
  slippage: 50, // 0.5% in bps
  deadline: Math.floor(Date.now() / 1000) + 60 * 60, // required, unix seconds
  // beneficiary: anotherAccount, // optional, default = owner
  // permit: "0x...",              // optional, if you signed a Permit instead of approving
  // partiallyFillable: true,      // optional, default = fill-or-kill
});

console.log("auction id:", auction.id);

Split flow

Use the three-step flow when you need to customize signing: for example, a hardware wallet that prompts on each call, a multisig that signs asynchronously, or batched signing across orders.

const built = await sdk.delta.buildDeltaOrder({
  route: price.route,
  side: price.side,
  owner: account,
  partner: "my-app-name",
  slippage: 50,
  deadline: Math.floor(Date.now() / 1000) + 60 * 60, // required, unix seconds
});

const signature = await sdk.delta.signDeltaOrder(built);

const auction = await sdk.delta.postDeltaOrder({
  order: built.toSign.value,
  signature,
  partner: "my-app-name",
});

buildDeltaOrder returns { toSign, orderHash }. The server has already composed the EIP-712 typed data, and signDeltaOrder wraps your contract caller’s signTypedData to produce the signature. It’s generic across order families, so the market, limit, and TWAP flows all sign through the same call. If your signer is a smart contract (e.g., a multisig or 4337 wallet) that can’t produce an off-chain EIP-712 signature, use sdk.delta.preSignDeltaOrder to register the order hash on-chain instead.

Poll for execution

import { OrderHelpers } from "@velora-dex/sdk";

const intervalId = setInterval(async () => {
  const updated = await sdk.delta.getDeltaOrderById(auction.id);
  if (OrderHelpers.checks.isExecutedAuction(updated)) {
    clearInterval(intervalId);
    console.log("filled");
  }
}, 3000);

// stop polling after 5 minutes
setTimeout(() => clearInterval(intervalId), 60_000 * 5);

OrderHelpers.checks.isExecutedAuction returns true only when same-chain orders show status === "COMPLETED", and crosschain orders also have their destination-chain leg filled.

List orders

getDeltaOrders returns a paginated list filtered by user, chain, status, and order type:

const { data, page, limit, total } = await sdk.delta.getDeltaOrders({
  userAddress: account,
  page: 1,
  limit: 100,
  // status: ["ACTIVE", "COMPLETED"],   // optional filter
  // chainId: [1, 10],                   // omit for all chains
  // type: "MARKET",                     // 'MARKET' | 'LIMIT'
});

Each entry is a DeltaAuction<T>, generic over onChainOrderType. It may report 'FillableOrder' for a partiallyFillable Standard order; treat it exactly like 'Order' (identical shape). Use type: "LIMIT" to filter for limit orders.

Partner fee

Pass partner (and optionally partnerAddress, partnerFeeBps, partnerTakesSurplus) to getDeltaPrice, submitDeltaOrder, buildDeltaOrder, and postDeltaOrder. The SDK sends these directly to the server, which resolves and validates the fee in one call, so there’s no local getPartnerFee round-trip.

const auction = await sdk.delta.submitDeltaOrder({
  route: price.route,
  side: price.side,
  owner: account,
  partner: "my-app-name",
  partnerAddress: "0xYourFeeCollector",
  partnerFeeBps: 25, // 0.25%
  slippage: 50,
  deadline: Math.floor(Date.now() / 1000) + 60 * 60, // required, unix seconds
});

See Monetize for the full field reference and fee-vs-surplus tradeoffs.

Cancel an order

await sdk.delta.cancelDeltaOrders({ orderIds: [auction.id] });

This signs and posts a cancellation request. It only succeeds for orders that are still open in the auction.

Crosschain Delta

Pass destChainId to getDeltaPrice to settle on a different chain than the source. The returned route is bridge-aware; submitting the order is identical to same-chain. See Crosschain Delta for the full design and getBridgeRoutes for advanced route inspection.

Other Delta products

Limit orders and TWAP are Delta orders too. They reuse this exact build → sign → post → poll flow with a couple of extra fields:

Limit orders: a Delta order with a target-price constraint and type: "LIMIT".
TWAP is a Delta order split into time-weighted slices, built with buildTWAPDeltaOrder / submitTWAPDeltaOrder.

Migrate from V1 to V2

Only relevant if you’re upgrading an existing integration from an older SDK version. New integrations can ignore this section; everything above already uses the current API.

Delta V2 keeps the same sdk.delta.* namespace and method names as V1. What changes is that orders are now server-built (you no longer compose EIP-712 typed data locally), pricing is route-based, and order history is paginated. The on-chain contracts, approval flow, and signature format are unchanged.

Pricing

getDeltaPrice takes the same params, but the response shape changes:

  const price = await sdk.delta.getDeltaPrice({
    srcToken: USDC,
    destToken: ETH,
    amount,
    srcDecimals: 6,
    destDecimals: 18,
    userAddress: account,
    partner: "my-app-name",
  });

V1 returned a flat DeltaPrice { srcAmount, destAmount, partner, partnerFee, destToken, ... }. V2 returns DeltaPrice { route, alternatives, side, partner: { name, feePercent }, spender }. Swap details now live under price.route, and alternatives lets users pick a different bridge.

One-call submit

  const auction = await sdk.delta.submitDeltaOrder({
-   deltaPrice,
-   owner: account,
-   srcToken: USDC,
-   destToken: ETH,
-   srcAmount: amount,
-   destAmount,         // you compute the slippage-adjusted destAmount
-   partner: "my-app-name",
+   route: price.route, // route carries src/dest tokens and amounts
+   side: price.side,
+   owner: account,
+   slippage: 50,       // bps; the SDK applies slippage for you
+   partner: "my-app-name",
  });

Split flow (build → sign → post)

- const signable = await sdk.delta.buildDeltaOrder({ /* ... */ });
- const signature = await sdk.delta.signDeltaOrder(signable);
- const auction = await sdk.delta.postDeltaOrder({
-   order: signable.data,
+ const built = await sdk.delta.buildDeltaOrder({ /* ... */ });
+ const signature = await sdk.delta.signDeltaOrder(built);
+ const auction = await sdk.delta.postDeltaOrder({
+   order: built.toSign.value,
    signature,
    partner: "my-app-name",
  });

buildDeltaOrder now returns { toSign, orderHash } from the server (V1 returned SignableDeltaOrderData with a locally-composed .data). signDeltaOrder is unchanged and is generic across the market, limit, and TWAP flows.

Listing orders

- const orders = await sdk.delta.getDeltaOrders({ /* filter */ });
+ const { data, total, hasMore } = await sdk.delta.getDeltaOrders({
+   userAddress: account,
+   page: 1,
+   limit: 100,
+ });

V1 returned a flat DeltaAuction[]. V2 returns a paginated { data, total, page, limit, hasMore } envelope, and userAddress is required.

Cancelling

- await sdk.delta.cancelLimitDeltaOrders({ orderIds: [orderId] });
+ await sdk.delta.cancelDeltaOrders({ orderIds: [orderId] });

Bridge inspection

- await sdk.delta.getBridgeInfo(/* ... */);
+ await sdk.delta.getBridgeRoutes(/* ... */);

getBridgeRoutes returns a flat routes[] array instead of V1’s nested srcChainId → destChainId → tokens[] map.

What stays the same

sdk.delta.* — same namespace and method names.
approveTokenForDelta, getDeltaContract, preSignDeltaOrder, and getPartnerFee are unchanged.
Type names (DeltaPrice, DeltaAuction, BuiltDeltaOrder) are still imported bare from the package root — only their shapes changed.
The on-chain order struct and signature format are identical, so V2 is just a different way to assemble the same on-chain payload.

If you call the HTTP API directly rather than through the SDK, see Delta V1 → V2 (HTTP API).

Market — the other swap execution path (user-submitted transactions).
Limit orders: a Delta order with a target price.
TWAP, a Delta order split into scheduled slices.
Why Delta. The protocol design.
Monetize — partner-fee fields.
API reference → Delta covers the HTTP endpoints.

​When to use this

​How it’s exposed

​The flow

​One-call submit

​Split flow

​Poll for execution

​List orders

​Partner fee

​Cancel an order

​Crosschain Delta

​Other Delta products

​Migrate from V1 to V2

​Pricing

​One-call submit

​Split flow (build → sign → post)

​Listing orders

​Cancelling

​Bridge inspection

​What stays the same

​Related pages

When to use this

How it’s exposed

The flow

One-call submit

Split flow

Poll for execution

List orders

Partner fee

Cancel an order

Crosschain Delta

Other Delta products

Migrate from V1 to V2

Pricing

One-call submit

Split flow (build → sign → post)

Listing orders

Cancelling

Bridge inspection

What stays the same

Related pages