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. A native ETH source has no approval; it’s authorized by a deposit transaction after submit — see Native ETH (dETH). For ERC-20s, 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 replaces this step (and the signature in step 4) with a different mechanic: you submit the order with signature: "0x", then the user sends one depositNativeAndPreSign transaction that escrows the ETH in the Delta contract and authorizes the order on-chain. Follow Native ETH (dETH) for that flow; the quote, build, and poll steps on this page apply unchanged.

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.

Native ETH source: submit with signature: "0x" instead of a signed payload. The order is stored as AWAITING_SIGNATURE and activates once the user’s deposit transaction lands.

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. A native ETH source order that expires unfilled also ends in REFUNDED — that’s the deposited ETH being returned to the owner, not an error. 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