@switch-win/sdk 1.2.2 → 1.2.4

package/LIMIT-ORDERS.md

@@ -0,0 +1,737 @@
+# Switch Limit Orders — Integration Guide
+
+> **Gasless EIP-712 signed limit orders on PulseChain and Robinhood Chain**
+
+**Limit Order API:** `https://quote.switch.win`
+
+| API network | Chain ID | Native currency | Current limit-order contract | Native flow contract |
+|---|---:|---|---|---|
+| `pulsechain` | 369 | PLS | `0x8e3881bdF81Fc0211383B2e576076B654F7aFD86` | `0x88c9e2C83b6B7c707602e548481e58E920694E64` |
+| `robinhood` | 4663 | ETH | `0x752c50DDd3B426cAE3D7A995F313Ac74ac6B0230` | `0x029FfC6aF9112eA078f1D6f4a98826DDB2136cf6` |
+
+Pass `network: "pulsechain"` or `network: "robinhood"` to every SDK API
+helper. Call `fetchLimitOrderConfig({ network })` at startup and treat its
+addresses and EIP-712 domain as the live source of truth.
+
+---
+
+## Table of Contents
+
+0. [Installation](#installation)
+1. [Overview](#overview)
+2. [How It Works](#how-it-works)
+3. [Creating a Limit Order](#creating-a-limit-order)
+4. [Native Currency Limit Orders (SwitchPLSFlow)](#native-currency-limit-orders-switchplsflow)
+5. [Choosing `feeOnOutput`](#choosing-feeonoutput)
+6. [Querying Limit Orders](#querying-limit-orders)
+7. [Cancelling a Limit Order](#cancelling-a-limit-order)
+8. [API Reference](#api-reference)
+9. [Types Reference](#types-reference)
+10. [Helper Functions](#helper-functions)
+11. [EIP-712 Signing Details](#eip-712-signing-details)
+12. [On-Chain Revert Errors](#on-chain-revert-errors)
+
+---
+
+## Installation
+
+```bash
+npm install @switch-win/sdk
+# or
+yarn add @switch-win/sdk
+# or
+pnpm add @switch-win/sdk
+```
+
+---
+
+## Overview
+
+Switch Limit Orders let users place **gasless, signed orders** that are filled automatically when market conditions are met. Orders use **EIP-712 typed data signatures** — no tokens are deposited or locked.
+
+**Key properties:**
+
+- **No gas to create** — orders are signed off-chain and submitted to the Switch backend via REST API
+- **No token deposit** — tokens stay in the maker's wallet until the order is filled
+- **One approval per order type:**
+  - `feeOnOutput: false` (default) → approve **SwitchLimitOrder** (`getApprovalTarget()`)
+  - `feeOnOutput: true` → approve **SwitchRouter** (`getRouterApprovalTarget()`)
+- **EIP-712 signed** — standard typed data signatures, supported by all major wallets
+- **Nonce-based replay protection** — each order has a unique nonce per maker
+- **Optional expiry** — set a deadline or make the order valid forever
+- **Custom recipient** — output tokens can be sent to a different address
+- **Native unwrap** — WPLS can be unwrapped to PLS and Robinhood WETH can be
+  unwrapped to ETH by setting `unwrapOutput`
+
+> **⚠️ Important:** The `SWITCH_LIMIT_ORDER` address is the **current** default. The contract may be redeployed (e.g. when the router is upgraded). Each order returned by the API includes a `limitOrderContract` field — **always use the contract address from the order for on-chain interactions (approvals, cancellations), not a hardcoded constant.** This ensures your integration works seamlessly across contract versions without code changes.
+
+### Network-aware setup
+
+```ts
+import {
+  fetchLimitOrderConfig,
+  getLimitOrderApprovalTarget,
+  getNetworkEIP712SigningParams,
+  submitLimitOrder,
+} from "@switch-win/sdk/limit-orders";
+
+// `signer` and a completed `order` are assumed below.
+const network = "robinhood" as const;
+const live = await fetchLimitOrderConfig({ network });
+const { domain, types } = getNetworkEIP712SigningParams(
+  network,
+  live.limitOrderContract,
+);
+const approvalTarget = getLimitOrderApprovalTarget(network, order.feeOnOutput, {
+  limitOrderContract: live.limitOrderContract,
+});
+const signature = await signer.signTypedData(domain, types, order);
+await submitLimitOrder(
+  { ...order, signature, limitOrderContract: live.limitOrderContract },
+  { network },
+);
+```
+
+---
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│  1. APPROVE — one-time per token + fee mode                             │
+│       feeOnOutput=false → approve SwitchLimitOrder (getApprovalTarget)  │
+│       feeOnOutput=true  → approve SwitchRouter (getRouterApprovalTarget)│
+│                                                                         │
+│  2. SIGN — EIP-712 typed data (gasless, no transaction)                 │
+│                                                                         │
+│  3. SUBMIT — POST /limit-orders to Switch backend                       │
+│       ⚠️  CRITICAL: submit IMMEDIATELY after signing and AWAIT success  │
+│       The signature is off-chain only — if the POST never arrives,      │
+│       the order is permanently lost. See critical notes below.          │
+│                                                                         │
+│  4. FILL — automated by Switch operators when conditions are met        │
+│       Tokens are pulled from the maker's wallet and swapped.            │
+│       Output is sent to the maker (or custom recipient).                │
+│                                                                         │
+│  5. CANCEL (optional)                                                   │
+│       invalidateNonce(nonce) on-chain — prevents execution              │
+│       The backend indexer observes the cancellation event.              │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+> **⚠️ Why the POST is critical (ERC-20 orders)**
+>
+> For standard ERC-20 limit orders, the EIP-712 signature is **purely off-chain**.
+> Nothing is recorded on-chain until an operator fills the order. The backend
+> only knows about the order because your integration POSTed it.
+>
+> If the POST never arrives — user closes the browser, network error, frontend
+> navigates away — **the order is permanently lost**. No one can fill it.
+>
+> Your integration must:
+> 1. Call `submitLimitOrder()` **immediately** after the user signs.
+> 2. **Await** the response and confirm `success: true` before showing "order created".
+> 3. **Retry** on transient failures — the backend is idempotent on `maker + nonce`.
+> 4. Do **not** navigate away or close the signing flow until the backend confirms.
+>
+> *Native PLS/ETH flow orders are the exception — they are recorded on-chain*
+> *first, so the backend discovers them via event indexing even if the POST*
+> *never arrives.*
+
+---
+
+## Creating a Limit Order
+
+The full lifecycle in code (ethers.js v6):
+
+```ts
+import { ethers } from "ethers";
+import {
+  buildLimitOrder,
+  fetchLimitOrderConfig,
+  getLimitOrderApprovalTarget,
+  getNetworkEIP712SigningParams,
+  submitLimitOrder,
+} from "@switch-win/sdk/limit-orders";
+import { ERC20_ABI } from "@switch-win/sdk/constants";
+
+const network = "robinhood" as const;
+const provider = new ethers.JsonRpcProvider("https://rpc.mainnet.chain.robinhood.com");
+const signer = new ethers.Wallet(PRIVATE_KEY, provider);
+const maker = await signer.getAddress();
+const live = await fetchLimitOrderConfig({ network });
+
+// ── Step 1: Build the order ──
+const order = buildLimitOrder({
+  maker,
+  tokenIn: "0x0Bd7D308f8E1639FAb988Df18A8011f41EAcAD73",   // WETH
+  tokenOut: "0x5fc5360D0400a0Fd4F2aF552aDD042D716F1d168",  // USDG
+  amountIn: ethers.parseUnits("0.01", 18).toString(),
+  minAmountOut: ethers.parseUnits("30", 18).toString(),
+  deadline: Math.floor(Date.now() / 1000) + 86400,          // 24h expiry
+  // nonce: auto-generated from Date.now()
+  // feeOnOutput: false (default — fee taken from input)
+  // recipient: maker (default — output goes to maker)
+  // unwrapOutput: false (default)
+});
+
+// ── Step 2: Approve the correct contract (one-time per token + fee mode) ──
+//   feeOnOutput=false (default) → approve this network's LO contract
+//   feeOnOutput=true            → approve this network's SwitchRouter
+const approvalTarget = getLimitOrderApprovalTarget(network, order.feeOnOutput, {
+  limitOrderContract: live.limitOrderContract,
+});
+const token = new ethers.Contract(order.tokenIn, ERC20_ABI, signer);
+const allowance: bigint = await token.allowance(maker, approvalTarget);
+
+if (allowance < BigInt(order.amountIn)) {
+  const tx = await token.approve(approvalTarget, ethers.MaxUint256);
+  await tx.wait();
+}
+
+// ── Step 3: Sign via EIP-712 (gasless!) ──
+const { domain, types } = getNetworkEIP712SigningParams(
+  network,
+  live.limitOrderContract,
+);
+const signature = await signer.signTypedData(domain, types, order);
+
+// ── Step 4: Submit to the Switch backend ──
+// ⚠️ CRITICAL: The signature is off-chain only — if this POST fails,
+// the order is lost. Submit IMMEDIATELY after signing, await the
+// response, and retry on network failure.
+const result = await submitLimitOrder(
+  { ...order, signature, limitOrderContract: live.limitOrderContract },
+  { network },
+);
+
+if ("error" in result) {
+  // Retry logic recommended here — the backend is idempotent on maker+nonce
+  console.error("Failed:", result.error);
+} else {
+  console.log("Order created:", result.order.id);
+  console.log("Status:", result.order.status); // "ACTIVE"
+}
+```
+
+### Order Parameters
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `maker` | `string` | Yes | — | Maker (signer) address |
+| `tokenIn` | `string` | Yes | — | Input token address (token being sold) |
+| `tokenOut` | `string` | Yes | — | Output token address (token being bought) |
+| `amountIn` | `string` | Yes | — | Amount of tokenIn in wei |
+| `minAmountOut` | `string` | Yes | — | Minimum acceptable output in wei |
+| `deadline` | `number` | No | `0` | Unix timestamp expiry. `0` = no expiry |
+| `nonce` | `number` | No | `Date.now()` | Unique per maker. Auto-generated if omitted |
+| `feeOnOutput` | `boolean` | No | `false` | Fee mode — see [Choosing `feeOnOutput`](#choosing-feeonoutput) below |
+| `recipient` | `string` | No | `maker` | Address to receive output tokens |
+| `unwrapOutput` | `boolean` | No | `false` | Unwrap wrapped native output to PLS/ETH on the selected network |
+
+---
+
+## Native Currency Limit Orders (SwitchPLSFlow)
+
+When selling native **PLS** on PulseChain or native **ETH** on Robinhood
+(rather than WPLS/WETH), use the selected network's native-flow contract
+instead of the standard EIP-712 signing flow. The deployed contract retains
+the legacy `SwitchPLSFlow` name on both networks, but its behavior is
+native-currency neutral:
+
+- **No approval needed** — users send the native currency directly to the contract
+- **No EIP-712 signature** — the contract creates the order on-chain immediately
+- **Single transaction** — wrap + approve + place order all in one tx
+- **Fully indexed** — the backend discovers orders via `PLSOrderCreated` events
+
+### Native-flow contract address
+
+```ts
+import { getNativeFlowAddress, PLS_FLOW_ABI } from "@switch-win/sdk";
+
+const robinhoodNativeFlow = getNativeFlowAddress("robinhood");
+// "0x029FfC6aF9112eA078f1D6f4a98826DDB2136cf6"
+```
+
+### Creating a native ETH limit order on Robinhood
+
+```ts
+import { ethers } from "ethers";
+import { getNativeFlowAddress, isNativeCurrency } from "@switch-win/sdk/limit-orders";
+import { PLS_FLOW_ABI } from "@switch-win/sdk/constants";
+
+const network = "robinhood" as const;
+const provider = new ethers.JsonRpcProvider("https://rpc.mainnet.chain.robinhood.com");
+const signer = new ethers.Wallet(PRIVATE_KEY, provider);
+
+const NATIVE = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
+if (isNativeCurrency(NATIVE)) {
+  const nativeFlow = new ethers.Contract(
+    getNativeFlowAddress(network),
+    PLS_FLOW_ABI,
+    signer,
+  );
+  
+  const tokenOut = "0x5fc5360D0400a0Fd4F2aF552aDD042D716F1d168"; // USDG
+  const amountIn = ethers.parseEther("0.01");
+  const minAmountOut = ethers.parseUnits("30", 18);
+  const deadline = Math.floor(Date.now() / 1000) + 86400;         // 24h expiry
+  const feeOnOutput = false;
+  const unwrapOutput = false;
+
+  // Single transaction — no approval, no signing
+  const tx = await nativeFlow.createOrder(
+    tokenOut,
+    minAmountOut,
+    deadline,
+    feeOnOutput,
+    unwrapOutput,
+    ethers.ZeroAddress,      // partnerAddress (0x0 = no partner)
+    ethers.ZeroAddress,      // recipient (0x0 = defaults to msg.sender)
+    { value: amountIn }
+  );
+  
+  const receipt = await tx.wait();
+  console.log("Native ETH limit order created in tx:", receipt.hash);
+  
+  // The backend will automatically detect this order via PLSOrderCreated event.
+  // No POST to /limit-orders required (though it's harmless if you do).
+}
+```
+
+### Native flow vs EIP-712 orders
+
+| Aspect | Native flow (PLS/ETH) | EIP-712 (ERC-20) |
+|---|---|---|
+| **Input token** | Native currency | Any ERC-20 (including WPLS/WETH) |
+| **User experience** | Single transaction | Approve + Sign + Submit |
+| **Gas cost** | User pays gas | Gasless signing (user pays on fill) |
+| **Order discovery** | On-chain event | Requires successful POST |
+| **Maker address** | Native-flow contract | User's wallet |
+| **Recipient** | User's wallet (or custom) | User's wallet (or custom) |
+
+### Important: Order Discovery
+
+For native-flow orders, the `maker` field in the order record is the
+**native-flow contract address**, not the user's address. The actual user is
+stored in the `recipient` field.
+
+When querying orders for a user, use the `owner` parameter instead of `maker`:
+
+```ts
+// ✅ Correct — finds both EIP-712 and native-flow orders
+const { orders } = await fetchLimitOrders({
+  network: "robinhood",
+  owner: "0xUserAddress",  // matches maker OR recipient
+  status: "ACTIVE",
+});
+
+// ❌ Won't find native-flow orders
+const { orders } = await fetchLimitOrders({
+  network: "robinhood",
+  maker: "0xUserAddress",  // only matches maker field
+  status: "ACTIVE",
+});
+```
+
+### Cancelling a native-flow order
+
+Native-flow orders can be cancelled by the original creator (`recipient`):
+
+```ts
+const nativeFlow = new ethers.Contract(
+  getNativeFlowAddress("robinhood"),
+  PLS_FLOW_ABI,
+  signer,
+);
+
+// Cancel on-chain (only the original creator can call this)
+const tx = await nativeFlow.cancelOrder(nonceToCancel);
+await tx.wait();
+
+// The backend will detect the NonceCancelled event and update the order status.
+// No REST mutation is required.
+```
+
+---
+
+## Choosing `feeOnOutput`
+
+The `feeOnOutput` flag is **baked into the signed order** and cannot be changed after signing. It controls which contract the maker must approve **and** how flexibly operators (fillers) can execute the order. Choose carefully — it affects your order's fillability.
+
+### Approval target
+
+| `feeOnOutput` | Maker approves | SDK helper |
+|---|---|---|
+| `false` (default) | **SwitchLimitOrder** — LO contract pulls tokens from maker, then routes internally | `getApprovalTarget()` |
+| `true` | **SwitchRouter** — Router pulls tokens directly from maker to pool(s) | `getRouterApprovalTarget()` |
+
+Only **one** approval is needed per fee mode, but the target is different.
+
+### Operator (filler) flexibility
+
+Operators choose how to take their profit when filling an order: either from **excess input** (route less than `amountIn`, keep the unrouted tokens) or from **output surplus** (route all input, keep output above `minAmountOut`).
+
+| `feeOnOutput` | Excess from input | Excess from output |
+|---|---|---|
+| `false` | ✅ Always works | ✅ Always works |
+| `true` | ⚠️ Requires maker approved **both** LO + Router | ✅ Always works |
+
+When `feeOnOutput=false`, the LO contract pulls all tokens to itself first — operators have full freedom to optimize their profit-taking strategy.
+
+When `feeOnOutput=true`, the Router pulls tokens directly from the maker. If an operator also tries to take excess input via the LO contract, that requires a second approval the maker typically hasn't granted — the transaction would simply revert. The operator loses gas; the maker loses nothing and the order remains active for another operator. In practice, operators use output-side profit for `feeOnOutput=true` orders.
+
+> **Impact on fillability:** `feeOnOutput=true` orders are still fully fillable, but operators have less flexibility. In tight-margin or low-liquidity situations, this *could* reduce the likelihood of a fill since operators cannot optimize their profit-taking strategy on both sides.
+
+### Tax token decision guide
+
+| Scenario | Recommended `feeOnOutput` | Why |
+|---|---|---|
+| **Neither token is taxed** | `false` (default) | Maximum operator flexibility → best chance of fill |
+| **Input token is taxed** | `true` | Router sends tokens directly from maker → pool in one transfer (one tax). Default mode would do maker → LO → pool (two transfers, two taxes). |
+| **Output token is taxed** | `false` (default) | Output goes directly to recipient in one transfer. |
+| **Both tokens taxed** | `false` | Supported through tax-safe routes; fee on input avoids another output-token transfer. |
+
+> **Recommendation:** Use `feeOnOutput: false` (the default) unless the input token has a transfer tax. This gives operators the most flexibility and the best chance of filling your order.
+
+---
+
+## Querying Limit Orders
+
+```ts
+import {
+  fetchLimitOrders,
+  fetchLimitOrder,
+  fetchLimitOrderPairs,
+  fetchLimitOrderStats,
+} from "@switch-win/sdk/limit-orders";
+
+// All active orders for a maker
+const { orders, total } = await fetchLimitOrders({
+  maker: "0xYourAddress",
+  status: "ACTIVE",
+});
+
+// All orders for a user (includes native-PLS orders where user is recipient)
+const { orders: allMyOrders } = await fetchLimitOrders({
+  owner: "0xYourAddress",
+  status: "ACTIVE",
+});
+
+// Single order by maker + nonce
+const order = await fetchLimitOrder("0xYourAddress", 1717171717);
+
+// Active trading pairs with order counts
+const pairs = await fetchLimitOrderPairs();
+// [{ pairKey: "0xwpls:0xplsx", tokenIn: "0x...", tokenOut: "0x...", activeOrders: 42 }]
+
+// Global summary stats
+const stats = await fetchLimitOrderStats();
+// { active: 150, filled: 3200, cancelled: 45, expired: 12, total: 3407 }
+```
+
+### Query Filters
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `status` | `"ACTIVE" \| "FILLED" \| "CANCELLED" \| "EXPIRED"` | `"ACTIVE"` | Filter by order status |
+| `maker` | `string` | — | Filter by maker address |
+| `owner` | `string` | — | Filter by owner (matches maker OR recipient) |
+| `partnerAddress` | `string` | — | Filter by partner address stored on the order |
+| `tokenIn` | `string` | — | Filter by input token |
+| `tokenOut` | `string` | — | Filter by output token |
+| `pair` | `string` | — | Filter by pair key (`tokenIn:tokenOut`, lowercased) |
+| `limit` | `number` | `100` | Page size (1–500) |
+| `offset` | `number` | `0` | Page offset |
+
+> Each order record returned by the API includes the original `partnerAddress` used when the order was created, plus the `limitOrderContract` that should be used for on-chain cancellation/fill interactions.
+
+---
+
+## Cancelling a Limit Order
+
+Cancellation is an **on-chain operation**:
+
+1. **On-chain:** Call `invalidateNonce(nonce)` on the **order's** SwitchLimitOrder contract. This is the authoritative cancellation — it prevents any operator from executing the order even if the backend hasn't been notified yet.
+
+   > **⚠️** Each order includes a `limitOrderContract` field. Always use that address — do not hardcode a single contract constant, as the contract may be redeployed across versions.
+
+The backend indexer observes `NonceCancelled` and updates the orderbook. No
+separate REST mutation is required.
+
+```ts
+import { ethers } from "ethers";
+import { LIMIT_ORDER_ABI } from "@switch-win/sdk/constants";
+
+const signer = new ethers.Wallet(PRIVATE_KEY, provider);
+const maker = await signer.getAddress();
+const nonceToCancel = 1717171717;
+
+// Step 1: Invalidate the nonce on-chain (prevents fill)
+// ⚠️ Use order.limitOrderContract — not a hardcoded address
+const contract = new ethers.Contract(order.limitOrderContract, LIMIT_ORDER_ABI, signer);
+const tx = await contract.invalidateNonce(nonceToCancel);
+await tx.wait();
+
+// The backend indexer observes the event and marks the order CANCELLED.
+```
+
+To cancel **multiple orders** at once, use `invalidateNonces(uint256[])`:
+
+```ts
+const nonces = [1717171717, 1717171718, 1717171719];
+const tx = await contract.invalidateNonces(nonces);
+await tx.wait();
+
+// The backend indexer observes each NonceCancelled event.
+```
+
+---
+
+## API Reference
+
+**Base URL:** `https://quote.switch.win`
+
+| Method | Path | Description |
+|---|---|---|
+| `POST` | `/limit-orders` | Submit a signed limit order |
+| `GET` | `/limit-orders` | List orders (with query filters) |
+| `GET` | `/limit-orders/pairs` | Active pairs with order counts |
+| `GET` | `/limit-orders/stats` | Summary statistics |
+| `GET` | `/limit-orders/:maker/:nonce` | Single order by maker + nonce |
+
+### `POST /limit-orders`
+
+Submit a signed limit order. The backend verifies the EIP-712 signature before storing.
+
+> **⚠️ CRITICAL — Post immediately after signing.** For standard ERC-20 orders, the
+> EIP-712 signature is purely off-chain. Nothing is recorded on-chain until an operator
+> fills the order. If this POST never arrives (user closes browser, network
+> error, frontend navigates away), **the order is permanently lost**.
+>
+> Your integration must:
+> 1. Call `submitLimitOrder()` **immediately** after the user signs.
+> 2. **Await** the response and confirm `success: true` before showing "order created".
+> 3. **Retry** on transient failures — the backend is idempotent on `maker + nonce`.
+>
+> Native PLS/ETH flow orders are the exception — they are recorded on-chain first,
+> so the backend discovers them via event indexing even if the POST never arrives.
+
+**Request body:**
+
+```json
+{
+  "maker": "0x...",
+  "tokenIn": "0x...",
+  "tokenOut": "0x...",
+  "amountIn": "1000000000000000000",
+  "minAmountOut": "500000000000000000000",
+  "deadline": 1717257600,
+  "nonce": 1717171717,
+  "feeOnOutput": false,
+  "recipient": "0x...",
+  "unwrapOutput": false,
+  "limitOrderContract": "0x...",
+  "signature": "0x..."
+}
+```
+
+**Success response (201):**
+
+```json
+{
+  "success": true,
+  "order": {
+    "id": "clx...",
+    "maker": "0x...",
+    "tokenIn": "0x...",
+    "tokenOut": "0x...",
+    "amountIn": "1000000000000000000",
+    "minAmountOut": "500000000000000000000",
+    "deadline": 1717257600,
+    "nonce": 1717171717,
+    "feeOnOutput": false,
+    "recipient": "0x...",
+    "unwrapOutput": false,
+    "partnerAddress": "0x0000000000000000000000000000000000000000",
+    "limitOrderContract": "0x...",
+    "signature": "0x...",
+    "pairKey": "0x...:0x...",
+    "status": "ACTIVE",
+    "createdAt": "2025-01-01T00:00:00.000Z",
+    "updatedAt": "2025-01-01T00:00:00.000Z"
+  }
+}
+```
+
+**Error responses:**
+
+| Error | Cause |
+|---|---|
+| `"Missing required field: ..."` | A required field is missing from the body |
+| `"Invalid address format"` | One of the address fields is not a valid hex address |
+| `"tokenIn and tokenOut must differ"` | Trying to create an order that swaps a token to itself |
+| `"Invalid signature"` | EIP-712 signature verification failed |
+| `"Signature does not match maker"` | The recovered signer doesn't match the `maker` field |
+| `"Nonce N already used for maker 0x..."` | This nonce has already been used (filled or submitted) |
+
+### `GET /limit-orders`
+
+List orders with optional query filters. See [Query Filters](#query-filters) above.
+
+**Response:**
+
+```json
+{
+  "total": 42,
+  "limit": 100,
+  "offset": 0,
+  "orders": [
+    {
+      "id": "clx...",
+      "maker": "0x...",
+      "recipient": "0x...",
+      "tokenIn": "0x...",
+      "tokenOut": "0x...",
+      "amountIn": "1000000000000000000",
+      "minAmountOut": "500000000000000000000",
+      "deadline": 1717257600,
+      "nonce": 1717171717,
+      "feeOnOutput": false,
+      "unwrapOutput": false,
+      "partnerAddress": "0xYourPartnerAddress",
+      "limitOrderContract": "0x...",
+      "signature": "0x...",
+      "pairKey": "0x...:0x...",
+      "status": "ACTIVE",
+      "createdAt": "2025-01-01T00:00:00.000Z",
+      "updatedAt": "2025-01-01T00:00:00.000Z",
+      "filledTxHash": null,
+      "filler": null,
+      "fillerProfit": null
+    }
+  ]
+}
+```
+
+The backend currently returns the full order record, so integrations should expect at least the fields above and tolerate additional metadata fields in future deployments.
+
+### `GET /limit-orders/pairs`
+
+Returns active trading pairs with order counts.
+
+```json
+[
+  { "pairKey": "0xwpls:0xplsx", "tokenIn": "0x...", "tokenOut": "0x...", "activeOrders": 12 }
+]
+```
+
+### `GET /limit-orders/stats`
+
+Summary statistics.
+
+```json
+{ "active": 150, "filled": 3200, "cancelled": 45, "expired": 12, "total": 3407 }
+```
+
+---
+
+## Types Reference
+
+> All types are available in [`src/types.ts`](src/types.ts).
+
+| Type | Description |
+|---|---|
+| `LimitOrderParams` | Order fields for EIP-712 signing |
+| `SignedLimitOrder` | `LimitOrderParams` + `signature` |
+| `CreateLimitOrderRequest` | Alias for `SignedLimitOrder` (POST body) |
+| `LimitOrderStatus` | `"ACTIVE" \| "FILLED" \| "CANCELLED" \| "EXPIRED"` |
+| `LimitOrderRecord` | Full order record from the API (includes `partnerAddress`, `limitOrderContract`, status, and timestamps) |
+| `CreateLimitOrderResponse` | `{ success: true, order: LimitOrderRecord }` |
+| `ListLimitOrdersResponse` | `{ total, limit, offset, orders: LimitOrderRecord[] }` |
+| `LimitOrderPair` | Active pair with order count |
+| `LimitOrderStats` | Global order statistics |
+| `LimitOrderMutationResponse` | Submission response + `ErrorResponse` |
+
+---
+
+## Helper Functions
+
+Available from `@switch-win/sdk/limit-orders`:
+
+| Function | Description |
+|---|---|
+| `buildLimitOrder(options)` | Build a `LimitOrderParams` object with sensible defaults |
+| `getEIP712SigningParams()` | Get the `{ domain, types }` for `signTypedData()` |
+| `getNetworkEIP712SigningParams(network, contract?)` | Build the correct PulseChain or Robinhood EIP-712 domain |
+| `getLimitOrderNetworkConfig(network)` | Get static chain, router, LO, wrapped-native, and native-flow defaults |
+| `getLimitOrderApprovalTarget(network, feeOnOutput, overrides?)` | Resolve the correct maker approval target |
+| `getApprovalTarget()` | Get approval target for `feeOnOutput: false` orders → SwitchLimitOrder |
+| `getRouterApprovalTarget()` | Get approval target for `feeOnOutput: true` orders → SwitchRouter |
+| `shouldUnwrapOutput(tokenOut)` | Returns `true` if tokenOut is WPLS (should set `unwrapOutput: true`) |
+| `getPLSFlowAddress()` | Get the SwitchPLSFlow contract address for native PLS limit orders |
+| `getNativeFlowAddress(network)` | Get the native PLS/ETH flow address for either chain |
+| `isNativePLS(tokenIn)` | Returns `true` if tokenIn is native PLS (use PLSFlow instead of EIP-712) |
+| `isNativeCurrency(tokenIn)` | Network-neutral native sentinel check |
+| `submitLimitOrder(signedOrder)` | POST a signed order to the Switch backend |
+| `fetchLimitOrders(options?)` | GET orders with optional filters |
+| `fetchLimitOrder(maker, nonce)` | GET a single order by maker + nonce |
+| `fetchLimitOrderPairs()` | GET active pairs with order counts |
+| `fetchLimitOrderConfig({ network })` | GET live deployments and EIP-712 domain |
+| `fetchLimitOrderStats()` | GET global order statistics |
+
+---
+
+## EIP-712 Signing Details
+
+The EIP-712 domain and types must match the on-chain contract exactly:
+
+```ts
+// Domain
+{
+  name: "SwitchLimitOrder",
+  version: "2",
+  chainId: 369,
+  verifyingContract: SWITCH_LIMIT_ORDER  // must match deployed address
+}
+
+// Types
+{
+  LimitOrder: [
+    { name: "maker",        type: "address" },
+    { name: "tokenIn",      type: "address" },
+    { name: "tokenOut",     type: "address" },
+    { name: "amountIn",     type: "uint256" },
+    { name: "minAmountOut", type: "uint256" },
+    { name: "deadline",     type: "uint256" },
+    { name: "nonce",        type: "uint256" },
+    { name: "feeOnOutput",  type: "bool"    },
+    { name: "recipient",    type: "address" },
+    { name: "unwrapOutput", type: "bool"    },
+  ]
+}
+```
+
+These are exported as `LIMIT_ORDER_EIP712_DOMAIN` and `LIMIT_ORDER_EIP712_TYPES` from `@switch-win/sdk/constants`.
+
+---
+
+## On-Chain Revert Errors
+
+| Error | Meaning |
+|---|---|
+| `ExcessiveFee()` | Contract fee exceeds the maximum allowed |
+| `InsufficientOutput()` | Output fell below `minAmountOut` |
+| `InvalidAmount()` | Order amount is zero |
+| `InvalidSignature()` | EIP-712 signature doesn't recover to the maker |
+| `InvalidTokens()` | tokenIn and tokenOut are the same, or zero address |
+| `NonceAlreadyUsed()` | This nonce has already been filled or invalidated |
+| `OrderExpired()` | `block.timestamp > deadline` (and deadline > 0) |
+| `RouteInputExceedsMax()` | Route's total input exceeds the order's `amountIn` |
+| `TransferFailed()` | Token transfer failed (insufficient balance or allowance) |
+
+---
+
+*See also: [README.md](README.md) for swap API docs, constants, and general integration info.*
+
+*Last updated: July 2026*