React SDK Examples
- React SDK example in spot-ui — form, order submission, history, and cancellation components.
- SpotProvider setup example.
- Orbs Spot example application.
Before You Start
Set minTradeSizeUsd on SpotProvider to any value of **10 or higher**, such as 10, 25, or 50. This is the minimum amount in USD for each individual trade. For example, minTradeSizeUsd: 25 means every trade must be worth at least $25. For TWAP orders, each smaller trade must meet this minimum; it is not the total order amount.
Complete the shared setup requirements. Use the host application's existing wallet connection, token registry, quote, balance, and price sources. Install the packages below and the dependencies imported by the wallet adapter example.
Mount one SpotProvider around the form, submission dialog, and history consumers. Implement all five walletInteractions methods from Configure SpotProvider, then connect the focused hooks and submission dialog. The SDK supplies provider state and execution orchestration; your app supplies wallet access, data, controls, and presentation.
Quickstart
Keep the existing DEX swap form as the source of truth and adapt these values into SpotProvider:
Follow the shared Input Tokens requirements when wiring inputToken and wrappedNativeToken.
| Host value | Expected shape |
|---|---|
| Tokens | Token values with address, symbol, decimals, and optional logoUrl, including a host-supplied wrapped-native token. |
| Typed input | User-facing decimal string such as "1.25". |
| Market quote | Current raw output-token amount for that complete input and token pair, plus loading/no-liquidity state. |
| Balance | Raw input-token integer string, or undefined while disconnected/loading. |
| USD prices | USD value of exactly one whole token. Input price is required but may be undefined while loading. |
| Wallet | Connected chainId, account, and five walletInteractions methods. |
| Product policy | Your DEX’s Partners enum member, or Partners.External, minTradeSizeUsd of at least 10, and priceProtectionPercent. |
Apply the shared Partner Configuration requirements. If the wallet or supported network is unavailable, keep the form visible and replace only the submit area with the DEX's connect-wallet or switch-network control.
Install the React SDK
Use the host's package manager. @orbs-network/swap-ui is an optional helper for review/progress UI and is not required by the headless React SDK.
npm install @orbs-network/spot-react@latest# Optional UI helper:npm install @orbs-network/swap-ui@latest
# or: pnpm add @orbs-network/spot-react@latest# optional: pnpm add @orbs-network/swap-ui@latest
# or: yarn add @orbs-network/spot-react@latest# optional: yarn add @orbs-network/swap-ui@latestThe wallet adapter examples target **Wagmi v3**, including useConnection. Wagmi v2 applications should adapt their existing useAccount-based wallet layer to the same walletInteractions contract. Wagmi is supplied by the host and is not required by the headless SDK.
The host must provide React ^18 || ^19. Zustand is internal; Viem, Wagmi, and Ethers are not package dependencies. The package publishes a "use client" entry for Next.js App Router.