@orbs-network/spot-react 1.1.41 → 1.1.43

package/README.md

@@ -2,383 +2,539 @@
 
 React SDK for building TWAP, Limit, Stop-Loss, and Take-Profit order interfaces on top of the [Orbs Spot protocol](https://www.orbs.com/).
 
+`spot-react` owns Spot order state and exposes it through `SpotProvider` and `useSpot()`. The host DEX remains responsible for swap-form state, wallet access, components, styling, translations, routing, and modal shells.
+
+For the complete integration workflow, see the [Spot React integration skill](https://github.com/orbs-network/spot-ui/tree/master/skills/spot-react-integration) and the [reference implementation](https://github.com/orbs-network/spot-ui/blob/master/apps/web/components/spot/spot-form.tsx).
+
+## Before You Start
+
+Every DEX needs a member of the exported `Partners` enum and a server-side Orbs Spot configuration for its supported chains. The SDK fetches contract and adapter addresses from that configuration. If the DEX is not configured yet, contact [@dTWAPSupportGroup](https://t.me/dTWAPSupportGroup) before integrating.
+
+### RePermit configuration security
+
+The `/config` endpoint is a security boundary. The SDK trusts successful JSON responses without client-side schema or contract-identity validation. It uses `domain.verifyingContract` as the ERC-20 approval spender and the v2 cancellation contract, and uses the returned adapter, reactor, and executor when constructing orders. Deployments must use the trusted Orbs endpoint over TLS, and contract-address changes require explicit approval from the protocol/security owner.
+
+`SpotProvider` starts a shared configuration query as soon as the partner and chain are known. Concurrent consumers reuse the same query, successful responses remain cached for that partner/chain/environment, and failed requests are retried twice. `useRePermitData()` exposes the query state and `refetch`; the standard submit panel exposes the same recovery action as `useSpot().submitOrderButton.retry`.
+
+The completed integration should:
+
+- keep tokens, typed amount, balances, USD prices, and quote state in the DEX's existing swap store or context;
+- provide all five `walletInteractions` methods using the DEX's existing wallet stack;
+- render TWAP, Limit, Stop-Loss, and Take-Profit entry points using DEX-native navigation and components;
+- use `@orbs-network/swap-ui` for the order review/progress flow inside the DEX's modal shell;
+- render order history and cancellation inside `SpotProvider` scope or through a context-preserving portal.
+
 ## Installation
 
+Install the latest Spot packages with the host application's package manager. Do not mix lockfiles.
+
 ```bash
-npm install @orbs-network/spot-react
+npm install @orbs-network/spot-react@latest @orbs-network/swap-ui@latest
+# or: pnpm add @orbs-network/spot-react@latest @orbs-network/swap-ui@latest
+# or: yarn add @orbs-network/spot-react@latest @orbs-network/swap-ui@latest
 ```
 
+If migrating from `@orbs-network/twap-ui`, remove it before installing the packages above.
+
 ### Peer Dependencies
 
-These must be installed in your application:
+The host application must also provide:
 
 ```bash
 npm install @tanstack/react-query bignumber.js react-error-boundary zustand react react-dom
 ```
 
-| Package                | Version    |
-| ---------------------- | ---------- |
-| `@tanstack/react-query`| `^5.90.12` |
-| `bignumber.js`         | `^9.3.1`   |
-| `react-error-boundary` | `^6.0.0`   |
-| `zustand`              | `^5.0.9`   |
-| `react`                | `^18 \|\| ^19` |
-| `react-dom`            | `^18 \|\| ^19` |
+| Package | Version |
+| --- | --- |
+| `@tanstack/react-query` | `^5.90.12` |
+| `bignumber.js` | `^9.3.1` |
+| `react-error-boundary` | `^6.0.0` |
+| `zustand` | `^5.0.9` |
+| `react` | `^18 \|\| ^19` |
+| `react-dom` | `^18 \|\| ^19` |
+
+`viem` is not a dependency. Adapt the wallet library already used by the DEX through `walletInteractions`.
+
+## Integration Model
 
-## Quick Start
+Keep the DEX swap form as the source of truth. Pass the following adapted values directly to `SpotProvider`:
+
+| Value | Expected shape |
+| --- | --- |
+| Selected tokens | `Token` objects with `address`, `symbol`, `decimals`, and `logoUrl` |
+| Typed source amount | User-facing decimal string, for example `"1.25"` |
+| Quote output | Raw destination-token amount for the current typed input |
+| Balances | Raw integer strings |
+| USD prices | USD value of exactly one whole source/destination token |
+| Chain and account | Values from the connected wallet/account state |
+
+If several Spot components need the same DEX-owned values, expose a small DEX adapter context. Do not copy the swap state into a parallel Spot store, prop-drill long value lists, or create a hook whose only purpose is forwarding props to `SpotProvider`.
+
+Memoize objects with `useMemo` and functions with `useCallback`. In particular, keep stable identities for tokens, `marketReferencePrice`, `walletInteractions`, and `callbacks`.
+
+## Provider Setup
 
 ```tsx
+import { useMemo } from "react";
 import {
-  SpotProvider,
-  useSpot,
   Module,
   Partners,
+  SpotProvider,
+  type Callbacks,
+  type MarketReferencePrice,
+  type Token,
   type WalletInteractions,
 } from "@orbs-network/spot-react";
 
-function App() {
+function SpotOrderForm({ module }: { module: Module }) {
+  // Read these from the DEX's existing swap and wallet state.
+  const {
+    account,
+    chainId,
+    inputCurrency,
+    outputCurrency,
+    inputBalance,
+    outputBalance,
+    typedInputAmount,
+    quotedInputAmount,
+    quoteOutputRaw,
+    isQuoteLoading,
+    inputUsdPrice,
+    outputUsdPrice,
+    refetchBalances,
+    dexWallet,
+  } = useDexSpotAdapter();
+
+  const srcToken = useMemo<Token | undefined>(() => {
+    if (!inputCurrency) return undefined;
+    return {
+      address: inputCurrency.address,
+      symbol: inputCurrency.symbol,
+      decimals: inputCurrency.decimals,
+      logoUrl: inputCurrency.logoUrl,
+    };
+  }, [inputCurrency]);
+
+  const dstToken = useMemo<Token | undefined>(() => {
+    if (!outputCurrency) return undefined;
+    return {
+      address: outputCurrency.address,
+      symbol: outputCurrency.symbol,
+      decimals: outputCurrency.decimals,
+      logoUrl: outputCurrency.logoUrl,
+    };
+  }, [outputCurrency]);
+
+  const marketReferencePrice = useMemo<MarketReferencePrice>(() => {
+    const shouldQuote = Boolean(
+      typedInputAmount && inputCurrency && outputCurrency,
+    );
+    const isStale = shouldQuote && typedInputAmount !== quotedInputAmount;
+    const value = !shouldQuote || isStale ? undefined : quoteOutputRaw;
+    const isLoading = shouldQuote && (isStale || isQuoteLoading);
+
+    return {
+      value,
+      isLoading,
+      noLiquidity: shouldQuote && !isLoading && !value,
+    };
+  }, [
+    inputCurrency,
+    isQuoteLoading,
+    outputCurrency,
+    quoteOutputRaw,
+    quotedInputAmount,
+    typedInputAmount,
+  ]);
+
+  const walletInteractions = useMemo<WalletInteractions>(
+    () => createWalletInteractions(dexWallet),
+    [dexWallet],
+  );
+
+  const callbacks = useMemo<Callbacks>(
+    () => ({
+      onWrapSuccess: () => refetchBalances(),
+      onOrderCreated: () => refetchBalances(),
+      onOrderFilled: () => refetchBalances(),
+      onOrdersProgressUpdate: () => refetchBalances(),
+      onCancelOrderSuccess: () => refetchBalances(),
+    }),
+    [refetchBalances],
+  );
+
   return (
     <SpotProvider
-      chainId={137}                              // Polygon
-      walletInteractions={walletInteractions}    // Wallet interaction handlers
-      account={walletAddress}                    // Connected wallet address
-      appId="my-dex"                             // Optional analytics app ID
-      partner={Partners.Quick}                   // DEX partner
-      module={Module.TWAP}                       // Order type
-      typedInputAmount={inputAmount}             // User-typed amount (string)
-      priceProtection={0.5}                      // Slippage tolerance %
-      minChunkSizeUsd={5}                        // Min chunk size in USD
-      srcToken={srcToken}                        // { address, symbol, decimals, logoUrl }
+      partner={Partners.Quick}
+      module={module}
+      typedInputAmount={typedInputAmount}
+      priceProtection={3}
+      minChunkSizeUsd={5}
+      marketReferencePrice={marketReferencePrice}
+      walletInteractions={walletInteractions}
+      chainId={chainId}
+      account={account}
+      srcToken={srcToken}
       dstToken={dstToken}
-      srcBalance={srcBalanceWei}                 // Balance in wei (string)
-      dstBalance={dstBalanceWei}
-      srcUsd1Token={srcUsdPrice}                 // USD price of 1 token (string)
-      dstUsd1Token={dstUsdPrice}
-      marketReferencePrice={marketPrice}         // { value?: string, isLoading?: boolean }
-      callbacks={callbacks}                      // Lifecycle event handlers
-      fees={0.25}                                // Fee percentage
+      srcBalance={inputBalance?.toString()}
+      dstBalance={outputBalance?.toString()}
+      srcUsd1Token={inputUsdPrice}
+      dstUsd1Token={outputUsdPrice}
+      callbacks={callbacks}
+      appId="my-dex"
+      fees={0.25}
     >
-      <SwapForm />
+      <SpotFormContent />
     </SpotProvider>
   );
 }
 ```
 
-## WalletInteractions
-
-The host app provides wallet interaction handlers via the `walletInteractions` prop. This keeps spot-react wallet-agnostic — it works with viem, ethers, web3.js, or any wallet library.
-
-```tsx
-const walletInteractions: WalletInteractions = {
-  // Wrap native token (e.g. ETH -> WETH). Wait for receipt, return tx hash.
-  wrapNativeToken: async (amountWei) => { ... },
-
-  // Approve ERC-20 token spending. Wait for receipt, return tx hash.
-  approveToken: async ({ token, amount, spender }) => { ... },
+`marketReferencePrice.value` is the DEX quote's raw destination amount for the current `typedInputAmount`, not a standalone per-token price. If the quote belongs to an older input or token pair, omit `value` and report `isLoading: true` until a current quote arrives.
 
-  // Cancel an order on-chain. Wait for receipt, return tx hash.
-  cancelOrder: async ({ order, contractAddress, args }) => { ... },
+Use the connected wallet chain as the UI source of truth. The provider falls back internally to a supported partner chain for configuration lookups when `chainId` is absent or unsupported, so the DEX submit area must still show connect-wallet or switch-network controls and block submission.
 
-  // Sign EIP-712 typed data for order creation. Return signature hex.
-  signOrder: async ({ domain, types, primaryType, message, account }) => { ... },
+### SpotProvider Props
 
-  // Read ERC-20 allowance. Return allowance as string.
-  getAllowance: async ({ tokenAddress, spenderAddress }) => { ... },
-};
-```
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `partner` | `Partners` | Yes | DEX partner enum |
+| `module` | `Module` | Yes | `TWAP`, `LIMIT`, `STOP_LOSS`, or `TAKE_PROFIT` |
+| `typedInputAmount` | `string` | Yes | User-facing source amount from DEX state |
+| `priceProtection` | `number` | Yes | Price Protection percentage; this is not swap slippage |
+| `minChunkSizeUsd` | `number` | Yes | Minimum trade chunk size in USD |
+| `marketReferencePrice` | `MarketReferencePrice` | Yes | `{ value?, isLoading?, noLiquidity? }` for the current DEX quote |
+| `walletInteractions` | `WalletInteractions` | Yes | Five wallet methods implemented by the DEX |
+| `chainId` | `number` | No | Connected wallet chain ID |
+| `account` | `string` | No | Connected wallet address |
+| `appId` | `string` | No | Analytics app ID |
+| `srcToken` | `Token` | No | Source token metadata |
+| `dstToken` | `Token` | No | Destination token metadata |
+| `srcBalance` | `string` | No | Raw source-token balance |
+| `dstBalance` | `string` | No | Raw destination-token balance |
+| `srcUsd1Token` | `string` | No | USD value of one whole source token |
+| `dstUsd1Token` | `string` | No | USD value of one whole destination token |
+| `enableQueryParams` | `boolean` | No | Sync supported form state to URL query parameters |
+| `callbacks` | `Callbacks` | No | Lifecycle and field-change callbacks |
+| `fees` | `number` | No | Fee percentage, for example `0.25` |
+| `isDev` | `boolean` | No | Use development services/configuration |
+| `supportLegacyOrders` | `boolean` | No | Include supported legacy v1 orders in history |
+
+Although balances and USD prices are optional in the TypeScript type, production integrations should pass them so validation, loading states, minimum trade size, and review details are correct.
 
-Each write method (`wrapNativeToken`, `approveToken`, `cancelOrder`) should wait for tx confirmation and throw if the transaction reverts.
+## WalletInteractions
 
-### Example with viem/wagmi
+The DEX must implement all five methods. Write methods must wait for the transaction receipt, throw when the transaction reverts, and then return the transaction hash.
 
 ```tsx
-import { erc20Abi } from "viem";
-
 const walletInteractions: WalletInteractions = {
   wrapNativeToken: async (amountWei) => {
-    const hash = await walletClient.writeContract({
-      abi: [{ name: "deposit", type: "function", stateMutability: "payable", inputs: [], outputs: [] }],
-      functionName: "deposit",
-      address: wTokenAddress,
-      args: [],
-      value: BigInt(amountWei),
-      chain: walletClient.chain,
-      account: walletClient.account!,
-    });
-    await publicClient.waitForTransactionReceipt({ hash, confirmations: 2 });
-    return hash;
+    const txHash = await dexWallet.wrapNativeToken(amountWei);
+    await dexWallet.waitForReceipt(txHash);
+    return txHash;
   },
-  approveToken: async ({ token, spender }) => {
-    const maxUint256 = BigInt("0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff");
-    const hash = await walletClient.writeContract({
-      abi: erc20Abi,
-      functionName: "approve",
-      address: token as `0x${string}`,
-      args: [spender as `0x${string}`, maxUint256],
-      chain: walletClient.chain,
-      account: walletClient.account!,
+
+  approveToken: async ({ tokenAddress, amount, spenderAddress }) => {
+    const txHash = await dexWallet.approveToken({
+      tokenAddress,
+      amount,
+      spenderAddress,
     });
-    await publicClient.waitForTransactionReceipt({ hash, confirmations: 2 });
-    return hash;
+    await dexWallet.waitForReceipt(txHash);
+    return txHash;
   },
-  cancelOrder: async ({ order, contractAddress, args }) => {
-    const hash = await walletClient.writeContract({
-      abi: cancelAbi, // TWAP_ABI for v1, REPERMIT_ABI for v2
+
+  cancelOrder: async ({ order, contractAddress, args, abi }) => {
+    const txHash = await dexWallet.writeContract({
+      address: contractAddress,
+      abi,
       functionName: "cancel",
-      address: contractAddress as `0x${string}`,
-      args: args as any,
-      chain: walletClient.chain,
-      account: walletClient.account!,
+      args,
     });
-    await publicClient.waitForTransactionReceipt({ hash, confirmations: 2 });
-    return hash;
-  },
-  signOrder: async ({ domain, types, primaryType, message, account }) => {
-    return walletClient.signTypedData({ domain, types, primaryType, message, account });
-  },
-  getAllowance: async ({ tokenAddress, spenderAddress }) => {
-    const result = await publicClient.readContract({
-      address: tokenAddress as `0x${string}`,
-      abi: erc20Abi,
-      functionName: "allowance",
-      args: [walletClient.account!.address, spenderAddress as `0x${string}`],
-    });
-    return String(result);
+    await dexWallet.waitForReceipt(txHash);
+    return txHash;
   },
+
+  signOrder: ({ domain, types, primaryType, message, account }) =>
+    dexWallet.signTypedData({ domain, types, primaryType, message, account }),
+
+  getAllowance: ({ tokenAddress, spenderAddress }) =>
+    dexWallet.getAllowance({ tokenAddress, spenderAddress }),
 };
 ```
 
-## SpotProvider Props
-
-| Prop | Type | Required | Description |
-| --- | --- | --- | --- |
-| `partner` | `Partners` | Yes | DEX partner enum |
-| `module` | `Module` | Yes | `TWAP`, `LIMIT`, `STOP_LOSS`, or `TAKE_PROFIT` |
-| `typedInputAmount` | `string` | Yes | User-typed source amount |
-| `priceProtection` | `number` | Yes | Slippage tolerance percentage |
-| `minChunkSizeUsd` | `number` | Yes | Minimum trade chunk size in USD |
-| `marketReferencePrice` | `MarketReferencePrice` | Yes | `{ value?: string, isLoading?: boolean, noLiquidity?: boolean }` |
-| `walletInteractions` | `WalletInteractions` | Yes | Wallet interaction handlers |
-| `chainId` | `number` | No | Connected chain ID |
-| `account` | `string` | No | Connected wallet address |
-| `appId` | `string` | No | Analytics app ID |
-| `srcToken` | `Token` | No | `{ address, symbol, decimals, logoUrl }` |
-| `dstToken` | `Token` | No | `{ address, symbol, decimals, logoUrl }` |
-| `srcBalance` | `string` | No | Source balance in wei |
-| `dstBalance` | `string` | No | Destination balance in wei |
-| `srcUsd1Token` | `string` | No | USD price of 1 source token |
-| `dstUsd1Token` | `string` | No | USD price of 1 destination token |
-| `callbacks` | `Callbacks` | No | Lifecycle event handlers |
-| `fees` | `number` | No | Fee percentage (e.g. 0.25) |
-| `isDev` | `boolean` | No | Enable dev mode |
-| `overrides` | `Overrides` | No | Initial state overrides |
+| Method | Contract |
+| --- | --- |
+| `wrapNativeToken(amountWei)` | Wrap native currency, wait for confirmation, return tx hash |
+| `approveToken({ tokenAddress, amount, spenderAddress })` | Approve the requested spender, wait for confirmation, return tx hash |
+| `cancelOrder({ order, contractAddress, args, abi })` | Call `cancel` with the supplied ABI and args, wait for confirmation, return tx hash |
+| `signOrder({ domain, types, primaryType, message, account })` | Sign the supplied EIP-712 data and return signature hex |
+| `getAllowance({ tokenAddress, spenderAddress })` | Return the connected account's raw allowance as a string |
 
-## useSpot() Hook
+## Building the Form with useSpot()
 
-The main hook returns all data and controls for building the UI:
+Every component rendered under `SpotProvider` can call `useSpot()`:
 
 ```tsx
 const spot = useSpot();
 ```
 
-### Returned panels
-
-| Panel | Description |
+| Value | Key returns |
 | --- | --- |
-| `spot.dstTokenPanel` | `{ value, isLoading }` — estimated output amount |
-| `spot.tradesAmountPanel` | Total trades input, per-trade amounts, validation |
-| `spot.durationPanel` | Order expiry duration input |
-| `spot.fillDelayPanel` | Trade interval input |
-| `spot.limitPricePanel` | Limit price input with percentage, toggle, reset |
-| `spot.triggerPricePanel` | Trigger price for stop-loss / take-profit |
-| `spot.pricePanel` | Market price display, inversion toggle |
-| `spot.disclaimerPanel` | Disclaimer key string (or `undefined`) |
-| `spot.inputError` | Validation error `{ type, args }` (or `undefined`) |
-| `spot.submitOrderButton` | `{ disabled, loading }` |
-| `spot.orderExecutionPanel` | Full submission lifecycle (see below) |
-| `spot.orderHistoryPanel` | `{ orders: { all: Order[] } }` |
-| `spot.derivedFormData` | Computed values: amounts, prices, deadline, fees |
-| `spot.supportedChains` | Partner's supported chain IDs |
-| `spot.module` | Current `Module` enum |
-
-### Order Execution Panel
+| `dstTokenPanel` | `value`, `valueWei`, `isLoading`, `usd` |
+| `tradesAmountPanel` | `totalTrades`, `maxTrades`, `onChange`, `error`, per-trade amounts, source/destination tokens |
+| `durationPanel` | `duration`, input/unit callbacks, `milliseconds`, `error` |
+| `fillDelayPanel` | `fillDelay`, input/unit callbacks, `milliseconds`, `error` |
+| `limitPricePanel` | Raw/UI price, percentage, toggle, input/reset callbacks, tokens, USD, loading/error state |
+| `triggerPricePanel` | Raw/UI trigger price, percentage, input/reset callbacks, tokens, per-chunk amounts, USD, error state |
+| `pricePanel` | Inversion state/callback, source/destination tokens, market-price state |
+| `disclaimerPanel` | Disclaimer translation key or `undefined` |
+| `inputError` | `{ type, args }` or `undefined` |
+| `submitOrderButton` | `disabled`, `loading`, configuration `error`, and `retry` |
+| `orderExecutionPanel` | Submission, status, steps, errors, resets, resolved tokens, and tx hashes |
+| `orderHistoryPanel` | Filtered order lists, loading state, and `refetchOrders` |
+| `derivedFormData` | Review amounts, prices, timing, fees, order type, spender, and RePermit data |
+| `supportedChains` | Supported chain IDs for the selected partner |
+| `module` | Current `Module` |
+| `refetchUntilStatusSynced` | Mutation used to reconcile cancellation status |
+
+Child components should call `useSpot()` themselves instead of receiving hook-returned panels through intermediate props.
+
+When `submitOrderButton.error` is set, render a translated retry label and call `submitOrderButton.retry()` instead of opening the review modal. Keep the button disabled while `loading` is true. Legacy v1 order history does not depend on RePermit configuration; v2 history, approvals, v2 cancellation, and submission resume after a successful retry.
+
+### Panel Visibility
+
+| Panel | TWAP | LIMIT | STOP_LOSS | TAKE_PROFIT |
+| --- | --- | --- | --- | --- |
+| Trades amount | Yes | — | — | — |
+| Fill delay | Yes | — | — | — |
+| Duration | — | Yes | Yes | Yes |
+| Limit price | Yes, optional | Always on | Optional | Optional |
+| Trigger price | — | — | Yes | Yes |
+
+Use `TimeUnit.Minutes`, `TimeUnit.Hours`, and `TimeUnit.Days` for duration and fill-delay controls. Resolve error and disclaimer keys through the DEX's i18n system.
+
+### Display Amounts
+
+Raw fields such as `dstTokenPanel.valueWei`, `tradesAmountPanel.amountPerTrade`, `derivedFormData.feesAmount`, and history fill amounts are integer strings. Convert them into the DEX's native amount type before display when possible:
 
 ```tsx
-const {
-  onSubmit,              // Trigger order creation
-  status,                // SwapStatus: LOADING | SUCCESS | FAILED
-  step,                  // Current step: WRAP | APPROVE | CREATE
-  stepIndex,             // Current step index (0-based)
-  totalSteps,            // Total number of steps
-  parsedError,           // { code, message } on failure
-  onSwapSuccess,         // Call when user acknowledges success
-  confirmButtonLoading,  // Loading state for confirm button
-  srcToken,              // Resolved source token
-  dstToken,              // Resolved destination token
-  wrapTxHash,            // Wrap transaction hash
-  approveTxHash,         // Approve transaction hash
-} = useSpot().orderExecutionPanel;
+const amount = CurrencyAmount.fromRawAmount(
+  inputCurrency,
+  spot.tradesAmountPanel.amountPerTrade,
+);
+
+return `${amount.toSignificant()} ${inputCurrency.symbol}`;
 ```
 
-### Cancel Order
+Use `*UI` fields for editable text inputs or when the DEX has no amount object. Do not format raw integer strings directly for user display.
+
+## Submit and Progress Modal
+
+Use `useSpot().orderExecutionPanel` for execution state, `derivedFormData` for review details, and `@orbs-network/swap-ui`'s `SwapFlow` for the creation/progress UI.
 
 ```tsx
-import { useCancelOrder } from "@orbs-network/spot-react";
+import { SwapFlow } from "@orbs-network/swap-ui";
+import { useSpot } from "@orbs-network/spot-react";
+
+function SpotOrderFlow() {
+  const {
+    status,
+    parsedError,
+    srcToken,
+    dstToken,
+    stepIndex,
+    totalSteps,
+  } = useSpot().orderExecutionPanel;
+  const form = useSpot().derivedFormData;
+
+  return (
+    <SwapFlow
+      inAmount={form.srcAmountUI}
+      outAmount={form.dstAmountUI}
+      inToken={{ symbol: srcToken?.symbol, logoUrl: srcToken?.logoUrl }}
+      outToken={{ symbol: dstToken?.symbol, logoUrl: dstToken?.logoUrl }}
+      swapStatus={status}
+      currentStepIndex={stepIndex}
+      totalSteps={totalSteps}
+      components={{
+        Main: <SwapFlow.Main inUsd={form.srcAmountUsd} outUsd={form.dstAmountUsd} />,
+        Success: <SwapFlow.Success title="Order created" />,
+        Failed: <SwapFlow.Failed error={parsedError?.message} />,
+      }}
+    />
+  );
+}
+```
 
-// Inside a component rendered within SpotProvider:
-const { cancelOrder, isLoading, isSuccess, isError, error, txHash } = useCancelOrder(order);
+Wrap `SwapFlow` in the DEX's modal shell and skin it with DEX colors, surfaces, typography, token logos, and loaders. Once `orderExecutionPanel.status` is set, hide the review details, confirm button, duplicate title, and secondary footer actions so the progress/success/failure content owns the modal.
 
-// Cancel the order
-await cancelOrder();
+### Execution State and Reset
 
-// Or use getCancelStatus for any order by ID:
-const { getCancelStatus } = useCancelOrder();
-const status = getCancelStatus(orderId); // { status, txHash?, error? } | undefined
+`orderExecutionPanel` includes:
+
+- `onSubmit`, `status`, `isLoading`, `isSuccess`, `isFailed`, and `confirmButtonLoading`;
+- `step`, `stepIndex`, `totalSteps`, and `pendingSteps`;
+- `parsedError`, `error`, `srcToken`, `dstToken`, `wrapTxHash`, and `approveTxHash`;
+- `resetCurrentSwap()` and `resetState()`.
+
+`spot-react` does not clear the DEX input. Do that only when a successful modal closes:
+
+```tsx
+const { status, isSuccess, resetCurrentSwap, resetState } =
+  useSpot().orderExecutionPanel;
+
+const onClose = useCallback(() => {
+  setIsModalOpen(false);
+
+  if (isSuccess) {
+    setInputAmount("");
+    setTimeout(resetState, 500);
+  } else if (status) {
+    setTimeout(resetCurrentSwap, 500);
+  }
+}, [isSuccess, resetCurrentSwap, resetState, setInputAmount, status]);
 ```
 
+Failed or rejected submissions should keep the user's input. The short delay lets the close animation finish before state resets.
+
 ## Callbacks
 
-Pass lifecycle callbacks to `SpotProvider` for wallet notifications:
+Callbacks cover wallet notifications, analytics, field synchronization, and balance refresh:
 
 ```tsx
 const callbacks: Callbacks = {
-  // Token wrapping
   onWrapRequest: () => {},
   onWrapSuccess: ({ txHash, explorerUrl, amount }) => {},
-
-  // Token approval
   onApproveRequest: () => {},
   onApproveSuccess: ({ txHash, explorerUrl, token, amount }) => {},
-
-  // Order lifecycle
   onSignOrderRequest: () => {},
   onSignOrderSuccess: (signature) => {},
   onSignOrderError: (error) => {},
   onOrderCreated: (order) => {},
   onOrderFilled: (order) => {},
-
-  // Errors
+  onOrdersProgressUpdate: (orders) => {},
   onSubmitOrderFailed: ({ code, message }) => {},
   onSubmitOrderRejected: () => {},
-
-  // Order cancellation
   onCancelOrderRequest: (order) => {},
   onCancelOrderSuccess: ({ order, txHash, explorerUrl }) => {},
   onCancelOrderFailed: (error) => {},
-
-  // Progress (good place to refetch balances)
-  onOrdersProgressUpdate: (orders) => {},
-
-  // Clipboard
   onCopy: () => {},
-
-  // State change callbacks
   onLimitPriceChange: (price) => {},
+  onLimitPricePercentChange: (percent) => {},
   onTriggerPriceChange: (price) => {},
+  onTriggerPricePercentChange: (percent) => {},
   onDurationChange: (duration) => {},
   onFillDelayChange: (fillDelay) => {},
   onChunksChange: (chunks) => {},
 };
 ```
 
-## Translations / i18n
-
-The SDK returns string keys for user-facing messages. You should resolve these through your own i18n system.
+Refetch balances in `onWrapSuccess`, `onOrderCreated`, `onOrderFilled`, `onOrdersProgressUpdate`, and `onCancelOrderSuccess`. Avoid an `onOrderCreated` toast unless the host DEX specifically wants one; the submit modal already shows creation success.
 
-### Disclaimer keys
+## Cancellation and Order History
 
-`useSpot().disclaimerPanel` returns one of:
-- `"limitOrderDisclaimer"` — shown for limit and TWAP-limit orders
-- `"marketOrderDisclaimer"` — shown for market orders
-- `"triggerMarketPriceDisclaimer"` — shown for stop-loss at market price
+Use the exported cancellation hook inside `SpotProvider`:
 
-### Input error keys
+```tsx
+import { OrderStatus, useCancelOrder } from "@orbs-network/spot-react";
 
-`useSpot().inputError` returns `{ type, args }` where `type` is a key like:
-- `"enterAmount"`, `"insufficientFunds"`, `"emptyLimitPrice"`, `"emptyTriggerPrice"`
-- `"maxChunksError"` (args: `{ maxChunks }`)
-- `"minChunksError"` (args: `{ minChunks }`)
-- `"minTradeSizeError"` (args: `{ minTradeSize }`)
-- `"minDurationError"` / `"maxDurationError"` (args: `{ duration }`)
-- `"minFillDelayError"` / `"maxFillDelayError"` (args: `{ fillDelay }`)
-- `"noLiquidity"`
+function CancelButton({ order }) {
+  const { cancelOrder, disabled, isLoading, isSuccess, isError, error, txHash } =
+    useCancelOrder(order);
 
-## Order Types
+  if (order.status !== OrderStatus.Open) return null;
 
-| Module | Description |
-| --- | --- |
-| `Module.TWAP` | Time-Weighted Average Price — splits order into multiple trades over time |
-| `Module.LIMIT` | Limit order — executes at specified price or better |
-| `Module.STOP_LOSS` | Stop-loss — triggers when price drops to threshold |
-| `Module.TAKE_PROFIT` | Take-profit — triggers when price rises to threshold |
+  return (
+    <button onClick={cancelOrder} disabled={disabled || isLoading}>
+      {isLoading ? "Cancelling..." : "Cancel"}
+    </button>
+  );
+}
+```
 
-### Panel visibility by module
+For v2 orders, `disabled` remains true while RePermit configuration is loading or unavailable. Legacy v1 history and cancellation do not require that configuration. V2 history is added after configuration succeeds because its request needs the returned exchange adapter.
 
-| Panel | TWAP | LIMIT | STOP_LOSS | TAKE_PROFIT |
-| --- | --- | --- | --- | --- |
-| Trades amount | Yes | — | — | — |
-| Fill delay | Yes | — | — | — |
-| Duration | — | Yes | Yes | Yes |
-| Limit price | Yes | Yes | Yes | Yes |
-| Trigger price | — | — | Yes | Yes |
-
-## Helper Hooks
+Order history is available from `useSpot().orderHistoryPanel`:
 
 ```tsx
-import {
-  useExplorerLink,  // (txHash?: string) => explorer URL
-  useNetwork,       // () => network info (name, native, wToken, explorer)
-  useAmountUi,      // (amount: string, decimals: number) => formatted amount
-} from "@orbs-network/spot-react";
+const { orders, isLoading, isRefetching, refetchOrders } =
+  useSpot().orderHistoryPanel;
+
+// orders.all, orders.open, orders.completed, orders.cancelled, orders.expired
 ```
 
-## Utility Functions
+Use `useDerivedHistoryOrder(order, srcToken?, dstToken?)` for display fields. For large histories, use the virtualization library already present in the DEX for both the orders and fills lists. Store the selected order ID, then look up the current order from `orders.all`; do not store a stale copy of the order object.
 
-```tsx
-import {
-  getPartners,           // () => all registered partners
-  getPartnerChains,      // (partner) => supported chain IDs
-  getNetwork,            // (chainId) => network config
-  isNativeAddress,       // (address) => boolean
-  eqIgnoreCase,          // (a, b) => case-insensitive address comparison
-  getConfig,             // (partner, chainId) => SpotConfig
-} from "@orbs-network/spot-react";
-```
+Keep history, details, and modal portals under `SpotProvider` context. Details should include execution summary, order info, fills, explorer/copy actions, and cancellation for open orders.
+
+## Translations
+
+The SDK returns keys rather than final user-facing strings.
+
+Disclaimer keys are:
 
-## Overrides
+- `limitOrderDisclaimer`
+- `marketOrderDisclaimer`
+- `triggerMarketPriceDisclaimer`
 
-For initial form state, pass `overrides` to `SpotProvider`:
+Input errors have the shape `{ type, args }`. Resolve `type` through the DEX's i18n system and interpolate `args`, including values such as `maxChunks`, `minChunks`, `minTradeSize`, `duration`, and `fillDelay`. Current duration and fill-delay arguments are human-readable; custom or older integrations should convert raw milliseconds before display.
+
+## Helper and Advanced APIs
 
 ```tsx
-<SpotProvider
-  overrides={{
-    state: {
-      isMarketOrder: false,
-      chunks: 10,
-      limitPrice: "1.5",
-      triggerPrice: "1.2",
-      fillDelay: { value: 5, unit: TimeUnit.Minutes },
-      duration: { value: 1, unit: TimeUnit.Days },
-    },
-  }}
-  // ...other props
-/>
+import {
+  useAmountUi,      // (decimals?, rawAmount?) => formatted amount
+  useExplorerLink,  // (txHash?) => explorer URL
+  useNetwork,       // () => current network metadata
+  useRePermitData,  // () => { data, error, isLoading, refetch }
+  useSignOrder,     // low-level signing hook
+  useSubmitOrder,   // low-level submission mutation
+  useSwapExecution, // low-level execution state
+} from "@orbs-network/spot-react";
 ```
 
-## Constants
+Normal integrations should submit through `useSpot().orderExecutionPanel`. Use the low-level hooks only when deliberately replacing the built-in execution flow. `useRePermitData()` must be called under `SpotProvider`; most integrations should use the configuration state already exposed by `useSpot().submitOrderButton`.
+
+Public utilities and constants include:
 
 ```tsx
 import {
-  SPOT_VERSION,       // SDK version identifier
-  DISCLAIMER_URL,     // Orbs disclaimer page
-  ORBS_TWAP_FAQ_URL,  // TWAP FAQ page
-  ORBS_SLTP_FAQ_URL,  // Stop-Loss/Take-Profit FAQ page
-  ORBS_LOGO,          // Orbs logo URL
-  ORBS_WEBSITE_URL,   // Orbs website
-  networks,           // All supported network configs
+  getMinChunkSizeUsd,
+  getNetwork,
+  getOrderExecutionRate,
+  getOrderFillDelayMillis,
+  getOrderLimitPriceRate,
+  getPartnerChains,
+  getPartners,
+  getTriggerPriceRate,
+  eqIgnoreCase,
+  isNativeAddress,
+  DISCLAIMER_URL,
+  ORBS_TWAP_FAQ_URL,
+  ORBS_SLTP_FAQ_URL,
+  ORBS_LOGO,
+  ORBS_WEBSITE_URL,
+  SPOT_VERSION,
+  networks,
 } from "@orbs-network/spot-react";
 ```
 
+Always import from `@orbs-network/spot-react`. Do not import from `dist/*` or package-internal source paths, and verify public exports when upgrading.
+
+## Integration Checklist
+
+- Use the DEX's existing tokens, inputs, selectors, components, styling, wallet controls, and routing.
+- Keep chain switching out of the Spot token selector; use the DEX network control.
+- Keep the form visible while disconnected; replace only the submit area with connect/switch controls.
+- Persist Price Protection separately from swap slippage and hide the DEX slippage setting while Spot is active.
+- Use `@orbs-network/swap-ui` for order creation/progress content.
+- Convert raw amounts into the DEX's amount type before display.
+- Use callbacks for balance refetch and reset the input only after success.
+- Put Spot tabs beside the Swap tab using the DEX's navigation pattern.
+- Split production integrations into focused `components`, `hooks`, `context`, and `utils` files.
+- Do not add another error boundary around Spot; `SpotProvider` already includes one.
+
 ## License
 
 MIT