Orderly Sdk Dex Architecture

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

Security Scan

This is an instruction-only architecture guide for building an Orderly DEX; its requirements and instructions are internally consistent with that purpose and it does not request unusual privileges or secrets.

Purpose & Capability

The skill is an architectural guide for an Orderly Network DEX and the SKILL.md content focuses on project structure, provider hierarchy, network/runtime config, and TradingView integration — all consistent with the stated purpose.

Instruction Scope

The instructions reference runtime environment variables (e.g., VITE_ORDERLY_BROKER_ID), localStorage usage, and placement of TradingView library files in public/tradingview/. They do not instruct the agent to read or exfiltrate unrelated files or credentials. Be aware the guide assumes you will wire runtime config and wallet connectors into your app; it uses browser APIs (window, localStorage) which is expected for a frontend app.

Install Mechanism

No install spec or code files are present; this is instruction-only so nothing is downloaded or written by the skill itself at install time (lowest install risk).

Credentials

Skill metadata declares no required env vars, but the guide references VITE_ runtime variables and a brokerId/networkId that you must supply when implementing the app. This is proportionate for a DEX guide, but you should avoid placing secrets or private keys in client-side .env or public runtime config. Wallet connectors will interact with user wallets — do not hard-code private keys.

Persistence & Privilege

The skill is not marked always:true and requests no config paths or persistent privileges. Autonomous invocation is allowed (platform default) but this is an instruction-only guide and does not modify other skills or system settings.

Assessment

This skill is an architecture and scaffolding guide (no code or installers), and appears coherent with its purpose. Consider these before using: 1) The guide expects you to supply runtime vars like VITE_ORDERLY_BROKER_ID and to host TradingView files — avoid storing secrets or private keys in client-side .env or public runtime config. 2) Vet and pin any third-party packages (e.g., @orderly.network packages, TradingView) for license and supply-chain risk. 3) Do not commit .env or private keys to source control; use safe secret management for any server-side credentials. 4) If you implement wallet connectors, ensure users sign transactions client-side — never embed private keys. 5) Because the skill is instruction-only, installing it does not execute code, but you should still audit any code or packages you add to your project based on the guide.

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 (
    <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

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