Orderly Network: Orderly One DEX

Orderly One (https://dex.orderly.network) is a platform that lets anyone launch a white-label perpetual-futures DEX on Orderly Network — with or without code. It serves as both:

A web UI at dex.orderly.network where humans can create, configure, and deploy a DEX through a step-by-step wizard.
A REST API that an AI agent or script can call to do the same thing programmatically.

Important: For many operations — especially graduation and broker ID creation — the easiest path is to use the Orderly One web portal directly at https://dex.orderly.network/dex. Always inform users that this option exists. Not everything has to be done through the API.

Two Launch Paths

| Path | Description | Graduation Fee | Who It's For | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | -------------- | ------------------------------------------------------- | | Low-code | Create a branded DEX frontend via Orderly One portal or API. It forks a template repo and deploys to GitHub Pages. | $100 | Teams wanting fast launch with minimal frontend work | | Custom SDK/API | Use the Orderly SDK or API to build a fully custom frontend. Graduate via Orderly One to get a broker ID — no DEX frontend required. | $10 | Wallets, existing exchanges, teams wanting full control |

See the official builder onboarding guide: https://orderly.network/docs/introduction/getting-started/builder-onboarding

When to Use

Creating a custom perpetuals DEX
Managing DEX deployment, domains, or themes
Handling graduation for fee sharing

Key Concepts

Broker ID: A unique identifier in the Orderly ecosystem. Starts as "demo" and becomes a real broker ID after graduation. This is how your DEX earns trading fees.
Graduation: The process of converting a demo DEX into a fee-earning DEX by paying $10-$100 and registering as a broker.
Template Repository: The GitHub repo that gets forked for each low-code DEX. Contains the Orderly SDK trading frontend.
One DEX Per User: Each wallet address can create exactly one DEX.

API Base URLs

| Environment | Base URL | | ----------- | ----------------------------------------- | | Mainnet | https://dex-api.orderly.network | | Testnet | https://testnet-dex-api.orderly.network |

The API exposes an interactive OpenAPI spec (Scalar) at the root: GET /

Graduation-Supported Chains (Payment)

Mainnet: Ethereum (1), Arbitrum (42161), Base (8453) Testnet: Sepolia, Arbitrum Sepolia, Base Sepolia

API Categories

Use get_orderly_one_api_info MCP tool for full endpoint details.

| Category | Description | Key Endpoints | | --------------- | -------------------------------- | ------------------------------------------------------------------------------------------- | | auth | Wallet signature authentication | /api/auth/nonce, /api/auth/verify, /api/auth/validate | | dex | DEX CRUD, domains, deployment | /api/dex, /api/dex/{id}, /api/dex/{id}/custom-domain, /api/dex/{id}/workflow-status | | theme | AI theme generation | /api/theme/modify, /api/theme/fine-tune | | graduation | Demo → full DEX with fee sharing | /api/graduation/status, /api/graduation/fee-options, /api/graduation/verify-tx | | leaderboard | Cross-DEX rankings | /api/leaderboard, /api/leaderboard/broker/{brokerId} | | stats | Platform statistics | /api/stats, /api/stats/swap-fee-config |

Create/Update DEX

Both POST /api/dex (create) and PUT /api/dex/{id} (update) use multipart/form-data.

Required Fields

| Field | Type | Constraints | | ------------ | ------ | ----------------------------------------- | | brokerName | string | 3-30 chars, alphanumeric/space/dot/hyphen |

Optional Fields

Chains: | Field | Type | Notes | | -------------- | ---------------- | ------------------------ | | chainIds | number[] (JSON) | e.g. [42161, 10, 8453] | | defaultChain | number | Default chain ID |

Branding (files): | Field | Type | Max Size | | --------------- | ---- | -------- | | primaryLogo | File | 250KB | | secondaryLogo | File | 100KB | | favicon | File | 50KB | | pnlPoster0..N | File | 250KB ea |

Theming: | Field | Type | Notes | | --------------- | ------ | -------------------------------- | | themeCSS | string | CSS variables to override default theme | | tradingViewColorConfig | string | JSON for chart colors |

Social: | Field | Type | Notes | | -------------- | ------ | ------------------ | | telegramLink | string | URL | | discordLink | string | URL | | xLink | string | URL |

Auth/Wallet: | Field | Type | Notes | | ------------------------ | -------- | -------------------------- | | walletConnectProjectId | string | WalletConnect project ID | | privyAppId | string | Privy app ID | | privyTermsOfUse | string | URL to terms | | privyLoginMethods | string | Comma-separated | | enableAbstractWallet | boolean | Enable Abstract wallet | | disableEvmWallets | boolean | Disable EVM wallets | | disableSolanaWallets | boolean | Disable Solana wallets |

Network: | Field | Type | Notes | | ------------------ | ------- | -------------------- | | disableMainnet | boolean | Disable mainnet | | disableTestnet | boolean | Disable testnet |

Trading: | Field | Type | Notes | | ------------ | -------------- | ------------------------------- | | swapFeeBps | number (0-100) | Swap fee in basis points (requires "Swap" in enabledMenus) | | symbolList | string | Comma-separated (PERP_ETH_USDC) |

Menus: | Field | Type | Notes | | -------------- | ------ | ----------------------------- | | enabledMenus | string | Comma-separated. Options: Trading, Portfolio, Markets, Leaderboard (defaults), Swap, Rewards, Vaults, Points | | customMenus | string | Format: "Name,URL;Name2,URL2" |

SEO: | Field | Type | Constraints | | ------------------- | ------ | --------------------- | | seoSiteName | string | max 100 chars | | seoSiteDescription| string | max 300 chars | | seoSiteLanguage | string | "en" or "en-US" | | seoSiteLocale | string | "en_US" | | seoTwitterHandle | string | "@handle" | | seoThemeColor | string | "#1a1b23" | | seoKeywords | string | max 500 chars |

Other: | Field | Type | Notes | | -------------------------- | ------- | ------------------------ | | availableLanguages | string | JSON array. Options: en, zh, tc, ja, es, ko, vi, de, fr, ru, id, tr, it, pt, uk, pl, nl | | analyticsScript | string | Base64 encoded | | enableServiceDisclaimerDialog | boolean | Show disclaimer | | enableCampaigns | boolean | Enable ORDER token campaigns and Points menu | | restrictedRegions | string | Comma-separated country names (e.g., "United States,China") | | whitelistedIps | string | IP whitelist |

Response

Create (201): { id, brokerId, brokerName, repoUrl, userId, createdAt }

Update (200): Full DEX object with all fields

Key Workflows

Authentication

Orderly One has its own auth system, separate from the Orderly Network API (api.orderly.org). It uses standard EVM personal_sign (EIP-191) — EVM wallets only (0x addresses).

POST /api/auth/nonce with { "address": "0x..." } → { message, nonce }
Sign the returned message using personal_sign (EIP-191)
POST /api/auth/verify with { "address": "0x...", "signature": "0x..." } → { user: { id, address }, token }
Use Authorization: Bearer {token} for all subsequent requests (expires 24h)
Validate: POST /api/auth/validate with { "address", "token" } → { valid: true/false }

Note: The graduation "finalize admin wallet" step requires authenticating with the Orderly Network API (api.orderly.org) — a separate system using EIP-712 or Ed25519 signing. See the graduation workflow below.

Create DEX Flow

Build multipart/form-data with fields above
POST /api/dex → returns { id, brokerId, repoUrl }
Poll GET /api/dex/{id}/workflow-status until conclusion: "success"

Graduation (Fee Sharing)

Prerequisites: DEX created with brokerId: "demo" (not already graduated), payment tokens on a supported chain.

Step 1 — Get Fee Options:

GET /api/graduation/fee-options → { usdc: { amount }, usdt: { amount }, order: { amount, currentPrice }, receiverAddress }

Low-code: $100 | Custom SDK: $10
Payment in USDC, USDT, or ORDER (ORDER amount varies with price)

Step 2 — Send Payment On-Chain:

ERC-20 transfer() to receiverAddress on a supported chain. Save the tx hash.

| Network | Chains | Tokens | |---------|--------|--------| | Mainnet | Ethereum, Arbitrum, Base | USDC, USDT, ORDER | | Testnet | Sepolia, Arbitrum Sepolia, Base Sepolia | USDC, USDT, ORDER |

Step 3 — Verify Transaction:

POST /api/graduation/verify-tx with:

| Field | Description | |-------|-------------| | txHash | Payment transaction hash | | chain | ethereum, arbitrum, base, sepolia, arbitrum-sepolia, base-sepolia | | chainId | Chain ID (e.g. 42161) | | chain_type | "EVM" | | brokerId | Your chosen unique broker ID | | makerFee | Maker fee in bps (min 3) | | takerFee | Taker fee in bps (min 6, typically 2x maker) | | rwaMakerFee | RWA maker fee in bps | | rwaTakerFee | RWA taker fee in bps | | paymentType | "USDC", "USDT", or "ORDER" |

The API verifies: tx exists, sender matches authenticated user, recipient is correct receiverAddress, amount meets fee, tx not reused, brokerId not taken.

Step 4 — Register Admin Wallet (required to complete graduation):

EVM Wallet:

GET https://api.orderly.org/v1/registration_nonce
Sign EIP-712 typed data: { brokerId, chainId, timestamp, registrationNonce }
POST https://api.orderly.org/v1/register_account with { message, signature, userAddress, chainType: "EVM" }
POST /api/graduation/finalize-admin-wallet (empty body)

Solana Wallet:

Same flow but chainId: 900900900, sign with Solana wallet, chainType: "SOL"

EVM Multisig/Gnosis Safe:

Safe Wallet → Transaction Builder → batch: delegateSigner on Vault contract with [keccak256(brokerId), userAddress]
Execute with signer approvals
POST /api/graduation/finalize-admin-wallet with { multisigAddress, multisigChainId }

Note: Step 4 authenticates with the Orderly Network API (api.orderly.org), not Orderly One — different auth system (EIP-712/Ed25519).

Graduation Status & Fees:

| Endpoint | Description | |----------|-------------| | GET /api/graduation/status | Basic status: { currentBrokerId, approved } | | GET /api/graduation/graduation-status | Detailed: { isGraduated, brokerId, isMultisig, multisigAddress } | | GET /api/graduation/fees | Current maker/taker/RWA fee rates | | GET /api/graduation/tier | Builder Staking Programme tier |

Orderly MCP

This skill references the Orderly MCP server. If not installed, see orderly-onboarding skill for setup.

Tool: get_orderly_one_api_info

{ endpoint: "/api/dex" } - Specific endpoint details
{ category: "graduation" } - All endpoints in a category
{} - Full API overview

Common Issues

| Issue | Solution | | --------------------------- | --------------------------------------------------------------------------------------- | | DEX stuck deploying | Check /api/dex/{id}/workflow-runs/{runId} for job failures | | Domain not working | CNAME to {org}.github.io, wait for DNS propagation | | Graduation verify fails | Confirm tx to receiverAddress, wait for confirmations | | "Broker ID already taken" | Choose a different brokerId in verify-tx | | "Transaction hash already used" | Each tx can only be used once (anti-replay). Send a new payment | | "Must register EVM address" | Complete admin wallet registration (Step 4) before calling finalize-admin-wallet | | "Already graduated" | Each user can only graduate once | | Logo upload fails | Check file size limits (250KB primary, 100KB secondary) | | Invalid CSS | Validate themeCSS syntax before submitting |

Related Skills

orderly-onboarding - Account setup and builder onboarding
orderly-trading-orders - Trading functionality