---
name: orderly-onboarding
version: 1.0.1
description: Agent onboarding for Orderly Network - omnichain perpetual futures infrastructure, MCP server, skills, and developer quickstart
---

# 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:**

| Use Case              | Description                                                                |
| --------------------- | -------------------------------------------------------------------------- |
| **Builders/DEXes**    | Create your own Perps DEX on EVM and Solana with plug-and-play SDKs        |
| **Perps Aggregators** | Access Orderly's shared liquidity directly via API or SDK                  |
| **Trading Desks**     | Use APIs for CEX-level trading with low latency orderbook                  |
| **Trading Bots**      | Connect to orderbook for best rates, SL/limit orders, gasless transactions |

## 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:**

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

**Supported Clients:**

| Client      | Command             | Config File            |
| ----------- | ------------------- | ---------------------- |
| Claude Code | `--client claude`   | `.mcp.json`            |
| Cursor      | `--client cursor`   | `.cursor/mcp.json`     |
| VS Code     | `--client vscode`   | `.vscode/mcp.json`     |
| Codex       | `--client codex`    | `~/.codex/config.toml` |
| OpenCode    | `--client opencode` | `.opencode/mcp.json`   |

**Manual Configuration:**

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

**Claude Code** (`.mcp.json`):

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

**Cursor** (`.cursor/mcp.json`):

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

**VS Code** (`.vscode/mcp.json`):

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

**OpenCode** (`.opencode/mcp.json`):

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

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

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

**What the MCP Server Provides:**

| Tool                       | Description                                      |
| -------------------------- | ------------------------------------------------ |
| `search_orderly_docs`      | Search Orderly documentation for specific topics |
| `get_sdk_pattern`          | Get code examples for SDK v2 hooks and patterns  |
| `get_contract_addresses`   | Lookup smart contract addresses for any chain    |
| `explain_workflow`         | Step-by-step guides for common tasks             |
| `get_api_info`             | REST API and WebSocket endpoint documentation    |
| `get_indexer_api_info`     | Trading metrics, events, volume statistics       |
| `get_component_guide`      | React UI component building guides               |
| `get_orderly_one_api_info` | DEX creation and management API for Orderly One  |

### Agent Skills

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

**Install all skills globally (recommended):**

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

**Install all skills locally:**

```bash
npx skills add OrderlyNetwork/skills --all
```

**Install specific skills:**

```bash
# 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:**

| Category           | Skill                            | Description                                         |
| ------------------ | -------------------------------- | --------------------------------------------------- |
| **API / Protocol** | `orderly-api-authentication`     | Two-layer auth: EIP-712 (EVM) + Ed25519 (Solana)    |
|                    | `orderly-trading-orders`         | Place, manage, cancel orders via REST API or SDK    |
|                    | `orderly-positions-tpsl`         | Monitor positions, TP/SL, leverage, PnL             |
|                    | `orderly-websocket-streaming`    | Real-time WebSocket for orderbook and executions    |
|                    | `orderly-deposit-withdraw`       | Token deposits, withdrawals, cross-chain operations |
| **SDK / React**    | `orderly-sdk-react-hooks`        | Reference for all React SDK hooks                   |
|                    | `orderly-ui-components`          | Pre-built React UI components                       |
|                    | `orderly-sdk-install-dependency` | Install Orderly SDK packages                        |
|                    | `orderly-sdk-dex-architecture`   | Complete DEX project structure and setup            |
|                    | `orderly-sdk-page-components`    | Pre-built page components                           |
|                    | `orderly-sdk-theming`            | CSS variable theming and customization              |
|                    | `orderly-sdk-trading-workflows`  | End-to-end trading flows                            |
| **Platform**       | `orderly-sdk-wallet-connection`  | Wallet integration for EVM and Solana               |
|                    | `orderly-sdk-debugging`          | Debug/troubleshoot SDK errors                       |
|                    | `orderly-one-dex`                | Create/manage custom DEX with Orderly One API       |

## For Builders (SDK & DEX Development)

Build custom trading interfaces using Orderly's React SDK v2.

### Fastest Way to Get Started

Fork the **[DEX Template](https://github.com/OrderlyNetwork/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. 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:**

```bash
# 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:**

| Network | URL                               |
| ------- | --------------------------------- |
| Mainnet | `https://api.orderly.org`         |
| Testnet | `https://testnet-api.orderly.org` |

**WebSocket URLs:**

| Network | URL                               |
| ------- | --------------------------------- |
| Mainnet | `wss://ws.orderly.org/ws`         |
| Testnet | `wss://testnet-ws.orderly.org/ws` |

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

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):**

```bash
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](https://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:**

| Network          | Address                                        |
| ---------------- | ---------------------------------------------- |
| Ethereum (ERC20) | `0xABD4C63d2616A5201454168269031355f4764337`   |
| EVM Chains (OFT) | `0x4E200fE2f3eFb977d5fd9c430A41531FB04d97B8`   |
| Solana           | `ABt79MkRXUsoHuV2CVQT32YMXQhTparKFjmidQxgiQ6E` |

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

## Key Links

| Resource              | URL                                                                    | Notes                                          |
| --------------------- | ---------------------------------------------------------------------- | ---------------------------------------------- |
| Documentation         | https://orderly.network/docs                                           |                                                |
| SDK Repository        | https://github.com/orderlynetwork/js-sdk                               |                                                |
| DEX Template  | https://github.com/OrderlyNetwork/dex-template       | Fastest start, uses components SDK             |
| MCP Server (npm) | https://www.npmjs.com/package/@orderly.network/mcp-server |
| CLI (npm)        | https://www.npmjs.com/package/@orderly.network/cli        |
| Skills (npm)     | https://www.npmjs.com/package/@orderly.network/skills     |
| Skills.sh        | https://skills.sh                                          |
| DEX Dashboard    | https://dex.orderly.network                               |
| Orderly App      | https://app.orderly.network                               |
| Discord          | https://discord.gg/OrderlyNetwork                         |
| Twitter          | https://twitter.com/OrderlyNetwork                        |

## Recommended Next Steps

**If you're building a DEX:**

1. Fork the **[DEX Template](https://github.com/OrderlyNetwork/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](https://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](https://github.com/OrderlyNetwork/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](https://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