Orbs Swap
Playground
Search documentation

Advanced Orders · React SDK · Step 1 of 8

Quickstart

Add scheduled or price-based trades to an existing React app. @orbs-network/spot-react supplies state and hooks; you build the controls and connect your wallet and market data. It uses the Orbs Spot protocol.

Follow this guide in order; setup requirements and implementation details are included as you need them. The goal is to create one order, track its fills in history, and cancel an open order. Order creation does not mean the trade has filled.

Implementation Order

Install the packages, implement the provider and wallet adapter, then add the form, review/progress screens, and history. The code is split into named files; later steps supply some of the imports used in earlier ones.

React SDK Examples

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.

Have these app values available before connecting the SDK:

  • A connected wallet account and chain, with RPC reads and wallet transactions on that same chain.
  • Input/output token addresses and decimals, plus the chain’s wrapped-native token.
  • The input-token balance, gas balance, a current quote for the full input amount, and token USD prices.
  • Your existing DEX partner enum, or Partners.External. The provider must initialize successfully for that partner and chain before submission.

The installation commands below list the packages to add. Your existing wallet, token registry, quote, balance, and price sources supply these values.

Mount one SpotProvider around the form, submission dialog, and history consumers. The wallet adapter needs five operations: read allowance, wrap native input, approve tokens, sign an order, and cancel an order. The following steps implement these operations before connecting the form and submission dialog. The SDK supplies provider state and execution orchestration; your app supplies wallet access, data, controls, and presentation.

Install the React SDK

Use your app’s package manager. The SDK is headless: it supplies state and behavior. The full dialog example also imports @orbs-network/swap-ui and @radix-ui/react-dialog; install those if copying it. Use your existing wallet provider or library to implement walletInteractions. The wallet adapter example illustrates this with Viem and Wagmi v3; adapt its calls to your wallet setup.

bash
npm install @orbs-network/spot-react@latest# Optional UI helper:npm install @orbs-network/swap-ui@latest @radix-ui/react-dialog
# or: pnpm add @orbs-network/spot-react@latest# optional: pnpm add @orbs-network/swap-ui@latest @radix-ui/react-dialog
# or: yarn add @orbs-network/spot-react@latest# optional: yarn add @orbs-network/swap-ui@latest @radix-ui/react-dialog

The copied UI also imports lucide-react for icons. Install it if your app does not already use it.

The 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.