Orderly Network: API Authentication
This skill covers both authentication layers in Orderly Network: wallet signatures (EIP-712 for EVM, Ed25519 message signing for Solana) for account registration and key management, and Ed25519 signatures for API request authentication.
When to Use
- - Setting up new Orderly accounts and API keys (EVM or Solana)
- Building server-side trading bots
- Implementing direct API calls
- Understanding the two-layer authentication flow
- Debugging signature issues
Prerequisites
- - A Web3 wallet (MetaMask, WalletConnect for EVM; Phantom, Solflare for Solana)
- A Broker ID (e.g.,
woofi_dex, or your own) - Node.js 18+ installed (for programmatic usage)
- Understanding of EIP-712 typed data signing (EVM) or Ed25519 message signing (Solana) and Ed25519 cryptography
Authentication Overview
Orderly Network uses a two-layer authentication system supporting both EVM and Solana wallets:
CODEBLOCK0
Authentication Flow
CODEBLOCK1
Environment Configuration
| Environment | API Base URL | WebSocket URL |
|---|
| Mainnet | INLINECODE1 | INLINECODE2 |
| Testnet |
https://testnet-api.orderly.org |
wss://testnet-ws.orderly.org/ws/stream |
Note: These API base URLs work for both EVM and Solana wallets. Orderly's API is omnichain - the same endpoints handle both chains.
Getting Supported Chains
Don't hardcode chain IDs. Fetch them dynamically for your broker:
CODEBLOCK2
EIP-712 Domain Configuration
Orderly uses two different EIP-712 domains depending on the operation:
| Domain Type | Use Case | Mainnet | Testnet |
|---|
| Off-chain | Account registration, API key management | INLINECODE5 | INLINECODE6 |
| On-chain |
Withdrawals, internal transfers, settle PnL |
0x6F7a338F2aA472838dEFD3283eB360d4Dff5D203 |
0x1826B75e2ef249173FC735149AE4B8e9ea10abff |
Important: The on-chain verifyingContract is the Ledger contract on Orderly L2. This is a single contract for all chains (not per-chain). Vault contracts exist on each supported EVM chain for deposits, but the Ledger is the source of truth for on-chain operations.
Off-Chain Domain (Registration, API Keys)
Used for operations that don't directly interact with smart contracts:
CODEBLOCK3
On-Chain Domain (Withdrawals, Transfers)
Used for operations that interact with the Ledger contract on Orderly L2:
CODEBLOCK4
Part 1: EIP-712 Wallet Authentication
Wallet authentication is required for account-level operations that need proof of ownership.
When to Use EIP-712
- - Account Registration: Creating a new Orderly account
- API Key Management: Adding or removing Ed25519 API keys
- Withdrawals: Requesting token withdrawals from the vault
- Admin Operations: Setting IP restrictions, managing account settings
Account Registration
Step 1: Check Existing Account
Before registration, verify if the wallet already has an account:
CODEBLOCK5
Step 2: Fetch Registration Nonce
Retrieve a unique nonce required for registration (valid for 2 minutes):
CODEBLOCK6
Step 3: Sign Registration Message
Create and sign an EIP-712 typed message:
CODEBLOCK7
Step 4: Submit Registration
Send the signed payload to create the Orderly Account ID:
CODEBLOCK8
API Key Management (Orderly Key)
Once you have an account, you need to register Ed25519 keys for API access.
Generate Ed25519 Key Pair
CODEBLOCK9
Sign Add Orderly Key Message
Associate the Ed25519 key with your account via EIP-712:
CODEBLOCK10
Submit Orderly Key
Register the API key:
CODEBLOCK11
Orderly Key Scopes
When registering an API key, specify permissions:
| Scope | Permissions |
|---|
| INLINECODE10 | Read positions, orders, balance |
| INLINECODE11 |
Place, cancel, modify orders |
|
asset | Deposit, withdraw, internal transfer |
Multiple scopes can be combined comma-separated: INLINECODE13
Remove Orderly Key
To remove a key (requires Ed25519 authentication with another valid key):
CODEBLOCK12
Solana Wallet Authentication
Solana wallets use native Ed25519 message signing (not EIP-712) for account operations. Solana wallets already use Ed25519 keys natively, making the signing process simpler but requiring different message formatting.
Solana vs EVM Authentication
| Aspect | EVM Wallets | Solana Wallets |
|---|
| Signing Method | EIP-712 typed data | Plain message signing |
| Key Type |
secp256k1 | Ed25519 (native) |
|
Account Lookup |
/v1/get_account |
/v1/get_account?chain_type=SOL |
|
Message Format | Structured JSON types | Raw bytes via adapter |
|
Signature | Ethereum signature | Ed25519 signature |
Account Lookup
Check if a Solana wallet already has an Orderly account:
CODEBLOCK13
Message Signing with Solana Adapter
Orderly provides a Solana adapter to generate properly formatted messages:
CODEBLOCK14
Registration Flow
Step 1: Fetch Registration Nonce
CODEBLOCK15
Step 2: Generate and Sign Registration Message
CODEBLOCK16
Step 3: Submit Registration
CODEBLOCK17
API Key Management (Orderly Key)
Generate Ed25519 Key Pair
Same as EVM - locally generate an Ed25519 key pair:
CODEBLOCK18
Sign Add Orderly Key Message
CODEBLOCK19
Submit Orderly Key
CODEBLOCK20
Withdrawal Signing
Withdrawals require wallet signature on both EVM and Solana:
CODEBLOCK21
Settle PnL Signing
CODEBLOCK22
Solana-Specific Configuration
| Environment | Solana Chain ID | Solana Cluster | Orderly Vault Address | Verifying Contract |
|---|
| Mainnet | 900900900 | INLINECODE16 | INLINECODE17 | INLINECODE18 |
| Testnet |
901901901 |
devnet |
9shwxWDUNhtwkHocsUAmrNAQfBH2DHh4njdAEdHZZkF2 |
0x1826B75e2ef249173FC735149AE4B8e9ea10abff |
Note: API base URLs are the same for EVM and Solana. See the Environment Configuration section at the top of this skill.
Important Differences
Account ID Generation
- - EVM: INLINECODE22
- Solana: Returned from
/v1/get_account API (not a hash)
Message Signing
- - EVM: Uses
eth_signTypedData_v4 with structured EIP-712 types - Solana: Uses raw message bytes signed with Ed25519
No Domain Separator
Solana doesn't use EIP-712 domain configuration:
CODEBLOCK23
Part 2: Ed25519 API Authentication
Once you have registered an Ed25519 key via wallet signing (EIP-712 for EVM or Ed25519 message signing for Solana), you use that key for all API operations.
Required Headers
| Header | Description |
|---|
| INLINECODE25 | Unix timestamp in milliseconds |
| INLINECODE26 |
Your Orderly account ID |
|
orderly-key | Your public key prefixed with
ed25519: |
|
orderly-signature | Base64url-encoded Ed25519 signature |
Generating Ed25519 Key Pair
CODEBLOCK24
Signing Requests
Message Construction
CODEBLOCK25
Creating the Signature
CODEBLOCK26
Sign and Send Request Helper
For a simple, standalone authentication helper that always works correctly with query parameters and proper Content-Type headers:
CODEBLOCK27
This helper function:
- - Properly parses the URL to extract both pathname and search (query) parameters
- Correctly sets Content-Type based on HTTP method (GET/DELETE use
application/x-www-form-urlencoded, others use application/json) - Constructs the signature message with timestamp + method + pathname + search + body
- Returns the fetch response for further processing
Usage Examples
CODEBLOCK28
Error Handling Helper
CODEBLOCK29
Query Parameters
Query parameters must be included in the signature message. The URL is parsed to extract both pathname and search parameters:
CODEBLOCK30
Common Errors
Signature Mismatch (Code 10016)
CODEBLOCK31
Timestamp Expired (Code 10017)
CODEBLOCK32
Invalid Orderly Key (Code 10019)
CODEBLOCK33
Orderly Key Scopes
When registering an API key, specify permissions:
| Scope | Permissions |
|---|
| INLINECODE32 | Read positions, orders, balance |
| INLINECODE33 |
Place, cancel, modify orders |
|
asset | Deposit, withdraw, internal transfer |
CODEBLOCK34
Security Best Practices
Store Private Keys Securely
CODEBLOCK35
Key Rotation
Rotate your API keys periodically for security:
CODEBLOCK36
IP Restrictions
CODEBLOCK37
WebSocket Authentication
WebSocket also requires Ed25519 authentication:
CODEBLOCK38
Testing Authentication
CODEBLOCK39
Supported Chains
| Chain | Chain ID | Mainnet | Testnet |
|---|
| Arbitrum | 42161 / 421614 | ✅ | ✅ |
| Optimism |
10 / 11155420 | ✅ | ✅ |
| Base | 8453 / 84532 | ✅ | ✅ |
| Ethereum | 1 / 11155111 | ✅ | ✅ |
| Solana | 900900900 / 901901901 | ✅ | ✅ |
| Mantle | 5000 / 5003 | ✅ | ✅ |
Common Issues
EIP-712 Errors
"Nonce expired" error
- - Nonces are valid for 2 minutes only
- Fetch a new nonce and retry
"Account already exists" error
- - The wallet is already registered with this broker
- Use
/v1/get_account to retrieve existing account info
"Invalid signature" error
- - Ensure the EIP-712 domain matches exactly (name, version, chainId, verifyingContract)
- Check chain ID matches your network
- Verify the message structure matches the types
- Use
eth_signTypedData_v4 not INLINECODE37
Ed25519 Errors
Signature Mismatch (Code 10016)
CODEBLOCK40
Timestamp Expired (Code 10017)
CODEBLOCK41
Invalid Orderly Key (Code 10019)
CODEBLOCK42
Authentication Comparison
| Aspect | EIP-712 Wallet Auth | Ed25519 API Auth |
|---|
| Purpose | Account operations, key management | Trading, reading data |
| Signer |
User's Web3 wallet | Locally-generated Ed25519 key |
|
Key type | Ethereum private key | Ed25519 key pair |
|
Endpoints |
/v1/register_account,
/v1/orderly_key | All other endpoints |
|
Signature type | EIP-712 typed data | Raw Ed25519 + base64url |
|
Scope | Create/manage API keys | Use API keys for trading |
Related Skills
- - orderly-trading-orders - Using authenticated endpoints
- orderly-websocket-streaming - WebSocket authentication
- orderly-sdk-react-hooks - React SDK for simplified auth
- orderly-deposit-withdraw - Fund your account
Orderly Network: API 认证
本技能涵盖 Orderly Network 中的两层认证：钱包签名（EVM 的 EIP-712，Solana 的 Ed25519 消息签名）用于账户注册和密钥管理，以及 Ed25519 签名用于 API 请求认证。
何时使用
- - 设置新的 Orderly 账户和 API 密钥（EVM 或 Solana）
- 构建服务器端交易机器人
- 实现直接 API 调用
- 理解两层认证流程
- 调试签名问题
前置条件
- - 一个 Web3 钱包（EVM：MetaMask、WalletConnect；Solana：Phantom、Solflare）
- 一个经纪商 ID（例如 woofi_dex，或您自己的）
- 已安装 Node.js 18+（用于编程使用）
- 理解 EIP-712 类型化数据签名（EVM）或 Ed25519 消息签名（Solana）以及 Ed25519 密码学
认证概述
Orderly Network 使用两层认证系统，支持 EVM 和 Solana 钱包：
┌─────────────────────────────────────────────────────────────┐
│ 第 1 层：钱包认证 │
│ ───────────────────────────── │
│ • 账户注册 │
│ • API 密钥管理（添加/删除密钥） │
│ • 特权操作（提现、管理） │
│ │
│ EVM：EIP-712 类型化数据签名 │
│ Solana：Ed25519 消息签名 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 第 2 层：API 认证（Ed25519） │
│ ───────────────────────────────────── │
│ • 交易操作（下单/撤单） │
│ • 读取账户数据（持仓、余额） │
│ • WebSocket 连接 │
│ │
│ 签名者：Ed25519 密钥对 │
│ 密钥类型：本地生成的 Ed25519 密钥对 │
└─────────────────────────────────────────────────────────────┘
认证流程
- 1. 用户连接钱包
- 钱包签署 EIP-712 消息以注册账户
- 创建账户 ID
- 用户生成 Ed25519 密钥对
- 钱包签署 EIP-712 消息以授权 Ed25519 密钥
- Ed25519 密钥用于所有后续 API 调用
环境配置
| 环境 | API 基础 URL | WebSocket URL |
|---|
| 主网 | https://api.orderly.org | wss://ws.orderly.org/ws/stream |
| 测试网 |
https://testnet-api.orderly.org | wss://testnet-ws.orderly.org/ws/stream |
注意：这些 API 基础 URL 适用于 EVM 和 Solana 钱包。Orderly 的 API 是跨链的——相同的端点处理两条链。
获取支持的链
不要硬编码链 ID。为您的经纪商动态获取它们：
typescript
// 获取您的经纪商支持的链
const response = await fetch(https://api.orderly.org/v1/public/chaininfo?brokerid=${BROKER_ID});
const { data } = await response.json();
// data.chains 包含支持的 chain_ids
// 将这些链 ID 用于 EIP-712 域配置
EIP-712 域配置
Orderly 根据操作使用两个不同的 EIP-712 域：
| 域类型 | 用例 | 主网 | 测试网 |
|---|
| 链下 | 账户注册、API 密钥管理 | 0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC | 0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC |
| 链上 |
提现、内部转账、结算盈亏 | 0x6F7a338F2aA472838dEFD3283eB360d4Dff5D203 | 0x1826B75e2ef249173FC735149AE4B8e9ea10abff |
重要：链上的 verifyingContract 是 Orderly L2 上的账本合约。这是所有链的单一合约（非每条链独立）。每个支持的 EVM 链上都有用于存款的金库合约，但账本是链上操作的真相来源。
链下域（注册、API 密钥）
用于不直接与智能合约交互的操作：
typescript
const OFFCHAIN_DOMAIN = {
name: Orderly,
version: 1,
chainId: 421614, // 连接的链 ID（例如 Arbitrum Sepolia）
verifyingContract: 0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC,
};
链上域（提现、转账）
用于与 Orderly L2 上的账本合约交互的操作：
typescript
const ONCHAIN_DOMAIN = {
name: Orderly,
version: 1,
chainId: 42161, // 连接的链 ID
verifyingContract: isTestnet
? 0x1826B75e2ef249173FC735149AE4B8e9ea10abff
: 0x6F7a338F2aA472838dEFD3283eB360d4Dff5D203,
};
第 1 部分：EIP-712 钱包认证
需要所有权证明的账户级操作需要钱包认证。
何时使用 EIP-712
- - 账户注册：创建新的 Orderly 账户
- API 密钥管理：添加或删除 Ed25519 API 密钥
- 提现：从金库请求代币提现
- 管理操作：设置 IP 限制、管理账户设置
账户注册
第 1 步：检查现有账户
注册前，验证钱包是否已有账户：
typescript
const BROKERID = woofidex; // 您的经纪商 ID
const walletAddress = 0x...; // 用户的钱包地址
const response = await fetch(
https://testnet-api.orderly.org/v1/getaccount?brokerid=${BROKERID}&useraddress=${walletAddress}
);
const data = await response.json();
// 如果 data.success 为 true，则账户已存在
// 如果不是，则继续注册
第 2 步：获取注册随机数
检索注册所需的唯一随机数（有效期为 2 分钟）：
typescript
const nonceResponse = await fetch(https://testnet-api.orderly.org/v1/registration_nonce);
const { data: nonce } = await nonceResponse.json();
console.log(注册随机数:, nonce);
第 3 步：签署注册消息
创建并签署 EIP-712 类型化消息：
typescript
// 注册消息类型
const REGISTRATION_TYPES = {
Registration: [
{ name: brokerId, type: string },
{ name: chainId, type: uint256 },
{ name: timestamp, type: uint64 },
{ name: registrationNonce, type: uint256 },
],
};
// 创建消息
const registerMessage = {
brokerId: BROKER_ID,
chainId: 421614,
timestamp: Date.now(),
registrationNonce: nonce,
};
// 使用钱包签署（例如 MetaMask）- 注册使用 OFFCHAIN_DOMAIN
const signature = await window.ethereum.request({
method: ethsignTypedDatav4,
params: [
walletAddress,
{
types: REGISTRATION_TYPES,
domain: OFFCHAIN_DOMAIN,
message: registerMessage,
primaryType: Registration,
},
],
});
第 4 步：提交注册
发送已签名的负载以创建 Orderly 账户 ID：
typescript
const registerResponse = await fetch(https://testnet-api.orderly.org/v1/register_account, {
method: POST,
headers: {
Content-Type: application/json,
},
body: JSON.stringify({
message: registerMessage,
signature: signature,
userAddress: walletAddress,
}),
});
const result = await registerResponse.json();
console.log(账户 ID:, result.data.account_id);
// 存储此账户 ID - API 认证时需要
API 密钥
