Orderly Sdk Dex Architecture

---

name: orderly-sdk-dex-architecture description: Complete DEX architecture guide including project structure, provider hierarchy, network configuration, TradingView setup, and provider configuration.

---

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:

1. brokerId - Your Orderly broker ID 2. networkId - Either "mainnet" or "testnet" 3. Proper wallet connector setup with matching network 4. 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 (
    
      }>
        
          
            {children}
          
        
      
    
  );
};
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 {children};
};
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

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;
  }
}

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 (
    
      
        }>
          
        
      
    
  );
}

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

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

TradingView Configuration

// In your TradingPage component

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

Node.js 18+ installed

Orderly SDK packages installed (see orderly-sdk-install-dependency)

React 18+ project with TypeScript

Vite or similar build tool