Migrate from Delta V1 to V2

​

What breaks if you do nothing

​

Why migrate

• Crosschain is native to pricing. GET /v2/quote or GET /v2/delta/prices returns a recommended route with route.bridge populated for crosschain, plus alternatives when other bridge routes are available.
• Orders are built server-side. POST /v2/delta/orders/build returns EIP-712 typed data ready to sign, and you stop composing domain, types, and value on the client.
• Pricing is route-based. The route replaces the bridge / bridgeInfo / availableBridges triple V1 returns.
• Limit orders use the same build flow. Add limitAmount to POST /v2/delta/orders/build, then submit the signed order with type: "LIMIT".
• Order history is paginated. GET /v2/delta/orders returns { data, total, page, limit, hasMore } where V1 returns a flat array with no total.
• Status is a single field. Twelve values (PENDING, AWAITING_SIGNATURE, ACTIVE, SUSPENDED, CANCELLING, BRIDGING, COMPLETED, FAILED, EXPIRED, REFUNDING, CANCELLED, REFUNDED) replace V1’s status + bridgeStatus pair.
• Partner fees resolve on the server. Pass partner / partnerAddress / partnerFeeBps directly on every call; the separate GET /prices/partnerfee/{chainId} round-trip goes away.
• The hmac is gone. V2 doesn’t sign the price payload, so there’s no opaque blob to thread from /prices into /orders/build.

​

Endpoint mapping

​

Steps

​

1. Pricing

- GET /delta/prices?chainId=1&srcToken=0x...&destToken=0x...&amount=...&partner=my-app-name
+ GET /v2/delta/prices?chainId=1&srcToken=0x...&destToken=0x...&amount=...&partner=my-app-name

- GET /quote?chainId=1&srcToken=0x...&destToken=0x...&amount=...&mode=ALL&partner=my-app-name
+ GET /v2/quote?chainId=1&srcToken=0x...&destToken=0x...&amount=...&mode=ALL&partner=my-app-name

{
  "price": {
    "srcToken": "0x...", "destToken": "0x...",
    "srcAmount": "...", "destAmount": "...",
    "partner": "my-app-name", "partnerFee": 0.05,
    "bridge": { "destinationChainId": 0, "protocolSelector": "0x00000000", ... },
    "hmac": "0x..."
  },
  "deltaAddress": "0x..."
}

{
  "id": "req_...",
  "side": "SELL",
  "inputToken": { "chainId": 1, "address": "0x..." },
  "outputToken": { "chainId": 8453, "address": "0x..." },
  "route": {
    "origin": { "input": { ... }, "output": { ... } },
    "destination": { "input": { ... }, "output": { ... } },
    "bridge": { "...": "present for crosschain, null for same-chain" },
    "fees": { "gas": { ... }, "bridge": [] }
  },
  "alternatives": [],
  "partner": { "name": "my-app-name", "feePercent": 0.05 },
  "spender": "0x..."
}

• price.hmac is gone; don’t thread it into /orders/build.
• deltaAddress moved to spender. Approve spender as the ERC-20 spender (the on-chain Delta contract address itself is unchanged).
• Bridge detection changed. V1 used bridge.destinationChainId !== 0; V2 sets route.bridge to null for same-chain and populates it for crosschain. Read route.origin.input.token.chainId vs route.destination.output.token.chainId if you need a direct check.

​

2. Build

  POST /delta/orders/build
  {
-   "chainId": 1,
-   "owner": "0x...",
-   "price": { /* the full delta price object including hmac */ },
-   "slippage": 100
+   /* request goes to /v2/delta/orders/build instead */
  }

+ POST /v2/delta/orders/build
+ {
+   "owner": "0x...",
+   "route": { /* the route from /v2/delta/prices, verbatim */ },
+   "side": "SELL",
+   "slippage": 100,
+   "deadline": 1893456000,
+   "partner": "my-app-name",
+   "partnerFeeBps": 25
+ }

The chain ID is no longer part of the build request; V2 derives it from the route.

  // V1 response
- {
-   "data":  { /* on-chain Order struct */ },
-   "orderHash": "0x...",
-   "domain": { ... },
-   "types":  { ... }
- }

  // V2 response
+ {
+   "toSign": {
+     "domain": { ... },
+     "types":  { ... },
+     "value":  { /* on-chain Order struct, same shape as V1's `data` */ }
+   },
+   "orderHash": "0x..."
+ }

​

3. Sign

​

4. Submit

- POST /delta/orders
+ POST /v2/delta/orders
  {
    "chainId": 1,
-   "order": /* V1 build response's `data` */,
+   "order": /* V2 build response's `toSign.value` */,
    "signature": "0x...",
    "type": "MARKET",
    "partner": "my-app-name"
  }

​

5. Limit orders

+ POST /v2/delta/orders/build
+ {
+   "owner": "0x...",
+   "route": { /* the route from /v2/quote or /v2/delta/prices, verbatim */ },
+   "side": "SELL",
+   "deadline": 1893456000,
+   "limitAmount": "3000000000000000000",
+   "partner": "my-app-name"
+ }

+ POST /v2/delta/orders
+ {
+   "chainId": 1,
+   "order": /* V2 build response's `toSign.value` */,
+   "signature": "0x...",
+   "type": "LIMIT",
+   "partner": "my-app-name"
+ }

​

6. Poll for status

- GET /delta/orders/{orderId}
+ GET /v2/delta/orders/{orderId}

{
  "tx": "0x...",
  "chainId": 42161,
  "token": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
  "amount": "1454437"
}

​

7. List orders

- GET /delta/orders?userAddress=0x...&page=1&limit=100
+ GET /v2/delta/orders?userAddress=0x...&page=1&limit=100

- [ { "id": "...", "status": "...", ... }, ... ]
+ {
+   "data":    [ { "id": "...", "status": "...", ... }, ... ],
+   "total":   1234,
+   "page":    1,
+   "limit":   100,
+   "hasMore": true
+ }

​

8. Cancel

- POST /delta/orders/cancel
+ POST /v2/delta/orders/cancel
  {
    "orderIds":  ["..."],
    "signature": "0x..."
  }

​

9. Partner fee

- // V1: separate round-trip, then re-encode in build params
- const { partnerAddress, partnerFee, takeSurplus } =
-   await fetch(`/prices/partnerfee/${chainId}?partner=${key}`).then(r => r.json());
- POST /delta/orders/build { ..., partnerAddress, partnerFeeBps: partnerFee * 100, ... }

+ // V2: server resolves; just pass `partner`
+ POST /v2/delta/orders/build { ..., partner: "my-app-name" }

​

Breaking changes you might miss

• price.hmac is gone in V2. Existing code that re-attaches hmac to the build payload will fail validation.
• The replacement for V1 GET /quote is GET /v2/quote, not “no quote endpoint.” With mode=ALL, branch on top-level delta or market.
• Limit orders move onto the standard V2 build path. Add limitAmount to POST /v2/delta/orders/build, then submit with type: "LIMIT".
• The bridge.destinationChainId !== 0 check breaks. V2 sets route.bridge = null for same-chain; the V1 sentinel is no longer present in V2 responses.
• bridge-info changed shape, from a nested object to a flat routes[] array, and the replacement endpoint is named bridge-routes.
• The status enum changed, so your status-handling code needs the mapping table above. Don’t rely on EXECUTED alone: V2 reports COMPLETED for executed-and-finalized orders, BRIDGING while the destination leg is still pending, and REFUNDING while a failed bridge leg is waiting for a verified refund transaction.
• REFUNDED is now distinct from REFUNDING in V2. If your V1 UI showed any refund state as final, add an in-progress state before moving users to V2.
• The order list response changed from Order[] to { data: Order[], total, page, limit, hasMore }. Code that does orders.length or orders.map(...) on the response needs to unwrap .data first.

​

End-state check

1. GET /v2/quote?mode=DELTA or GET /v2/delta/prices returns a route and a non-empty spender.
2. POST /v2/delta/orders/build returns { toSign, orderHash }.
3. The signature your wallet produces over toSign is accepted by POST /v2/delta/orders (status 200, response carries the new order shape with id and status: "PENDING").
4. GET /v2/delta/orders/{id} polls through ACTIVE → COMPLETED (or BRIDGING → COMPLETED for crosschain). If a bridge refund happens, your UI can show REFUNDING until the order reaches REFUNDED and any verified refunds[] entries appear.
5. A limit-order build with limitAmount returns { toSign, orderHash }, and the signed order submits with type: "LIMIT".
6. grep -r "partnerfee\|/delta/prices\b\|/delta/orders\b" your-codebase/: every hit is intentional (e.g., /prices/partnerfee for UI lookup; /delta/orders only if you intentionally stayed on V1).

​

Related pages

• Delta V2 API overview — the recommended surface.
• SDK → Migrate from V1 to V2 — same migration at the TypeScript SDK level.
• Crosschain Delta swaps — how destChainId, bridge routes, and crosschain status work.
• Limit order API integration — build with limitAmount, then submit with type: "LIMIT".