---
name: orderly-onboarding
description: Agent onboarding for Orderly Network - infrastructure overview, agent tools, quickstart, and programmatic broker ID creation via x402
---

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

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

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

| Tool                          | Description                                        |
| ----------------------------- | -------------------------------------------------- |
| `search_orderly_docs`         | Search Orderly docs and type-accurate SDK symbols  |
| `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    |
| `get_strategy_vault_api_info` | Strategy Vault API: yield strategies and providers |
| `get_public_info_api_info`    | Zero-auth Public Info API: market/account data     |

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

> **Default rule for agents:** when a user wants a DEX, start from the **[DEX Template](https://github.com/OrderlyNetwork/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](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. 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:**

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

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

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

| Option            | Cost               | Setup                                           | Revenue     |
| ----------------- | ------------------ | ----------------------------------------------- | ----------- |
| **`demo`**        | Free               | None — use `demo` in your config                | None        |
| **Custom broker** | 10 USDC (one-time) | Self-service via Orderly One API + x402 payment | Fee sharing |

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

| #   | Step                                             | Call                                                                                                                                    |
| --- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| 1   | Authenticate (EIP-191 `personal_sign`, EVM only) | `POST /api/auth/nonce` `{address}` → sign the returned message → `POST /api/auth/verify` `{address, signature}` → Bearer JWT (24h)      |
| 2   | Create DEX record                                | `POST /api/dex` (multipart): `brokerName` (3-30 chars), `integrationType: "custom"` — no hosted frontend needed                         |
| 3   | Check the fee                                    | `GET /api/graduation/fee-options` → `{ usdc: { amount }, receiverAddress, payerAddress }` — `payerAddress` must be your wallet          |
| 4   | Pay fee + register broker (one request)          | `POST /api/graduation/graduate?brokerId=…&makerFee=…&takerFee=…&rwaMakerFee=…&rwaTakerFee=…` with Bearer — x402 payment, auto-finalizes |
| 5   | Register wallet as broker admin                  | `GET https://api.orderly.org/v1/registration_nonce` → EIP-712 sign → `POST /v1/register_account` (see **orderly-api-authentication**)   |
| 6   | Finalize                                         | `POST /api/graduation/finalize-admin-wallet` with empty body `{}` + Bearer                                                              |
| 7   | Verify                                           | `GET /api/graduation/graduation-status` until `isGraduated: true`; `GET /api/leaderboard/broker/{brokerId}`                             |

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

| 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 (Remote)  | https://mcp.orderly.network                               | No install needed                  |
| MCP Server (npm)     | https://www.npmjs.com/package/@orderly.network/mcp-server | Local install                      |
| 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 One API spec | https://dex-api.orderly.network/openapi.json              | Agent quickstart inside            |
| Orderly App          | https://app.orderly.network                               |
| Discord              | https://discord.gg/OrderlyNetwork                         |
| Twitter              | https://twitter.com/OrderlyNetwork                        |

## 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](https://github.com/OrderlyNetwork/dex-template) — see **For Builders**

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

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