TypeScript SDK Example
Spot App uses the Advanced Orders TypeScript SDK. View the Spot App source on GitHub for an application example.
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.
Before starting, have these app values ready:
- A connected wallet account/provider and RPC client on the same chain.
- Input/output token addresses and decimals, plus the chain’s wrapped-native token.
- The raw 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. Client initialization must succeed for that partner and chain before submission.
Install the SDK using the commands below and reuse your existing wallet provider or library.
Build 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.
Implementation Order
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. Use the same partner and chain for history and cancellation.
The client resolves protocol configuration and prepares the signing payload. Your app sends wrapping/approval transactions, waits for successful receipts, requests the signature, and tracks the accepted order through history. Keep the account, chain, and partner consistent throughout an attempt.
Install the TypeScript SDK
Use the package manager already used by the host application. Do not mix lockfiles.
npm install @orbs-network/spot-ui@latest# or: pnpm add @orbs-network/spot-ui@latest# or: yarn add @orbs-network/spot-ui@latestThe wallet examples illustrate operations with Viem; adapt those calls to your existing wallet setup. The SDK itself 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.
Import createClient and Partners from @orbs-network/spot-ui, then call const client = await createClient(Partners.External, chain.id) inside your async operation. Use the connected wallet's chain and use Partners.External ("external") or the partner provided by the Orbs team. The submission, history, and cancellation examples below include this call directly.
Each createClient() call fetches configuration. You can optionally reuse or cache clients in your app by partner and chain.
Checkpoint: createClient(partner, chainId) resolves for the selected chain and partner. Surface configuration errors before enabling submission.
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 a new 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.