Perps 代码示例

本页内容由 AI 自动翻译，所有内容以英文版本为准。查看英文版 →

Raydium Perps 是 Orderly Network 上的白标部署。 订单簿、匹配引擎和账户状态都运行在 Orderly 上。Raydium SDK v2（@raydium-io/raydium-sdk-v2）不涵盖 Perps — 如需以编程方式访问，请直接使用 Orderly 的 REST + WebSocket API。下面的代码片段展示了最常见的流程；规范参考是 Orderly API 介绍，其中包含 REST 端点和 WebSocket 流的文档。

版本信息。

后端：Orderly Network REST + WebSocket API
代码片段架构已根据 Orderly API（截至 2026-04）验证
链上存入的 Solana 集群：mainnet-beta
签名：Solana ed25519 对 Orderly EIP-712 风格的负载（Orderly 即使在非 EVM 链上也使用 EIP-712 架构；查看 Orderly 文档了解最新字段列表）

Orderly 的 API 表面在不断演变；在将这些代码片段复制到生产环境之前，请检查 Orderly API 文档。

本页内容

下面的流程涵盖了集成商相关的生命周期：

账户设置 — 存入 USDC 并向 Orderly 注册账户。
认证 REST 调用 — 请求签名以进行订单下单、取消和账户查询。
交易 — 下市价单/限价单、取消、获取持仓和成交。
市场数据 — 订阅订单簿和交易 WebSocket。
提现 — 启动提现回钱包。

这些代码片段针对 Node.js + TypeScript，使用 @solana/web3.js 和 tweetnacl 进行 Ed25519 签名。它们是起点 — Orderly 的 API 表面很广，变化速度比本页快；在发布生产代码之前，始终检查 Orderly 的实时文档。

设置

import { Connection, Keypair, PublicKey, clusterApiUrl } from "@solana/web3.js";
import nacl from "tweetnacl";
import bs58 from "bs58";
import fs from "node:fs";

// 1. Solana 钱包 — 拥有 USDC，签署存入/提现交易。
const connection = new Connection(process.env.RPC_URL ?? clusterApiUrl("mainnet-beta"));
const owner = Keypair.fromSecretKey(
  new Uint8Array(JSON.parse(fs.readFileSync(process.env.KEYPAIR!, "utf8"))),
);

// 2. Orderly 交易密钥 — 用于签署 API 请求的独立 Ed25519 密钥对。
//    不是 Solana 钱包。生成一次，保密，在会话间重复使用。
const orderlyKey = nacl.sign.keyPair();   // ed25519
const orderlyPubB58 = "ed25519:" + bs58.encode(orderlyKey.publicKey);

// 3. Orderly 基础 URL。Raydium 使用 Orderly 的主网主机。
const ORDERLY_BASE = "https://api.orderly.org";
const BROKER_ID    = "raydium";   // Raydium 在 Orderly 上的代理命名空间
const CHAIN_ID     = "solana";    // 用于跨链账户注册

Orderly 交易密钥不是你的钱包密钥对。它是一个请求签名密钥，你在首次使用时向钱包注册；你可以在不触及资金的情况下轮换它。将其视为会话凭证。

账户注册

在下任何订单之前，向 Orderly 注册钱包：

import { encodeUserSettlement } from "./eip712-helpers"; // 查看 Orderly 文档了解确切的负载

// 1. 从 Orderly 请求注册 nonce。
const nonceResp = await fetch(`${ORDERLY_BASE}/v1/registration_nonce`).then(r => r.json());
const registrationNonce = nonceResp.data.registration_nonce;

// 2. 用 Solana 钱包签署注册负载（Solana 上的 EIP-712 风格
//    实现为结构化消息；Orderly 的 SDK 提供编码器）。
const payload = encodeUserSettlement({
  brokerId: BROKER_ID,
  chainId: CHAIN_ID,
  registrationNonce,
  timestamp: Date.now(),
});
const walletSig = nacl.sign.detached(Buffer.from(payload), owner.secretKey);

// 3. 注册，包括 Orderly Ed25519 交易密钥。
const reg = await fetch(`${ORDERLY_BASE}/v1/register_account`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    message: payload,
    signature: bs58.encode(walletSig),
    userAddress: owner.publicKey.toBase58(),
    orderlyKey: orderlyPubB58,
  }),
}).then(r => r.json());

console.log("Account ID:", reg.data.account_id);

账户 ID 对于每个 (broker_id, wallet_address) 对是确定性的 — 注册是幂等的。如果钱包已经向 Raydium 的代理注册，调用返回相同的账户 ID 而不创建新账户。

存入 USDC

存入将 USDC 从钱包 ATA 移动到 Orderly 的结算金库。它们是链上 Solana 交易：

// 使用 Orderly 的 Solana 程序构建存入指令（金库程序 ID 在
// 他们的文档中发布；动态拉取而不是硬编码）。
const vaultProgramId = new PublicKey("<orderly_solana_vault_program_id>");

const depositIx = await buildOrderlyDepositIx({
  vaultProgramId,
  user: owner.publicKey,
  brokerId: BROKER_ID,
  amountUsdc: BigInt(100_000_000),    // 100 USDC（6 位小数）
});

const tx = new Transaction().add(depositIx);
const sig = await connection.sendTransaction(tx, [owner]);
await connection.confirmTransaction(sig, "confirmed");
console.log("Deposit tx:", sig);

约 30 秒后，Orderly 的中继器索引存入，余额显示在账户的可用保证金下。查询 /v1/client/holding 确认：

const holdingResp = await orderlyAuthGet("/v1/client/holding");
console.log("Balances:", holdingResp.data.holding);

（orderlyAuthGet 定义如下 — 每个认证调用都通过它。）

请求签名辅助函数

每个对 Orderly 的认证 REST 调用都携带一个 Ed25519 签名，覆盖 (timestamp + method + path + body)：

async function orderlyAuthRequest(
  method: "GET" | "POST" | "PUT" | "DELETE",
  path: string,
  body?: unknown,
): Promise<any> {
  const ts   = Date.now().toString();
  const json = body ? JSON.stringify(body) : "";
  const msg  = `${ts}${method}${path}${json}`;
  const sig  = nacl.sign.detached(Buffer.from(msg), orderlyKey.secretKey);

  const resp = await fetch(ORDERLY_BASE + path, {
    method,
    headers: {
      "Content-Type": "application/json",
      "orderly-account-id":  /* 注册的 account_id */ "",
      "orderly-key":         orderlyPubB58,
      "orderly-signature":   bs58.encode(sig),
      "orderly-timestamp":   ts,
    },
    body: json || undefined,
  });
  return resp.json();
}

const orderlyAuthGet  = (p: string)            => orderlyAuthRequest("GET",  p);
const orderlyAuthPost = (p: string, b: object) => orderlyAuthRequest("POST", p, b);
const orderlyAuthDel  = (p: string)            => orderlyAuthRequest("DELETE", p);

重放保护：timestamp 与服务器时钟偏差超过 5 秒的请求被拒绝。同步你的时钟（NTP）并避免提前签署请求。

下市价单

const marketResp = await orderlyAuthPost("/v1/order", {
  symbol:        "PERP_SOL_USDC",
  order_type:    "MARKET",
  side:          "BUY",
  order_quantity: 1.0,        // 1 SOL 的持仓
  reduce_only:    false,
});

if (marketResp.success) {
  console.log("Order ID:", marketResp.data.order_id);
} else {
  console.error("Reject:", marketResp.message);
}

市价单立即执行。响应返回生成的 order_id 加上状态。成交通过 WebSocket 传来（见下文）；REST 响应本身不会阻塞直到完全成交。

下限价单（仅做市）

const limitResp = await orderlyAuthPost("/v1/order", {
  symbol:         "PERP_SOL_USDC",
  order_type:     "LIMIT",
  side:           "SELL",
  order_quantity: 0.5,
  order_price:    140.50,
  // 标志组合：
  // post_only: true 使这成为仅做市订单 — 如果会穿过则取消。
  // reduce_only / time_in_force 可独立设置。
  post_only:      true,
});
console.log(limitResp);

对于 IOC / FOK，设置 time_in_force: "IOC" 或 "FOK"。查看 products/perps/order-types 了解每个标志的语义。

取消订单

// 按订单 ID
await orderlyAuthDel(`/v1/order?order_id=${orderId}&symbol=PERP_SOL_USDC`);

// 取消一个交易对上的所有订单
await orderlyAuthDel(`/v1/orders?symbol=PERP_SOL_USDC`);

取消同步确认，但实际取消可能与成交竞争。始终通过轮询 /v1/orders 或观察 WebSocket 进行协调 — 假设取消成功而不确认可能导致重复或意外持仓。

获取开仓持仓

const posResp = await orderlyAuthGet("/v1/positions");
for (const p of posResp.data.rows) {
  console.log(
    p.symbol,
    "size:",  p.position_qty,
    "entry:", p.average_open_price,
    "unrealized:", p.unsettled_pnl,
  );
}

负的 position_qty 是空头，正的是多头。position_qty == 0 意味着持仓已平但行可能仍显示直到下次清理。

获取成交历史

const fills = await orderlyAuthGet(
  "/v1/trades?symbol=PERP_SOL_USDC&start_t=" + (Date.now() - 86_400_000)
);
for (const t of fills.data.rows) {
  console.log(t.executed_timestamp, t.side, t.executed_quantity, "@", t.executed_price);
}

时间参数是毫秒 Unix 时间戳。默认页面大小是 25 行；使用 page 和 size 查询参数进行分页。

WebSocket：市场数据

import WebSocket from "ws";

const ws = new WebSocket(`wss://ws.orderly.org/ws/stream/${accountId}`);

ws.on("open", () => {
  // 公开市场数据：一个交易对的订单簿增量 + 交易
  ws.send(JSON.stringify({ id: "ob1", topic: "orderbook@PERP_SOL_USDC" }));
  ws.send(JSON.stringify({ id: "tr1", topic: "trade@PERP_SOL_USDC" }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.topic?.startsWith("orderbook@")) {
    // 深度增量：{ bids: [[price, qty], ...], asks: [[price, qty], ...] }
    applyOrderbookDelta(msg.data);
  } else if (msg.topic?.startsWith("trade@")) {
    console.log("trade:", msg.data);
  }
});

对于私有流（你的成交、持仓更新、余额变化），WebSocket 必须经过认证。发送一个 subscribe 负载，用与 REST 请求相同的方式签署，作用域限于你的账户 ID。Orderly 的文档有确切的负载形状；它偶尔会变化，所以不要在这里硬编码特定的架构。

提现 USDC

// 1. 请求提现。
const wRes = await orderlyAuthPost("/v1/withdraw_request", {
  token:  "USDC",
  chain_id: CHAIN_ID,
  amount: 50.0,                          // 人类单位
  receiver: owner.publicKey.toBase58(),
});

console.log("Withdrawal request id:", wRes.data.withdraw_id);

Orderly 将提现中继到链上的接收者地址。有一个固定的 1 USDC 提现费（查看 products/perps/fees）。链上转账在正常条件下在 1-2 分钟内发生；在拥塞期间预期更长。

陷阱

不要在环境间重复使用交易密钥。 针对你的钱包注册的单个 Orderly 交易密钥与一个 Solana 主网账户关联。如果你还需要 devnet 或 staging，为每个生成一个单独的密钥。
时间同步。 Orderly 的时钟偏差容限很紧（±5 秒）。在长期运行的服务上，NTP 漂移最终会破坏签名。定期重新同步。
WebSocket 重连。 公开 WS 在 Orderly 升级期间偶尔会断开连接。实现指数退避并在重新打开时重新订阅。
速率限制。 REST 调用按账户进行分层速率限制。当你有 >5 个订单要取消时，通过 cancel_all 进行批量取消，而不是循环 cancel-by-id。
持仓方向是隐含的。 PERP_SOL_USDC 上的 BUY 订单开仓或扩展多头；SELL 开仓或扩展空头 — 但如果你已经是多头，SELL 减少（并可能翻转）持仓，因为 Raydium Perps 是单向模式。如果方向重要，在下单前始终检查当前持仓。
资金费和清算与订单流分离。 资金费支付和清算显示为单独的事件流；它们不是「订单」。如果你需要观察它们，订阅相关的私有 WS 主题。

下一步

products/perps/trading-basics — 永续合约机制的概念入门。
products/perps/order-types — 每种订单类型和标志的语义。
products/perps/collateral — 支持的抵押资产和每条链的限制。
products/perps/fees — 做市商/接单者费率表和提现费。

来源：

Orderly Network 开发者文档 — 上面使用的 API 表面的规范参考。Raydium Perps 直接使用这个。
Orderly 支持的链 — 确认 Solana 的状态和每条链的结算金库地址。
OrderlyNetwork/orderly-sdk-js — 同一 REST 层上的社区可见 JS 包装器。它 没有发布版本 且没有声明的维护政策，所以将其视为参考代码而不是依赖；上面的签名层足够小，可以自己拥有。

产品

算法

本页内容

设置

账户注册

存入 USDC

请求签名辅助函数

下市价单

下限价单（仅做市）

取消订单

获取开仓持仓

获取成交历史

WebSocket：市场数据

提现 USDC

陷阱

下一步

​本页内容

​设置

​账户注册

​存入 USDC

​请求签名辅助函数

​下市价单

​下限价单（仅做市）

​取消订单

​获取开仓持仓

​获取成交历史

​WebSocket：市场数据

​提现 USDC

​陷阱

​下一步

本页内容

设置

账户注册

存入 USDC

请求签名辅助函数

下市价单

下限价单（仅做市）

取消订单

获取开仓持仓

获取成交历史

WebSocket：市场数据

提现 USDC

陷阱

下一步