Delta swap API integration

A Delta swap lets your user sign one off-chain intent that Delta settles gaslessly through the Portikus Network, with MEV protection. This page walks the whole integration end to end: quote the trade, build the order, have the user sign it, submit it, and poll until it settles. Every example is a curl or fetch call against https://api.velora.xyz; no SDK required. For the conceptual model behind the auction and settlement, see Delta → How it works. For a typed wrapper over these same calls, see SDK → Delta.

The flow

Quote the trade

GET /v2/quote?mode=DELTA returns a delta block with the recommended route, the spender to approve, and the resolved partner fee. See GET /v2/quote.

Approve the spender

Authorize the spender (the Delta contract) to pull the source token, by on-chain approval or a permit. Native source skips this. See Approvals and permit.

Build the order

POST /v2/delta/orders/build with the delta.route passed verbatim, owner set to the user, and a deadline. You get back { toSign, orderHash }. See POST /v2/delta/orders/build.

Sign and submit

The user signs toSign (ERC-2098 compact signature). POST /v2/delta/orders with the order, signature, chainId, and partner. See POST /v2/delta/orders.

Poll, or cancel before settlement

GET /v2/delta/orders/{orderId} until the status is terminal (COMPLETED, EXPIRED, FAILED, CANCELLED, REFUNDED). If the user cancels first, build a cancellation payload, have them sign it, then post it. See POST /v2/delta/orders/build/cancellation.

1. Quote

curl -G 'https://api.velora.xyz/v2/quote' \
  --data-urlencode 'srcToken=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' \
  --data-urlencode 'destToken=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE' \
  --data-urlencode 'amount=10000000000' \
  --data-urlencode 'srcDecimals=6' \
  --data-urlencode 'destDecimals=18' \
  --data-urlencode 'side=SELL' \
  --data-urlencode 'chainId=1' \
  --data-urlencode 'mode=DELTA' \
  --data-urlencode 'userAddress=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' \
  --data-urlencode 'partner=my-app-name'

The response carries a delta block:

{
  "delta": {
    "route": { "origin": { "input": { "amount": "10000000000" }, "output": { "amount": "..." } } },
    "spender": "0x...",
    "destAmount": "..."
  }
}

mode=DELTA returns a delta block or fails with a 400; it never falls back to Market. If you’d rather let Velora pick the cheaper path, send mode=ALL and branch on whether the response has a delta or a market block. See Trading modes.

2. Approve the spender

Authorize the Delta contract (the spender from the quote) to pull the source token at settlement, with either an on-chain approval or a signed permit. See Approvals and permit for both methods and when each applies. Selling native ETH skips this step; see Native ETH (dETH).

3. Build

Pass the delta.route from the quote verbatim into the build call, with owner set to the user’s address and a deadline (unix seconds) after which the order is unfillable:

curl -X POST 'https://api.velora.xyz/v2/delta/orders/build' \
  -H 'Content-Type: application/json' \
  -d '{
    "route": { "...": "the delta.route from the quote, unchanged" },
    "owner": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "deadline": 1893456000,
    "partner": "my-app-name"
  }'

{
  "toSign": { "domain": { "...": "..." }, "types": { "...": "..." }, "value": { "...": "..." } },
  "orderHash": "0x..."
}

Pass delta.route exactly as the quote returned it. Reordering or re-encoding any field makes the build call reject.

4. Sign and submit

The user signs the toSign typed data. Delta uses ERC-2098 compact signatures (64 bytes); viem, ethers v6, and wagmi produce them natively. Then submit the signed order:

curl -X POST 'https://api.velora.xyz/v2/delta/orders' \
  -H 'Content-Type: application/json' \
  -d '{
    "chainId": 1,
    "order": { "...": "toSign.value, sent verbatim" },
    "signature": "0x...",
    "partner": "my-app-name"
  }'

The relayer validates the signature, balance, and allowance, then enrolls the order in the sealed-bid auction. The response is the stored order with its id.

5. Poll for settlement

curl 'https://api.velora.xyz/v2/delta/orders/{orderId}'

Poll until the order reaches a terminal status. A same-chain market Delta order usually settles in seconds once the auction has a winning fill, so a short interval is fine. Crosschain orders can spend longer in BRIDGING, or in REFUNDING if the bridge leg failed and a refund transaction is still being verified. For a human-readable view (status, fills, the settlement transaction), open the order in the Velora explorer at https://explorer.velora.xyz/order/{orderId}. It’s handy for debugging and for linking users to their order.

6. Cancel before settlement

Cancellation is gasless. Build the EIP-712 cancellation payload for one or more open orders, have the user sign the returned toSign object, then post the same orderIds with the signature.

curl -X POST 'https://api.velora.xyz/v2/delta/orders/build/cancellation' \
  -H 'Content-Type: application/json' \
  -d '{ "orderIds": ["..."] }'

curl -X POST 'https://api.velora.xyz/v2/delta/orders/cancel' \
  -H 'Content-Type: application/json' \
  -d '{ "orderIds": ["..."], "signature": "0x..." }'

Cancellation only succeeds while the order is still open or executing. See POST /v2/delta/orders/build/cancellation and POST /v2/delta/orders/cancel.

Partner fee

Pass partner on the quote, build, and submit calls to attribute volume and capture a fee; add partnerAddress, partnerFeeBps, and partnerTakesSurplus to configure it. See Monetize for the field reference.

Delta → How it works: the auction and settlement model behind these calls.
Trading modes covers DELTA vs MARKET vs ALL and the fallback envelope.
Native ETH (dETH): selling native ETH as a Delta source.
Limit orders and TWAP, the same flow with a price constraint or a schedule.
Delta API reference for full parameters and response schemas.
SDK → Delta, a typed wrapper over this flow.

​The flow

​1. Quote

​2. Approve the spender

​3. Build

​4. Sign and submit

​5. Poll for settlement

​6. Cancel before settlement

​Partner fee

​Related pages

The flow

1. Quote

2. Approve the spender

3. Build

4. Sign and submit

5. Poll for settlement

6. Cancel before settlement

Partner fee

Related pages