Advanced Orders · TypeScript SDK — Spot Integration Docs

Before You Start

Pass minTradeSizeUsd to calculateOrderForm() with 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. Install the SDK below and Viem for the wallet example. Supply the connected account/provider, active-chain RPC, token metadata, raw balance, and a current quote for the full input amount.

Build one partner/chain client cache, one calculateOrderForm() adapter, one guarded confirmation handler, and a history/cancellation view. The SDK prepares and submits protocol data; the host owns application state, current market data, wallet transactions, and polling.

Quickstart

Install @orbs-network/spot-ui, create one client for your existing DEX partner (or Partners.External) and connected chain, derive the form from current DEX inputs, then prepare, sign, and submit one immutable attempt. Reuse the same client for history and cancellation.

See Integration Lifecycle for the host and SDK responsibilities.

Initialize the client using the shared Partner Configuration requirements.

Install the TypeScript SDK

Use the package manager already used by the host application. Do not mix lockfiles.

1npm install @orbs-network/spot-ui@latest2# or: pnpm add @orbs-network/spot-ui@latest3# or: yarn add @orbs-network/spot-ui@latest

The package has no React or wallet-library dependency. Import only from the package root; do not use dist/* or internal source paths.

Initialize the Client

createClient(partner, chainId) validates support, fetches and validates the current RePermit configuration, and returns a new frozen client bound to that exact partner and chain.

1import { createClient, Partners } from "@orbs-network/spot-ui";2
3export async function getSpotClient(chainId: number) {4  const partner = Partners.External;5
6  return createClient(partner, chainId);7}

Every call fetches configuration and there is no SDK-global cache. Reuse an in-flight promise or resolved client in the host data layer, keyed by partner and chain. Remove rejected promises so an explicit retry can initialize again, and invalidate the resource when either key changes.

The client exposes these read-only configuration values and operations:

Member	What it represents
`client.partner`	The `Partners` value used for configuration and configured history requests.
`client.chainId`	The EVM chain captured by this client. Create or retrieve another keyed client when the wallet chain changes.
`client.rePermitData`	The validated, trusted RePermit configuration, including the EIP-712 domain/types, base order, and protocol addresses. Treat it as read-only.
`client.spenderAddress`	The RePermit verifying contract. Use it for ERC-20 allowance and approval; it is also the v2 cancellation contract.
`client.exchangeAddress`	The configured exchange adapter used for order execution; it is not a v2 history query parameter.
`client.prepareOrder(params)`	Converts a submittable form snapshot into the exact protocol order, signing request, approval request, and fresh timestamps. It performs no wallet or network operation.
`preparedOrder.signingRequest`	Contains `signerAddress` and `typedData` for the host wallet to sign. The client does not expose a `signOrder()` method.
`client.submitOrder(preparedOrder.order, signature)`	Submits the exact signed protocol `order` and signature once and returns a normalized `Order`.
`client.getAccountOrders({ account, ...options })`	Loads normalized history with this client's partner and chain. Options include `signal` and `legacyOrders`; `page` and `limit` apply only to legacy v1 history.
`client.getCancelOrderRequest(order)`	Builds the correct v1 or v2 contract address, ABI, and arguments. The host wallet sends and confirms the transaction.

Do not fetch or reconstruct RePermit configuration in host code. The client rejects chain mismatches and malformed or zero critical addresses before exposing approval, signing, history, or cancellation values.