Swap · TypeScript SDK — Spot Integration Docs

Before You Start

Complete the shared setup requirements. For this path, install the packages below and supply a connected wallet provider, active-chain RPC, token registry, and a quote-refresh callback from your host app.

Your implementation has three parts: one reusable SDK client per active chain, a quote adapter driven by the current form, and a confirmation handler that calls the complete Submit Swap example. The host owns route comparison, wallet operations, and successful receipt confirmation.

Install the SDK and Viem:

1npm install @orbs-network/liquidity-hub-sdk@latest viem

Create one Liquidity Hub client for the active chain and reuse it for quote and swap operations. Create a new client when the active chain changes; do not create a new client for every quote.

1import { createClient } from "@orbs-network/liquidity-hub-sdk";2
3const partner = "external";4
5function createLiquidityHubClient(chainId) {6  return createClient({7    chainId,8    partner,9  });10}

createClient() returns a LiquidityHubClient synchronously. It rejects an invalid chain ID or empty partner, normalizes the partner to lowercase, and keeps one session scope for that client.

Use the partner name supplied by Orbs. If Orbs has not supplied one, use the lowercase string "external".

The public client surface is intentionally small:

Member	Purpose
`chainId`	Read-only chain bound to this client.
`partner`	Read-only normalized partner identifier.
`getQuote(args)`	Request and validate a wallet-bound quote.
`swap(quote, signature, dexRouterData?)`	Submit a fresh signed quote and resolve with its transaction hash.

The SDK selects the standard chain endpoint when apiUrl is omitted. For a same-origin development proxy, pass a relative base path such as apiUrl: "/api/liquidity-hub"; it applies to quote, submission, and status requests. Keep any proxy development-only, use fixed upstream hosts, and allow only Liquidity Hub routes.

The Submit Swap reference initializes Viem publicClient and walletClient instances in the same file. They handle token reads, wallet transactions, EIP-712 signing, and receipt confirmation without requiring React or Wagmi.

For React, the source repository provides a two-file TanStack Query reference: `liquidity-hub.ts` contains the framework-neutral client and execution flow, while `liquidity-hub-react.tsx` contains the provider, quote query, and swap mutation. Reuse an existing QueryClientProvider instead of adding a second provider. The `best-trade-form.tsx` example application shows how an application can compose its execution hook with SwapFlow for review, progress, failure, and success states.

See Supported Chains for the shared network list and requirements.