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
• 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, install the MCP server for the best development experience. It provides 8 powerful tools for documentation search, SDK patterns, contract addresses, workflows, and API reference.

MCP Server (Recommended)

The MCP server provides AI assistants with instant access to Orderly documentation, code patterns, and API references.

Quick Install:

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

Supported Clients:

Manual Configuration:

If automatic setup doesn't work, add this configuration to your AI client:

Claude Code (.mcp.json):

{
  "mcpServers": {
    "orderly": {
      "command": "npx",
      "args": ["@orderly.network/mcp-server@latest"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "orderly": {
      "command": "npx",
      "args": ["@orderly.network/mcp-server@latest"]
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "orderly": {
      "command": "npx",
      "args": ["@orderly.network/mcp-server@latest"]
    }
  }
}

OpenCode (.opencode/mcp.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "orderly": {
      "type": "local",
      "command": ["npx", "@orderly.network/mcp-server@latest"],
      "enabled": true
    }
  }
}

Codex (~/.codex/config.toml):

[mcp_servers.orderly]
command = "npx"
args = ["@orderly.network/mcp-server@latest"]

What the MCP Server Provides:

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 custom trading interfaces using Orderly's React SDK v2.

Fastest Way to Get Started (Default for DEX Creation)

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

⚠️ CRITICAL FOR AGENTS — NEVER try to build a DEX by installing @orderly.network/cli:

• @orderly.network/cli is a terminal trading tool for placing perp orders, NOT a DEX builder or scaffolding CLI. Installing it pulls keytar (native C++ build via node-gyp), which will OOM-kill (SIGKILL / 137) 1GB sandboxes.
• Zero-install DEX deployment: The official DEX template requires NO heavy installs on the agent box. Fork OrderlyNetwork/dex-template to the user's GitHub, configure .env, and let GitHub Actions build and deploy it directly to GitHub Pages for free (or deploy to Vercel/Netlify).

1. Fork the repository OrderlyNetwork/dex-template to your GitHub account (or user's GitHub via Composio/gh)
2. Configure .env with your broker ID (VITE_ORDERLY_BROKER_ID) and name (VITE_ORDERLY_BROKER_NAME)
3. Customize your theme in app/styles/theme.css with orderly-sdk-theming (pure CSS custom properties, no build step needed)
4. Complete the required one-time GitHub settings after forking (see template README / AGENTS.md):
   • Enable Actions: gh api repos/$REPO/actions/permissions -X PUT -f enabled=true -f allowed_actions=all
   • Grant workflow write permissions: gh api repos/$REPO/actions/permissions/workflow -X PUT -f default_workflow_permissions=write -F can_approve_pull_request_reviews=true
   • Enable GitHub Pages with Actions: gh api repos/$REPO/pages -X POST -f build_type=workflow (Without these permissions, GitHub Actions will not run and auto-deployment will fail.)
5. Push to main — GitHub Actions builds via GitHub-hosted runner and publishes to https://<user>.github.io/<repo>/

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

Core SDK Packages:

Package Manager: Prefer pnpm add (or yarn add) over npm install — pnpm uses ~⅓ the peak memory during dependency resolution, avoiding memory pressure in resource-constrained container environments.

# Full DEX setup (prefer pnpm)
pnpm add @orderly.network/react-app \
         @orderly.network/trading \
         @orderly.network/portfolio \
         @orderly.network/markets \
         @orderly.network/wallet-connector \
         @orderly.network/i18n

# Required: EVM wallet support
pnpm add @web3-onboard/injected-wallets @web3-onboard/walletconnect

# Required: Solana wallet support
pnpm add @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

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 (Terminal Trading Only — NOT for DEX Building)

A terminal trading tool (@orderly.network/cli) wrapping the Orderly REST API for CLI-based trading.

⚠️ Memory Warning: Do NOT install @orderly.network/cli in resource-constrained environments (≤1GB RAM). It depends on keytar which triggers native C++ compilation (node-gyp) and will OOM-kill the container. For trading or onboarding via agent, prefer Orderly REST API or the hosted MCP server (https://mcp.orderly.network).

Install & Quick Start (Testnet, local machines with >2GB RAM only):

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

• demo — For testing, development, and personal use. No setup required.
• Custom — Go to dex.orderly.network, select "Custom API integration". Costs $10, requires manual browser interaction (cannot be done via CLI or agent).

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're building a DEX:

1. Fork the DEX Template for the fastest start
2. Install MCP server: npx @orderly.network/mcp-server init
3. Configure your broker settings in .env and customize your theme
4. For more control, load orderly-sdk-install-dependency and orderly-sdk-dex-architecture to build from scratch
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 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 get a custom broker ID at dex.orderly.network ($10, manual browser interaction required)

If you're launching a white-label DEX:

1. Install MCP server for Orderly One API tools: npx @orderly.network/mcp-server init
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

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

For a quick DEX: Fork the DEX Template, configure .env, and deploy. Uses pre-built components — fastest path.

For more control: Install the MCP server first: 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.

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)
• 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?"

Go to dex.orderly.network, select the "Custom API integration" option, and follow the steps. It costs $10. This requires manual browser interaction and cannot be done via CLI or agent. For testing and development, use --broker-id demo — no setup needed.

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

Trade Indexing (Starchild Agents)

Starchild indexes Orderly fills into trade_events via POST {AI_AGENT_API_URL}/v1/trade-events (same pipeline as hyperliquid / polymarket / DEX skills). Two layers — use both:

The private ed25519 /v1/trades endpoint alone is not enough for platform analytics — API-key / SDK trading often binds to the user's personal wallet, not the agent Privy wallet. Always record the wallet that actually executed the trade.

Critical: wallet_address = execution wallet

When reporting, set wallet_address to the address that holds the Orderly account / signed the order — not always the agent Privy wallet.

Wrong address → volume mis-attributed or dropped from agent analytics.

Realtime report after every Orderly trade (required)

After any successful Orderly order / fill (SDK, CLI, REST, or a future trading skill), fire-and-forget report. Never block or fail the trade on reporting errors.

One call, zero follow-up. This is a plain HTTP POST — no LLM call, no extra turn. Do not verify that the report landed, do not retry it, and do not mention it to the user unless it raises. The server dedupes, so a duplicate send is harmless and a lost one is picked up by the daily scan.

from scripts._trade_report import report_trade_events
# or: copy the same helper used by hyperliquid / other trading skills

report_trade_events([{
    "source": "orderly",                 # realtime skill/agent report
    "venue": "orderly:<broker>",         # e.g. orderly:woofi_pro
    "event_type": "fill",                # or "order" if not yet filled
    "wallet_address": execution_wallet,  # MUST be the wallet that traded
    "account_id": orderly_account_id,    # Orderly account_id if known
    "symbol": "PERP_ETH_USDC",
    "side": "buy",                       # buy | sell
    "price": "2500.1",
    "size": "0.5",
    "notional_usd": "1250.05",
    "fee": "0.12",
    "fee_currency": "USDC",
    "order_id": str(order_id),
    "dedupe_key": f"orderly:{account_id}:{trade_id}",  # stable unique
    "occurred_at": "2026-07-15T12:00:00Z",             # ISO8601 UTC
    "raw": {"trade_id": trade_id, "broker": broker},
}])

dedupe_key convention (server unique on (user_id, dedupe_key)):

• Prefer orderly:{account_id}:{trade_id} when trade_id is known
• Else orderly:{execution_wallet_lower}:{order_id}:{fill_index}
• Never emit a key with an empty/None id — archived Public Info rows can lack id/trade_id/match_id, and all such fills would collapse onto one dedupe_key. trade_sync.py falls back to synthetic_trade_id(ts_ms, symbol, side, price, size) (sha1-derived).

Calling from a short-lived script (cron, one-shot sync)? Pass report_trade_events(events, blocking=True). The default background thread is a daemon and is killed when the process exits, so the POST never leaves the machine. Long-lived agent processes keep the default non-blocking mode. Batches larger than 500 events are split automatically.

Source tags used in analytics:

Historical / catch-up sync script

pip install pynacl base58   # one-time
# Agent wallet (default)
python3 scripts/trade_sync.py --broker woofi_pro --days 90
# User's third-party / login wallet that actually trades on Orderly
python3 scripts/trade_sync.py --address 0xUserWallet --broker woofi_pro --days 90
# Force zero-auth Public Info (no private key needed)
python3 scripts/trade_sync.py --address 0xUserWallet --public-only

Env override (same as --address): ORDERLY_WALLET_ADDRESS=0x…

What the script does (idempotent):

1. Resolves execution wallet: --address → ORDERLY_WALLET_ADDRESS → agent EVM.
2. Looks up Orderly account for that address + broker (registers only when the address is the agent wallet and can EIP-712-sign).
3. If a read-scope ed25519 key is available for that account → private GET /v1/trades. Agent wallets can mint a read key via AddOrderlyKey; third-party wallets only use an existing key file (agent cannot sign for another wallet).
4. Else falls back to Public Info POST /v1/public/query {type:trades,address} (zero auth) — covers third-party wallets without keys.
5. Maps fills with wallet_address=<execution wallet> and dedupe_key=orderly:<account_id|address>:<trade_id>, then fire-and-forget reports to /v1/trade-events.

Keys are stored per account at workspace/.orderly_key_<account_prefix>.json (mode 600). Safe to schedule daily; server-side dedupe prevents double-count against both this script and the platform Public Info cron.

After any trade you execute on Orderly, either call report_trade_events immediately (preferred) or run this sync so the fill is indexed. Reporting must never block or fail trading.