> ## Documentation Index
> Fetch the complete documentation index at: https://digraphsas-docs-cli.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# TWAP API integration

> Schedule a TWAP over the REST API. A TWAP is one Delta order the user signs once; Delta settles it slice-by-slice over time. Quote one slice, build with orderType TWAPOrder, end-to-end.

A **TWAP** (time-weighted average price) splits a larger trade into slices executed over time. On Velora it's **one Delta order**, not a loop of swaps: the user signs a single scheduled order, and Delta settles each eligible slice gaslessly through the [Portikus Network](/solver-network/portikus) until the order completes or expires. This page walks the whole integration with direct calls to `https://api.velora.xyz`.

It's the [Delta swap](/integrate/api/delta-swap) flow with one wrinkle that trips people up: **you quote a single slice**, not the whole order, and the server multiplies it across the schedule. For the conceptual model, see [Product stack → TWAP](/overview/product-stack/twap). For a typed wrapper, see [SDK → TWAP](/sdk/products/twap).

## Sell vs buy

A TWAP is either a sell or a buy, and the field that fixes the total differs:

* **Sell TWAP** (`orderType: "TWAPOrder"`) fixes the total **source** amount and splits it across slices. Set `totalSrcAmount`.
* **Buy TWAP** (`orderType: "TWAPBuyOrder"`) fixes the total **destination** amount to receive and caps the total source spent. Set `totalDestAmount` and `maxSrcAmount`.

## The flow

<Steps>
  <Step title="Quote one slice">
    `GET /v2/quote?mode=DELTA` for the **per-slice** amount, `floor(total / numSlices)`. The route's amount must match that slice; the server applies it across the schedule.
  </Step>

  <Step title="Approve the total">
    Approve the **total** source on-chain (`totalSrcAmount` for sell, `maxSrcAmount` for buy), not one slice. A TWAP uses approval, not a permit; see [Approvals and permit](/resources/approvals). Native source skips this.
  </Step>

  <Step title="Build the schedule">
    `POST /v2/delta/orders/build` with the `orderType`, `interval`, `numSlices`, a `deadline`, and the totals. See [`POST /v2/delta/orders/build`](/api-reference/delta/orders-build).
  </Step>

  <Step title="Sign and submit">
    The user signs `toSign`; `POST /v2/delta/orders`. See [`POST /v2/delta/orders`](/api-reference/delta/orders-submit).
  </Step>

  <Step title="Poll over the order's lifetime">
    Each slice settles as it becomes eligible; the order completes when the final slice settles, or expires if its constraints can no longer be met.
  </Step>
</Steps>

## 1. Quote one slice

Quote the per-slice amount, not the total. For a 4-slice sell of 10,000 USDC, quote `10000000000 / 4 = 2500000000`:

```bash theme={null}
curl -G 'https://api.velora.xyz/v2/quote' \
  --data-urlencode 'srcToken=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' \
  --data-urlencode 'destToken=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE' \
  --data-urlencode 'amount=2500000000' \
  --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'
```

For a sell TWAP, `route.origin.input.amount` must equal `floor(totalSrcAmount / numSlices)`. For a buy TWAP, `route.origin.output.amount` must equal `floor(totalDestAmount / numSlices)`. Each slice executes that floored amount, and the final slice picks up the rounding remainder, so the order settles the exact total. Then approve the **total** source amount, not the slice. Approve on-chain rather than with a permit, which can't cover a multi-slice order (see [Approvals and permit](/resources/approvals)).

## 2. Build the schedule (sell TWAP)

```bash theme={null}
curl -X POST 'https://api.velora.xyz/v2/delta/orders/build' \
  -H 'Content-Type: application/json' \
  -d '{
    "orderType": "TWAPOrder",
    "route": { "...": "the single-slice delta.route, unchanged" },
    "owner": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "totalSrcAmount": "10000000000",
    "numSlices": 4,
    "interval": 300,
    "slippage": 50,
    "deadline": 1893456000,
    "partner": "my-app-name"
  }'
```

`numSlices` is at least 2 and `interval` (seconds between slices) at least 60. The `deadline` must leave room for the whole schedule: at least `numSlices × interval` seconds from now, or the submit call rejects the order. The response is the same `{ toSign, orderHash }` as any Delta order.

### Buy TWAP

A buy TWAP fixes how much to receive and caps what's spent. Quote a single slice by the per-slice destination amount, then build with `totalDestAmount` and `maxSrcAmount`. Each slice may spend at most its proportional share of `maxSrcAmount`, so a single expensive slice can't eat the whole budget:

```bash theme={null}
curl -X POST 'https://api.velora.xyz/v2/delta/orders/build' \
  -H 'Content-Type: application/json' \
  -d '{
    "orderType": "TWAPBuyOrder",
    "route": { "...": "single-slice route; output.amount = floor(totalDestAmount / numSlices)" },
    "owner": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "totalDestAmount": "3000000000000000000",
    "maxSrcAmount": "10100000000",
    "numSlices": 4,
    "interval": 300,
    "slippage": 50,
    "deadline": 1893456000,
    "partner": "my-app-name"
  }'
```

## 3. Sign and submit

The user signs `toSign` (ERC-2098 compact signature), then you submit the order. There's no TWAP-specific submit; it's the same call as a market Delta order:

```bash theme={null}
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"
  }'
```

## 4. Poll, list, and cancel

Poll `GET /v2/delta/orders/{orderId}` over the order's lifetime; the `input`/`output` amounts carry expected and executed totals, so you can show fill progress without computing it yourself. For a human-readable view of slice-by-slice progress, open the order in the Velora explorer at `https://explorer.velora.xyz/order/{orderId}`. List a user's TWAPs by filtering on `onChainOrderType`:

```bash theme={null}
curl -G 'https://api.velora.xyz/v2/delta/orders' \
  --data-urlencode 'userAddress=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' \
  --data-urlencode 'chainId=1' \
  --data-urlencode 'onChainOrderType=TWAPOrder'
```

Cancel the remaining (unsettled) slices with a gasless signed cancellation, the same call as any Delta order:

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

See [`GET /v2/delta/orders`](/api-reference/delta/orders-list) and [`POST /v2/delta/orders/cancel`](/api-reference/delta/orders-cancel).

## Partner fee

Pass `partner` on the quote, build, and submit calls (plus optional `partnerAddress`, `partnerFeeBps`, `partnerTakesSurplus`), exactly as for a Delta swap. See [Monetize](/sdk/monetize).

## Related pages

* [Delta swap](/integrate/api/delta-swap): the base flow a TWAP extends.
* [Limit orders](/integrate/api/limit-orders), the other scheduled Delta order type.
* [Product stack → TWAP](/overview/product-stack/twap) for the conceptual model.
* [Delta API reference](/api-reference/delta/overview) lists full parameters and response schemas.
* [SDK → TWAP](/sdk/products/twap), a typed wrapper over this flow.