Orderly Sdk Dex Architecture

Complete DEX architecture guide including project structure, provider hierarchy, network configuration, TradingView setup, and provider configuration.

Audits

Pass

ClawScanPass

Agentic behavior and permission review.

Static analysisPass

Pattern checks against bundled files.

VirusTotalPass

Multi-engine malware detections and file reputation.

Install

openclaw skills install orderly-sdk-dex-architecture

Orderly Network: SDK DEX Architecture

A comprehensive guide to architecting and scaffolding a complete DEX application using the Orderly Network Components SDK.

When to Use

Setting up a new DEX project
Understanding the provider hierarchy
Configuring network settings
Setting up TradingView charts
Understanding runtime configuration

Prerequisites

Node.js 18+ installed
Orderly SDK packages installed (see orderly-sdk-install-dependency)
React 18+ project with TypeScript
Vite or similar build tool

Overview

This skill covers the complete architecture for building a production-ready DEX:

Project structure and setup
Provider hierarchy and configuration
Network configuration (REQUIRED) - mainnet/testnet and supported chains
TradingView chart setup (REQUIRED for charts) - charting library files
Routing and page components
Runtime configuration
Build and deployment

Critical Configuration: Every DEX must have:

brokerId - Your Orderly broker ID
networkId - Either "mainnet" or "testnet"
Proper wallet connector setup with matching network
TradingView charting library in public/tradingview/ (for chart functionality)

Project Structure

my-dex/
├── public/
│   ├── config.js              # Runtime configuration
│   ├── favicon.webp
│   ├── locales/               # i18n translations
│   │   ├── en.json
│   │   └── extend/            # Custom translations
│   ├── pnl/                   # PnL share poster backgrounds
│   │   ├── poster_bg_1.png
│   │   └── poster_bg_2.png
│   └── tradingview/           # TradingView library (REQUIRED for charts)
│       ├── chart.css          # Custom chart styles
│       └── charting_library/  # TradingView charting library files
├── src/
│   ├── main.tsx               # Entry point
│   ├── App.tsx                # Root component with router
│   ├── components/
│   │   ├── orderlyProvider/   # SDK provider setup
│   │   │   ├── index.tsx      # Main provider wrapper
│   │   │   └── walletConnector.tsx
│   │   ├── ErrorBoundary.tsx
│   │   └── LoadingSpinner.tsx
│   ├── pages/
│   │   ├── perp/              # Trading pages
│   │   ├── portfolio/         # Portfolio pages
│   │   ├── markets/           # Markets pages
│   │   └── leaderboard/       # Leaderboard pages
│   ├── utils/
│   │   ├── config.tsx         # App configuration
│   │   ├── walletConfig.ts    # Wallet setup
│   │   ├── runtime-config.ts  # Runtime config loader
│   │   └── storage.ts         # Local storage utils
│   └── styles/
│       └── index.css          # Global styles + Tailwind
├── .env                       # Build-time env vars
├── index.html
├── package.json
├── tailwind.config.ts
├── tsconfig.json
└── vite.config.ts

Provider Hierarchy

The SDK requires a specific provider nesting order:

LocaleProvider (i18n)
└── WalletConnectorProvider (or Privy)
    └── OrderlyAppProvider
        ├── (internal) AppConfigProvider
        ├── (internal) OrderlyThemeProvider
        ├── (internal) OrderlyConfigProvider (from hooks)
        ├── (internal) AppStateProvider
        ├── (internal) UILocaleProvider
        ├── (internal) TooltipProvider
        ├── (internal) ModalProvider
        └── Your App

Note: TooltipProvider and ModalProvider are managed internally by OrderlyAppProvider. You do not need to add them yourself.

Main Provider Component

// src/components/orderlyProvider/index.tsx
import { ReactNode, useCallback, Suspense, lazy } from 'react';
import { OrderlyAppProvider } from '@orderly.network/react-app';
import { LocaleProvider, LocaleCode, defaultLanguages } from '@orderly.network/i18n';
import type { NetworkId } from '@orderly.network/types';
import { useOrderlyConfig } from '@/utils/config';
import { getRuntimeConfig, getRuntimeConfigBoolean } from '@/utils/runtime-config';

const NETWORK_ID_KEY = 'orderly_network_id';

const getNetworkId = (): NetworkId => {
  if (typeof window === 'undefined') return 'mainnet';

  const disableMainnet = getRuntimeConfigBoolean('VITE_DISABLE_MAINNET');
  const disableTestnet = getRuntimeConfigBoolean('VITE_DISABLE_TESTNET');

  if (disableMainnet && !disableTestnet) return 'testnet';
  if (disableTestnet && !disableMainnet) return 'mainnet';

  return (localStorage.getItem(NETWORK_ID_KEY) as NetworkId) || 'mainnet';
};

const WalletConnector = lazy(() => import('./walletConnector'));

const OrderlyProvider = ({ children }: { children: ReactNode }) => {
  const config = useOrderlyConfig();
  const networkId = getNetworkId();

  const onChainChanged = useCallback((_chainId: number, { isTestnet }: { isTestnet: boolean }) => {
    const currentNetworkId = getNetworkId();
    if (
      (isTestnet && currentNetworkId === 'mainnet') ||
      (!isTestnet && currentNetworkId === 'testnet')
    ) {
      const newNetworkId: NetworkId = isTestnet ? 'testnet' : 'mainnet';
      localStorage.setItem(NETWORK_ID_KEY, newNetworkId);
      window.location.reload();
    }
  }, []);

  const onLanguageChanged = (lang: LocaleCode) => {
    const url = new URL(window.location.href);
    if (lang === 'en') {
      url.searchParams.delete('lang');
    } else {
      url.searchParams.set('lang', lang);
    }
    window.history.replaceState({}, '', url.toString());
  };

  return (
    <LocaleProvider onLanguageChanged={onLanguageChanged} locale="en" languages={defaultLanguages}>
      <Suspense fallback={<LoadingSpinner />}>
        <WalletConnector networkId={networkId}>
          <OrderlyAppProvider
            brokerId={getRuntimeConfig('VITE_ORDERLY_BROKER_ID')}
            brokerName={getRuntimeConfig('VITE_ORDERLY_BROKER_NAME')}
            networkId={networkId}
            onChainChanged={onChainChanged}
            appIcons={config.appIcons}
          >
            {children}
          </OrderlyAppProvider>
        </WalletConnector>
      </Suspense>
    </LocaleProvider>
  );
};

export default OrderlyProvider;

Wallet Connector Setup

Note: Both solanaInitial and evmInitial props on WalletConnectorProvider are optional. The provider has sensible defaults and the official templates use it with no props. Pass these props only if you need to customize wallet configuration.

Minimal Setup (recommended — uses defaults):

// src/components/orderlyProvider/walletConnector.tsx
import { ReactNode } from 'react';
import { WalletConnectorProvider } from '@orderly.network/wallet-connector';
import type { NetworkId } from '@orderly.network/types';

interface Props {
  children: ReactNode;
  networkId: NetworkId;
}

const WalletConnector = ({ children, networkId }: Props) => {
  return <WalletConnectorProvider>{children}</WalletConnectorProvider>;
};

export default WalletConnector;

Network Configuration (REQUIRED)

IMPORTANT: Every Orderly DEX must configure the network properly.

Supported Networks

Mainnet Chains (Production)

Chain	Chain ID	Description
Arbitrum	42161	Primary mainnet chain
Optimism	10	OP mainnet
Base	8453	Base mainnet
Ethereum	1	Ethereum mainnet
Solana	N/A	Solana mainnet

Testnet Chains (Development)

Chain	Chain ID	Description
Arbitrum Sepolia	421614	Primary testnet chain
Base Sepolia	84532	Base testnet
Solana Devnet	901901901	Solana devnet

Network ID Configuration

The networkId prop determines whether your DEX connects to mainnet or testnet.

import type { NetworkId } from '@orderly.network/types';

// Network ID must be "mainnet" or "testnet"
const networkId: NetworkId = 'mainnet'; // or "testnet"

Complete Provider Setup with Network Config

<WalletConnectorProvider
  solanaInitial={{
    network: networkId === "mainnet"
      ? WalletAdapterNetwork.Mainnet
      : WalletAdapterNetwork.Devnet,
    wallets: [],
  }}
  evmInitial={{
    options: {
      wallets: [],
    },
  }}
>
  <OrderlyAppProvider
    brokerId="your_broker_id"
    brokerName="Your DEX Name"
    networkId={networkId}
    onChainChanged={onChainChanged}
  >

Runtime Configuration

Use runtime configuration for deployment flexibility:

public/config.js

window.__RUNTIME_CONFIG__ = {
  VITE_ORDERLY_BROKER_ID: 'your_broker_id',
  VITE_ORDERLY_BROKER_NAME: 'Your DEX Name',
  VITE_DISABLE_MAINNET: 'false',
  VITE_DISABLE_TESTNET: 'false',
  VITE_DEFAULT_CHAIN: '42161',
};

Runtime Config Loader

// src/utils/runtime-config.ts

export function getRuntimeConfig(key: string): string {
  if (typeof window !== 'undefined' && window.__RUNTIME_CONFIG__?.[key]) {
    return window.__RUNTIME_CONFIG__[key];
  }
  return import.meta.env[key] || '';
}

export function getRuntimeConfigBoolean(key: string): boolean {
  return getRuntimeConfig(key) === 'true';
}

export function getRuntimeConfigArray(key: string): string[] {
  const value = getRuntimeConfig(key);
  if (!value) return [];
  return value
    .split(',')
    .map((s) => s.trim())
    .filter(Boolean);
}

declare global {
  interface Window {
    __RUNTIME_CONFIG__?: Record<string, string>;
  }
}

App Root Component

// src/App.tsx
import { Outlet } from 'react-router-dom';
import { Suspense } from 'react';
import OrderlyProvider from '@/components/orderlyProvider';
import { LoadingSpinner } from '@/components/LoadingSpinner';
import { ErrorBoundary } from '@/components/ErrorBoundary';

export default function App() {
  return (
    <ErrorBoundary>
      <OrderlyProvider>
        <Suspense fallback={<LoadingSpinner />}>
          <Outlet />
        </Suspense>
      </OrderlyProvider>
    </ErrorBoundary>
  );
}

TradingView Chart Setup (REQUIRED)

CRITICAL: The TradingView charting library must be manually added to your public/tradingview/ folder.

Required Files Structure

public/
└── tradingview/
    ├── chart.css                    # Optional: custom chart styling
    └── charting_library/            # REQUIRED: TradingView library
        ├── charting_library.js      # Main library script
        ├── charting_library.d.ts
        └── ... (other library files)

How to Get TradingView Library

Request access from TradingView: https://www.tradingview.com/HTML5-stock-forex-bitcoin-charting-library/
Download the charting library package
Copy the charting_library folder to your public/tradingview/ directory

TradingView Configuration

// In your TradingPage component
<TradingPage
  symbol={symbol}
  tradingViewConfig={{
    scriptSRC: '/tradingview/charting_library/charting_library.js',
    library_path: '/tradingview/charting_library/',
    customCssUrl: '/tradingview/chart.css',
    colorConfig: {
      upColor: '#26a69a',
      downColor: '#ef5350',
    },
  }}
/>

Tailwind Configuration

tailwind.config.ts

import type { Config } from 'tailwindcss';
import { OUITailwind } from '@orderly.network/ui';

export default {
  content: [
    './index.html',
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@orderly.network/**/*.{js,mjs}',
  ],
  presets: [OUITailwind.preset],
  theme: {
    extend: {},
  },
  plugins: [],
} satisfies Config;

src/styles/index.css

@import '@orderly.network/ui/dist/styles.css';

@tailwind base;
@tailwind components;
@tailwind utilities;

Vite Configuration

Important: The wallet connector packages use Node.js built-ins like Buffer. You must add polyfills.

npm install -D vite-plugin-node-polyfills

vite.config.ts

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { nodePolyfills } from 'vite-plugin-node-polyfills';
import path from 'path';

export default defineConfig({
  plugins: [
    react(),
    nodePolyfills({
      include: ['buffer', 'crypto', 'stream', 'util'],
      globals: {
        Buffer: true,
        global: true,
        process: true,
      },
    }),
  ],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
});

Checklist for Production

Broker ID configured
WalletConnect project ID (for mobile wallets)
Runtime config.js deployed
TradingView library (if using charts)
Custom branding (logo, favicon, colors)
Error tracking (Sentry, etc.)
Analytics integration
SSL/HTTPS enabled

Related Skills

orderly-sdk-install-dependency - SDK package installation
orderly-sdk-wallet-connection - Wallet integration details
orderly-sdk-page-components - Using pre-built page components
orderly-sdk-trading-workflows - End-to-end trading implementation
orderly-sdk-theming - Customizing the UI appearance
orderly-sdk-debugging - Troubleshooting common issues