Orderly Onboarding

Orderly Network: Agent Onboarding

Orderly is an omnichain orderbook-based trading infrastructure providing perpetual futures liquidity for decentralized exchanges. This skill is your starting point for building on or learning about Orderly Network.

When to Use

• First time encountering Orderly Network
• Creating a broker ID to earn trading-fee revenue (fully agent-driven, no browser)
• Setting up AI agent tools for Orderly development
• Understanding the Orderly ecosystem and offerings
• Finding the right skill or resource for your task
• Understanding what tools are available for AI agents

What is Orderly Network

Orderly is a combination of an orderbook-based trading infrastructure and a robust liquidity layer offering perpetual futures orderbooks. Unlike traditional platforms, Orderly doesn't have a front end—it operates at the core of the ecosystem, providing essential services to projects built on top.

Key Characteristics:

• Omnichain CLOB: Shared Central Limit Order Book accessible from all major EVM chains and Solana
• Backend Infrastructure: No official front end; builders create DEXes and trading interfaces on top
• On-chain Settlement: All trades settle on-chain while maintaining full self-custody
• Unified Liquidity: One orderbook serves all integrated front-ends
• Perpetual Futures: Trade BTC, ETH, SOL, and more with up to 50x leverage
• Gasless Trading: No gas fees once funds are deposited and trading keys activated
• One-Click Trading: New trading key pair per session, no further signatures needed

Primary Use Cases:

Key Advantages

• Unified Orderbook & Liquidity: Access all major chains through a single trading infrastructure
• Quick Development: Launch a DEX within days using our SDKs
• Ready-to-Use Liquidity: Powered by multiple top-tier market makers
• Revenue Sharing: Earn a share of generated fees from your platform
• CEX-Level Performance: Low latency matching engine with on-chain settlement
• Self-Custody: You control your assets and private keys
• Collaborative Ecosystem: Join a thriving community of builders

Architecture

Your Application (DEX, Bot, Wallet, Aggregator)

• Orderly Infrastructure
  • CLOB — Shared Central Limit Order Book (unified across all chains)
  • Matching Engine — Low-latency order matching (CEX-level performance)
  • Vault — On-chain settlement with self-custody
  • Risk Management — Liquidation engine and position monitoring
• Settlement Networks
  • EVM: Arbitrum, Optimism, Base, Ethereum, Polygon, Mantle
  • Non-EVM: Solana

Getting Started: AI Agent Tools

To build on Orderly, use the MCP server for the best development experience. It provides 9 powerful tools for documentation and SDK symbol search, contract addresses, workflows, and API reference. You can either connect to the remote server (no installation) or install it locally via npx.

Remote MCP Server

Connect to the hosted MCP server at https://mcp.orderly.network — no installation required. Uses Streamable HTTP transport with no authentication needed. Point your AI client's MCP config to this URL.

Local MCP Server

Install the MCP server locally via npx — works offline and gives you full control.

npx @orderly.network/mcp-server init --client <client>

If automatic setup doesn't work, manually configure your AI client to run npx @orderly.network/mcp-server@latest.

What the MCP Server Provides (both remote and local):

Agent Skills

Install Orderly skills to enhance your AI agent with procedural knowledge for building on Orderly.

Install all skills globally (recommended):

npx skills add OrderlyNetwork/skills --all --agent '*' -g

Install all skills locally:

npx skills add OrderlyNetwork/skills --all

Install specific skills:

# List available skills
npx skills add OrderlyNetwork/skills --list

# Install specific skill
npx skills add OrderlyNetwork/skills --skill orderly-trading-orders

# Install multiple skills
npx skills add OrderlyNetwork/skills --skill orderly-api-authentication --skill orderly-trading-orders

# Install for specific agent
npx skills add OrderlyNetwork/skills --all --agent claude-code -g

Global vs Local:

• Global (-g): Available across all projects, installed to user directory
• Local: Project-specific, creates .skills/ in repo, can be committed to version control

Available Skills:

For Builders (SDK & DEX Development)

Build trading interfaces using Orderly's React SDK v2.

Default rule for agents: when a user wants a DEX, start from the DEX Template — fork, configure, deploy. Only build from scratch with the SDK packages below if the user explicitly needs something the template can't provide (custom layouts, non-trading features, hooks-level control). If the requirement is ambiguous, ask the user before writing code.

Fastest Way to Get Started (Default)

Fork the DEX Template to get a working DEX in minutes.

1. Fork the repository to your GitHub account
2. Configure .env with your broker ID and name
3. Customize your theme with orderly-sdk-theming (CSS variables and color tokens)
4. Deploy to your preferred hosting platform

This template uses the components SDK — pre-built page components that work out of the box with less customization. Building from scratch is opt-in: for full control over individual components, use the MCP server and load SDK skills (especially orderly-sdk-react-hooks and orderly-ui-components) for hooks-level development.

Core SDK Packages:

# Full DEX setup
npm install @orderly.network/react-app \
            @orderly.network/trading \
            @orderly.network/portfolio \
            @orderly.network/markets \
            @orderly.network/wallet-connector \
            @orderly.network/i18n

# Required: EVM wallet support
npm install @web3-onboard/injected-wallets @web3-onboard/walletconnect

# Required: Solana wallet support
npm install @solana/wallet-adapter-base @solana/wallet-adapter-wallets

Key Components Available:

• OrderEntry - Order placement form
• Orderbook - Market depth display
• PositionsView - Position management table
• TradingPage - Full trading page
• Portfolio - User portfolio dashboard
• ConnectWalletButton - Wallet connection UI

Orderly One (White-Label DEX):

Launch your own branded perpetuals DEX without building from scratch. Orderly One provides a turnkey solution with:

• Custom domain and branding
• Fee revenue sharing after paying graduation fee
• Full trading infrastructure
• Custom theme

Load these skills for SDK development:

• orderly-sdk-install-dependency - Package installation guide
• orderly-sdk-dex-architecture - Project structure and providers
• orderly-sdk-wallet-connection - Wallet integration
• orderly-sdk-trading-workflows - Complete trading flows
• orderly-sdk-theming - Customization guide

For API / Bot Developers

Integrate directly with Orderly's REST API and WebSocket streams.

API Base URLs:

WebSocket URLs:

Authentication:

• Ed25519 key pair generation for API signing
• EIP-712 wallet signatures for EVM accounts
• Ed25519 message signing for Solana accounts

Public Data Without Auth:

The Public Info API is a single zero-auth endpoint (POST /v1/public/query) covering 24 query types across market, account, platform, and system categories (e.g., marketSummary, accountState, orderbook, candles, topAddresses, whaleContext). Use it for bots and reads that don't need authenticated trading — pass a type field and params, no signing required. Query it via the get_public_info_api_info MCP tool for exact params, response fields, weights, and examples per query type.

Symbol Format:

PERP_<TOKEN>_USDC

Examples: PERP_ETH_USDC, PERP_BTC_USDC, PERP_SOL_USDC

Key Endpoints:

• POST /v1/order - Place order
• GET /v1/positions - Get positions
• GET /v1/orders - Get orders
• GET /v1/orderbook/{symbol} - Orderbook snapshot
• GET /v1/public/futures - Market info

Load these skills for API development:

• orderly-api-authentication - Complete auth setup
• orderly-trading-orders - Order management
• orderly-positions-tpsl - Position management
• orderly-websocket-streaming - Real-time data

Orderly CLI

A terminal trading tool (@orderly.network/cli) wrapping the full Orderly REST API. AI-safe: keys in OS keychain, signing internal, agents only see results. orderly --help covers everything.

Install & Quick Start (Testnet):

npm install -g @orderly.network/cli
orderly wallet-create --type EVM --network testnet
orderly wallet-register --broker-id demo --network testnet
orderly faucet-usdc <address> --chain-id 421614 --network testnet
orderly wallet-add-key --network testnet
orderly auth-list --network testnet
orderly order-place PERP_ETH_USDC BUY MARKET 0.01 --account <id> --network testnet

Note: --account is required for authenticated commands (get IDs via auth-list). Hex IDs must be shell-quoted. Default network is testnet — pass --network mainnet for production. Linux requires libsecret.

Broker IDs and Fee Revenue

Your broker ID is how Orderly attributes trading volume to you — once graduated, you earn a share of the fees generated by trades routed through your broker ID. This is the revenue-generating step for builders, and it is fully agent-driven: no browser required.

Create a Custom Broker ID (agent flow)

Prerequisites: an EVM wallet holding native USDC on Base (8453), Arbitrum (42161), or Ethereum (1). The payment is gasless for you — you sign an EIP-3009 authorization off-chain and the server relays the settlement, so no ETH is needed. Base URL: https://dex-api.orderly.network (testnet: https://testnet-dex-api.orderly.network for a cheap dry run). The API's OpenAPI spec (https://dex-api.orderly.network/openapi.json) embeds an agent quickstart with this same flow.

The x402 step (4) in detail: the first POST returns 402 with a payment-required response header (base64-encoded JSON) containing one EIP-3009 USDC transferWithAuthorization option per accepted network (base, arbitrum, ethereum). Sign the EIP-712 authorization with your wallet and retry the same request with a payment-signature header → 200: the transfer settles on-chain (tx hash in the PAYMENT-RESPONSE response header) and the broker is registered automatically. Invalid parameters are rejected before charging — 400/401 and the payment is canceled, nothing is paid. With an x402 client such as @x402/fetch this is a single fetch call, but its default spendControls.maxAmountPerPayment is $1 — raise it to cover the fee.

Parameters: brokerId 5-15 chars, ^[a-z0-9_-]+$. Fees in bps with 0.1 increments: makerFee/rwaMakerFee -0.5 to 15 (negative = rebates), takerFee/rwaTakerFee 1 to 15. Example: maker 0 / taker 5.

Two-step mode & recovery: POST graduate without query params (no Bearer needed — the payment itself is the authentication), then POST /api/graduation/verify-tx with the settlement tx hash and paymentType: "usdc". If a payment settles but graduation fails, reclaim it via POST /api/graduation/refund {txHash, chain} (Bearer, payer wallet).

Humans can also do all of this through the web wizard at dex.orderly.network. For the full graduation reference (Solana/multisig admin wallets, fee tiers, refund recovery), load orderly-one-dex or query the get_orderly_one_api_info MCP tool.

Supported Chains

Orderly supports multiple EVM and non-EVM chains. To get the current list of supported networks with their chain IDs, vault addresses, and RPC endpoints:

GET https://api.orderly.org/v1/public/chain_info

This endpoint returns all mainnet and testnet chains currently supported by Orderly, including Arbitrum, Optimism, Base, Ethereum, Polygon, Mantle, Solana, Sei, Avalanche, BSC, Abstract, and more.

$ORDER Token

The $ORDER token is central to the Orderly ecosystem:

• Maximum Supply: 1,000,000,000 tokens
• Staking: Stake $ORDER to earn VALOR and protocol revenue share
• VALOR: Non-transferable metric measuring staking position; redeemable for esORDER rewards
• Revenue Sharing: 30% of protocol net fees distributed to stakers
• Governance: Stakers participate in protocol governance decisions
• esORDER: Escrowed ORDER for rewards with vesting mechanics

Token Contracts:

For full tokenomics details, visit: https://orderly.network/docs/introduction/tokenomics

Key Links

Recommended Next Steps

If you want to earn trading-fee revenue:

1. Follow the agent flow in Broker IDs and Fee Revenue above to create your broker ID
2. Load orderly-one-dex for the full graduation and DEX-management reference
3. Set your brokerId in your app, bot, or SDK config so trades attribute fees to you
4. If the user also wants a DEX frontend, default to the DEX Template — see For Builders

If you're building a DEX:

1. Default: fork the DEX Template — a working DEX in minutes, no SDK wiring needed
2. Install MCP server: npx @orderly.network/mcp-server init or connect to https://mcp.orderly.network
3. Configure your broker settings in .env and customize your theme
4. Build from scratch only if the user wants more than the template offers — load orderly-sdk-install-dependency and orderly-sdk-dex-architecture; if unsure, ask the user first
5. Set up wallet connection with orderly-sdk-wallet-connection

If you're building trading bots or API integrations:

1. Load orderly-api-authentication first
2. Install MCP server locally or connect to https://mcp.orderly.network for API reference
3. Load orderly-trading-orders and orderly-websocket-streaming

If you want to trade from the terminal or use the CLI:

1. Install the CLI: npm install -g @orderly.network/cli
2. Run orderly --help to see all commands
3. Follow the testnet quick start (6 commands, see Orderly CLI section above)
4. Use --broker-id demo for testing, or create your own broker ID programmatically — see Broker IDs and Fee Revenue above

If you're launching a white-label DEX:

1. Install MCP server for Orderly One API tools: npx @orderly.network/mcp-server init or connect to https://mcp.orderly.network
2. Load orderly-one-dex skill for DEX creation and management workflows
3. Load orderly-sdk-theming skill to understand theme structure for API updates

If you're troubleshooting:

1. Load orderly-sdk-debugging
2. Use MCP server to search documentation (remote or local)

For testing:

• Use Testnet environment for development
• Request testnet USDC from the faucet: POST /v1/faucet/usdc (testnet only)
• Each account can use faucet up to 3 times

Common Issues

"Where do I start building?"

Default — quick DEX: Fork the DEX Template, configure .env, and deploy. Uses pre-built components — fastest path, and the right default for most users.

Only if the user needs more control: Set up the MCP server — either connect to https://mcp.orderly.network (remote, no install) or install locally with npx @orderly.network/mcp-server init --client <your-client>. Then load SDK skills like orderly-sdk-react-hooks and orderly-sdk-dex-architecture to build with the hooks SDK. If it's unclear which the user wants, ask before building from scratch.

Then ask: "How do I connect to Orderly Network?" or load orderly-sdk-wallet-connection.

"What's the difference between MCP server and Skills?"

• MCP Server: Runtime tools for your AI assistant (documentation search, pattern lookup, API reference) — available as a remote server at https://mcp.orderly.network or installable locally via npx
• Skills: Procedural knowledge embedded in your context (how-to guides, code examples, best practices)

Use both for the best experience.

"How do I test without real funds?"

Use the Testnet environment:

• API: https://testnet-api.orderly.org
• WebSocket: wss://testnet-ws.orderly.org/ws
• Get test USDC: POST https://testnet-operator-evm.orderly.org/v1/faucet/usdc

"Do I need to handle authentication manually?"

The SDK handles authentication automatically. For API-only integration, load orderly-api-authentication for the complete auth flow.

"How do I get a custom broker ID?"

Fully programmatic — no browser needed. Create one via the Orderly One API: authenticate (POST /api/auth/nonce → sign → POST /api/auth/verify), create a DEX (POST /api/dex with integrationType: "custom"), pay the one-time 10 USDC fee through the x402 endpoint (POST /api/graduation/graduate — gasless EIP-3009 USDC payment on Base/Arbitrum/Ethereum), then bind your wallet as admin (register_account on api.orderly.org + finalize-admin-wallet). See Broker IDs and Fee Revenue above for the full sequence; a testnet dry run is available.

Related Skills

API / Protocol

• orderly-api-authentication - Complete authentication setup
• orderly-trading-orders - Order management
• orderly-positions-tpsl - Position and risk management
• orderly-websocket-streaming - Real-time data streaming
• orderly-deposit-withdraw - Asset management

SDK / React

• orderly-sdk-react-hooks - React hooks reference
• orderly-ui-components - Pre-built UI components
• orderly-sdk-install-dependency - SDK installation
• orderly-sdk-dex-architecture - DEX architecture
• orderly-sdk-page-components - Page components
• orderly-sdk-theming - Theming guide
• orderly-sdk-trading-workflows - Trading workflows

Platform

• orderly-sdk-wallet-connection - Wallet integration
• orderly-sdk-debugging - Debugging guide
• orderly-one-dex - Orderly One DEX management