Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions delta/crosschain-delta.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ sequenceDiagram
participant API as Velora API
participant OS as Order Server
participant Solvers as Solver network<br/>(Portikus)
participant Settlement as Protocol settlement
participant Delta as Delta contract<br/>source chain
participant Bridge as Bridge provider<br/>(CCTP / Across / Relay / ...)
participant Dest as Destination chain
Expand All @@ -38,11 +39,12 @@ sequenceDiagram
rect rgb(232, 245, 233)
note over OS,Solvers: Source-chain Delta auction
OS->>Solvers: Broadcast order
Solvers-->>OS: Competing fills
Solvers-->>OS: Competing fill calldata
OS->>Solvers: Award winner
end

Solvers->>Delta: Settle on source chain
OS->>Settlement: Winning calldata + signed order
Settlement->>Delta: Settle on source chain
Delta->>Bridge: Initiate selected bridge leg
API-->>DApp: status = BRIDGING

Expand Down Expand Up @@ -115,7 +117,7 @@ Then use the same build, sign, and submit calls as a same-chain Delta order:

Delta does not ask the user to perform a separate bridge transaction. The user signs a Delta order that already contains the selected destination chain, output token, and bridge execution data.

At settlement time, the winning solver executes the source-chain Delta order through Portikus. If the order is crosschain, the settlement module sends the post-swap output into the selected bridge module instead of transferring it locally to the user. The destination output is delivered to the order beneficiary on the destination chain.
At settlement time, the protocol executes the winning solver's source-chain calldata through Portikus. If the order is crosschain, the settlement module sends the post-swap output into the selected bridge module instead of transferring it locally to the user. The destination output is delivered to the order beneficiary on the destination chain.

For USDC routes, CCTP support is USDC-specific. Delta can still quote arbitrary source tokens when the source-chain leg swaps into the bridge token first, but the CCTP bridge leg itself moves USDC between supported chains.

Expand Down
14 changes: 8 additions & 6 deletions delta/how-it-works.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: "From signed intent to on-chain settlement: the full Delta flow end
keywords: ["delta","architecture","flow","portikus","solver"]
---

Delta separates **what the user wants** (the intent) from **how it gets executed** (the solver fill). The user signs once, off-chain. Solvers on the [Portikus Network](/solver-network/portikus) race to fill the order at the best price, then settle on-chain via the Delta contract.
Delta separates **what the user wants** (the intent) from **how it gets executed** (the fill). The user signs once, off-chain. Solvers on the [Portikus Network](/solver-network/portikus) race to provide the best executable calldata, and protocol settlement executes the winning calldata through the Delta contract.

## The flow at a glance

Expand All @@ -16,6 +16,7 @@ sequenceDiagram
participant API as Velora API
participant OS as Order Server
participant Solvers as Portikus Network<br/>(solvers)
participant Settlement as Protocol settlement
participant Delta as Delta contract<br/>0x...c96d

User->>DApp: "Swap 1000 USDC for USDT"
Expand All @@ -34,11 +35,12 @@ sequenceDiagram
rect rgb(232, 245, 233)
note over OS,Solvers: Off-chain auction
OS->>Solvers: Broadcast order
Solvers-->>OS: Competing fill quotes
Solvers-->>OS: Competing fill calldata
OS->>Solvers: Award winner
end

Solvers->>Delta: settle(order, signature, fillData)
OS->>Settlement: Winning calldata + signed order
Settlement->>Delta: settle(order, signature, fillData)
Delta-->>User: destToken delivered

loop Until terminal status
Expand Down Expand Up @@ -67,17 +69,17 @@ The user signs the returned `toSign` typed data with their wallet. The build res

### 4. Auction

You `POST /v2/delta/orders` with `order` (the `toSign.value`), the `signature`, `chainId`, and your `partner`. The order server persists it and runs a [sealed-bid auction](/solver-network/sealed-bid-auctions) across the **Portikus Network**: solvers bid in parallel without seeing each other's offers, and the best simulated outcome wins. The winning solver commits to fill the order with their own capital; they take on inventory and settlement risk in exchange for the spread.
You `POST /v2/delta/orders` with `order` (the `toSign.value`), the `signature`, `chainId`, and your `partner`. The order server persists it and runs a [sealed-bid auction](/solver-network/sealed-bid-auctions) across the **Portikus Network**: solvers bid in parallel without seeing each other's offers, and the best simulated outcome wins. The winning solver commits fill calldata and the capital needed to deliver it; they take on inventory and pricing risk in exchange for the spread.

### 5. Settle

The winning solver calls `settle(...)` on the Delta contract (`0x0000000000bbF5c5Fd284e657F01Bd000933C96D`, same address on every supported chain). The contract verifies the signature, pulls `srcToken` from the user via the approved spender (the Delta contract itself), runs the fill, and delivers `destToken` to the user. You track progress via `GET /v2/delta/orders/{orderId}` until the order reaches a terminal status (`COMPLETED`, `EXPIRED`, `FAILED`, or `CANCELLED`).
The protocol settlement layer calls `settle(...)` on the Delta contract (`0x0000000000bbF5c5Fd284e657F01Bd000933C96D`, same address on every supported chain) with the signed order and the winning solver's fill calldata. The contract verifies the signature, pulls `srcToken` from the user via the approved spender (the Delta contract itself), runs the fill, and delivers `destToken` to the user. You track progress via `GET /v2/delta/orders/{orderId}` until the order reaches a terminal status (`COMPLETED`, `EXPIRED`, `FAILED`, or `CANCELLED`).

## Why this design

<CardGroup cols={2}>
<Card title="Gasless for users" icon="gas-pump">
Users sign off-chain. Solvers pay gas and recoup it from their margin.
Users sign off-chain. Settlement gas is handled inside the Delta flow.
</Card>
<Card title="MEV-protected" icon="shield">
Orders are auctioned privately. There's no public mempool to sandwich.
Expand Down
4 changes: 2 additions & 2 deletions delta/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,13 @@ title: "Why Delta"
description: "Delta is Velora's intent protocol: gasless, MEV-protected, Crosschain swaps that settle in one signature. Here's what makes it different from a regular swap."
---

Delta is Velora's intent protocol. Instead of building, signing, and submitting an on-chain transaction yourself, you sign an off-chain **order** describing what you want, and a competitive network of solvers (the [Portikus Network](/solver-network/portikus)) fills it on your behalf.
Delta is Velora's intent protocol. Instead of building, signing, and submitting an on-chain transaction yourself, you sign an off-chain **order** describing what you want. A competitive network of solvers (the [Portikus Network](/solver-network/portikus)) submits fill calldata, and Delta settles the winning fill for you.

## What you get

<CardGroup cols={3}>
<Card title="Gasless" icon="gas-pump">
The user never pays gas. Solvers cover execution cost out of their margin.
The user never pays gas. Execution cost is handled inside the Delta settlement flow.
</Card>
<Card title="MEV-protected" icon="shield" href="/solver-network/sealed-bid-auctions">
Orders are filled via sealed-bid auction. No public mempool. No sandwich risk.
Expand Down
4 changes: 2 additions & 2 deletions for-agents/decision-tables.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Use these tables when an agent needs to choose the next Velora action. Prefer ex
| User intent | Prefer | Agent action | Why |
|---|---|---|---|
| "Swap token A to token B" | `mode=ALL` | Call [`GET /v2/quote`](/api-reference/market/quote) with `mode=ALL`, `chainId`, token addresses, amount, slippage, and the app or project `partner` value. | Velora can choose the best available path. |
| "Gasless swap" or "I have no gas" | Delta | Call `GET /v2/quote` with `mode=DELTA`. Continue only if the response includes a `delta` block. | Delta uses an EIP-712 signature and solver settlement. |
| "Gasless swap" or "I have no gas" | Delta | Call `GET /v2/quote` with `mode=DELTA`. Continue only if the response includes a `delta` block. | Delta uses an EIP-712 signature, a solver auction, and protocol settlement. |
| "Place a limit order" or "trade only if price reaches X" | Delta `LIMIT` order | Collect the target price, side, token pair, chain, amount, expiry, recipient, and partially-fillable preference before building the order. | New limit orders are Delta orders over the Delta API, not AugustusRFQ. |
| "TWAP this trade" or "split this order over time" | Delta TWAP | Collect side, total amount, number of slices, cadence/interval, chain, token pair, slippage/price constraints, deadline/expiry, recipient, and max source spend for buy TWAPs. | TWAP is one scheduled Delta order, not repeated independent swaps. Preserve sell-vs-buy amount semantics. |
| "Best price" | `mode=ALL` | Quote with `mode=ALL`, then branch on `delta` vs `market`. | Velora can choose the best available path. |
Expand Down Expand Up @@ -98,7 +98,7 @@ Use these tables when an agent needs to choose the next Velora action. Prefer ex
| HMAC or quote validation error | The quote payload is stale or mismatched. | Requote and rebuild from the same fresh response. |
| Approval transaction succeeds but swap still fails allowance check | Approval went to the wrong spender or wrong chain. | Check the spender for the selected mode and ask for a new approval if needed. |
| User rejects transaction or signature | User declined the action. | Stop. Do not retry automatically. |
| Delta order remains pending | Solver settlement is still in progress or the order may expire. | Poll status with backoff and show the latest order state. Do not resubmit blindly. |
| Delta order remains pending | The auction or protocol settlement is still in progress, or the order may expire. | Poll status with backoff and show the latest order state. Do not resubmit blindly. |
| Transaction reverts | Market transaction failed on-chain. | Surface the revert, suggest requoting, and avoid replaying the same calldata. |

## Guardrails for agents
Expand Down
2 changes: 1 addition & 1 deletion for-agents/prompt-library/crosschain-aave-deposit.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Requirements:
- The user holds (say) USDC on Polygon. They want to end up with aUSDC supplied to Aave v3 on Base. One signature.
- Use Velora's Crosschain Delta V2 API. Endpoints: `GET /v2/quote` (with `mode=DELTA` and `destChainId` per [Crosschain Delta docs]), `POST /v2/delta/orders/build`, `POST /v2/delta/orders`.
- Always set `partner` to the host app's partner identifier on every quote call (`my-app-name` is only a placeholder).
- The solver fills on Base; you provide a post-fill calldata hook that calls `aavePool.supply(USDC, amount, user, 0)` against Aave v3's Base pool address.
- The winning fill resolves on Base; you provide a post-fill calldata hook that calls `aavePool.supply(USDC, amount, user, 0)` against Aave v3's Base pool address.
- Read the Aave v3 pool address from a constants file (do NOT hardcode in component code).
- Surface clear status: "Quoting" → "Signing" → "Filling on Base" → "Depositing into Aave" → "Done".
- On failure at any stage, return the user to a recoverable state. Cancel the Delta order if it hasn't filled.
Expand Down
4 changes: 2 additions & 2 deletions integrate/api/delta-swap.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: "Integrate a gasless, MEV-protected Delta swap over the REST API: q
keywords: ["delta api", "gasless swap", "intent", "quote", "orders build", "orders submit", "dETH", "native eth"]
---

A **Delta swap** lets your user sign one off-chain intent and have the [Portikus Network](/solver-network/portikus) settle it gaslessly, 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.
A **Delta swap** lets your user sign one off-chain intent that Delta settles gaslessly through the [Portikus Network](/solver-network/portikus), 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](/delta/how-it-works). For a typed wrapper over these same calls, see [SDK → Delta](/sdk/products/delta).

Expand Down Expand Up @@ -111,7 +111,7 @@ The relayer validates the signature, balance, and allowance, then enrolls the or
curl 'https://api.velora.xyz/v2/delta/orders/{orderId}'
```

Poll until the order reaches a terminal status. A market Delta order settles in seconds once a solver wins the auction, so a short interval is fine.
Poll until the order reaches a terminal status. A market Delta order usually settles in seconds once the auction has a winning fill, so a short interval is fine.

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.

Expand Down
2 changes: 1 addition & 1 deletion integrate/api/market-swap.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ keywords: ["market api", "swap", "dex aggregator api", "price route", "build tra

A **Market swap** routes through DEX liquidity and settles in a single on-chain transaction that **your user signs and broadcasts**. This page walks the whole integration request by request: get a price route, build the calldata, approve the router, and send the transaction. Every example targets `https://api.velora.xyz`; no SDK required.

Market is the right path when the user has gas and wants synchronous, atomic settlement. For gasless, MEV-protected swaps the solver network settles on the user's behalf, use a [Delta swap](/integrate/api/delta-swap) instead. For the conceptual model, see [Market → How it works](/market/how-it-works); for a typed wrapper, see [SDK → Market](/sdk/products/swap).
Market is the right path when the user has gas and wants synchronous, atomic settlement. For gasless, MEV-protected swaps that Delta settles from a signed intent, use a [Delta swap](/integrate/api/delta-swap) instead. For the conceptual model, see [Market → How it works](/market/how-it-works); for a typed wrapper, see [SDK → Market](/sdk/products/swap).

## The flow

Expand Down
4 changes: 2 additions & 2 deletions integrate/api/twap.mdx
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
---
title: "TWAP"
description: "Schedule a TWAP over the REST API. A TWAP is one Delta order the user signs once; solvers settle it slice-by-slice over time. Quote one slice, build with orderType TWAPOrder, end-to-end."
description: "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."
keywords: ["twap api", "delta", "scheduled order", "slices", "time-weighted average price", "gasless", "TWAPOrder"]
---

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 the [Portikus Network](/solver-network/portikus) settles each eligible slice gaslessly until the order completes or expires. This page walks the whole integration with direct calls to `https://api.velora.xyz`.
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).

Expand Down
2 changes: 1 addition & 1 deletion overview/product-stack/limit-orders.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Limit orders separate **trade intent** from **trade timing**. Delta represents t
- The maker says what they are willing to sell or buy.
- The maker sets constraints such as price, token pair, amount, expiry, and eligible taker behavior.
- When the limit price becomes reachable, the order enters the Delta pricing auction. Solvers from the Portikus network act as takers and compete on fill quotes, so the user gets the best committed return, not just the limit price.
- Delta settles the order on-chain when the winning solver fills it.
- Delta settles the order on-chain when the winning solver's fill satisfies it.

This gives users price control without forcing them to watch the market and submit a swap at the exact moment liquidity appears.

Expand Down
4 changes: 2 additions & 2 deletions resources/chains-and-contracts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -56,15 +56,15 @@ Legacy router versions. Still operational but new integrations should target v6.

### Delta contract

On-chain entry point that validates signed Delta orders and dispatches settlement to Portikus solvers. The Delta contract is the spender on EIP-712 typed-data approvals: token approvals for Delta flows must be granted to this address, **not** to Augustus. Deployed at the same address across every Delta-enabled chain.
On-chain entry point that validates signed Delta orders and executes the winning Portikus fill through settlement. The Delta contract is the spender on EIP-712 typed-data approvals: token approvals for Delta flows must be granted to this address, **not** to Augustus. Deployed at the same address across every Delta-enabled chain.

### Delta Wrapped Native (dETH)

The wrapped-native token Delta uses to represent native ETH (and other native gas tokens) as an ERC-20, at a 1:1 rate. When a user sells native ETH through Delta, their ETH is represented as dETH, which is why a native source needs no ERC-20 approval. Deployed alongside the Delta contract at the same address on every Delta-enabled chain, so native ETH works as a source wherever Delta does. See [Native ETH (dETH)](/delta/native-eth) for the integration detail.

### Portikus settlement

The solver-facing settlement infrastructure. Solvers execute fills against Portikus; the Delta contract reconciles outcomes back to the user.
The solver-facing settlement infrastructure. Solvers compete by providing fills through Portikus; the Delta contract reconciles the winning outcome back to the user.

### AugustusRFQ

Expand Down
2 changes: 1 addition & 1 deletion resources/migrations/market-to-delta-parallel.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Nothing. This migration is opt-in. Your existing Market integration keeps workin

## Why migrate

Delta intents are gasless and MEV-protected: users sign once and the solver network fills. And you don't rewrite anything to get there. `GET /v2/quote` with `mode=ALL` returns either a Delta `delta` block or a Market `market` block (the same shape as `/prices`'s `priceRoute`). Velora picks the winner server-side; you branch on which block is present. See [Trading modes](/integrate/trading-modes).
Delta intents are gasless and MEV-protected: users sign once, solvers compete to fill, and Delta settles the winning fill. And you don't rewrite anything to get there. `GET /v2/quote` with `mode=ALL` returns either a Delta `delta` block or a Market `market` block (the same shape as `/prices`'s `priceRoute`). Velora picks the winner server-side; you branch on which block is present. See [Trading modes](/integrate/trading-modes).

## Steps

Expand Down
Loading