订单生命周期¶

本教程将引导您了解 Sera 上限价单的完整生命周期 — 从下单到领取收益。

概述¶

sequenceDiagram
    participant User
    participant API as Sera API
    participant Chain as Ethereum

    User->>API: POST /orders (signed order)
    API-->>User: order_id
    Note over API: Order is matched<br/>when counterparty found
    API->>Chain: Settlement on-chain
    User->>API: GET /orders/{id}
    API-->>User: Status: settled
    Note over User: Proceeds available<br/>in vault balance

第 1 步：检查服务器时间¶

在创建签名之前，与服务器时钟同步以避免过期问题：

JavaScriptPython

const timeRes = await fetch('https://api.sera.cx/api/v1/system/time');
const { timestamp } = await timeRes.json();
console.log('Server time:', timestamp);

import requests

time_res = requests.get("https://api.sera.cx/api/v1/system/time")
server_time = time_res.json()["timestamp"]
print(f"Server time: {server_time}")

所有已签名订单都必须带 expiration，并且 API 会强制执行 now < expiration <= now + 365 天 - 300 秒。请使用服务器时间，而不是只依赖浏览器或本地系统时钟。

第 2 步：查询可用代币¶

获取支持的代币列表以找到您需要的合约地址：

const tokensRes = await fetch('https://api.sera.cx/api/v1/tokens');
const { tokens } = await tokensRes.json();

// 查找 USDC 和 EURC 地址
const usdc = tokens.find(t => t.symbol === 'USDC');
const eurc = tokens.find(t => t.symbol === 'EURC');

第 3 步：下限价单¶

构造并签署 EIP-712 Order，然后提交：

import { ethers } from 'ethers';
import { v4 as uuidv4 } from 'uuid';

// Generate a unique order ID
const orderId = uuidv4();
const { executor_id: executorId } = await fetch('https://api.sera.cx/api/v1/health')
  .then(r => r.json());
const rawOrderId = BigInt(`0x${orderId.replace(/-/g, '')}`);
const groupId = rawOrderId >> 16n;
const uuidInt = ((BigInt(executorId) << 252n) | (rawOrderId << 124n) | (groupId << 12n)).toString();

// 构造订单。from_address 是市场基础代币，to_address 是报价代币。
// 最终支出哪一边由 side 决定。
const order = {
  owner_address: walletAddress,
  side: 'bid',                // Buy EURC with USDC
  amount: '1000.0',           // 1000 EURC
  price: '1.085',             // At 1.085 USDC per EURC
  order_type: 'limit',
  from_address: EURC_ADDRESS, // 市场基础代币，也是您要买入的代币
  to_address: USDC_ADDRESS,   // 市场报价代币，在 bid 中是您支出的代币
  order_id: orderId,
  uuid_int: uuidInt,
  expiration: Math.floor(Date.now() / 1000) + 86400,  // 24 hours
};

// Sign with EIP-712 (see Authentication docs for full signing details)
const signature = await signOrder(signer, order);

// Submit the order
const response = await fetch('https://api.sera.cx/api/v1/orders', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ ...order, signature })
});

const result = await response.json();
console.log('Order placed:', result.order_id);

第 4 步：监控订单状态¶

使用您的 API 密钥轮询订单状态：

const statusRes = await fetch(
  `https://api.sera.cx/api/v1/orders/${orderId}`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY:YOUR_API_SECRET' } }
);

const status = await statusRes.json();
console.log('Status:', status.status);
// 外部状态："pending"、"matched"、"settled"、"cancelled"、"failed"
console.log('Filled:', status.filled_amount);
console.log('Signed uuid_int:', status.uuid_int);

第 5 步：查看余额¶

订单结算后，收益会出现在您的 Vault 余额中：

const balanceRes = await fetch(
  'https://api.sera.cx/api/v1/balances?owner_address=' + walletAddress,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY:YOUR_API_SECRET' } }
);

const balances = await balanceRes.json();
for (const bal of balances.balances) {
  console.log(`${bal.symbol}: vault_raw=${bal.vault_available}, frozen_raw=${bal.vault_frozen}, decimals=${bal.decimals}`);
}

GET /balances 现在返回原始 uint256 十进制字符串。展示给用户前，请结合每一行的 decimals 字段自行转换。

第 6 步：取消订单（可选）¶

如果您想取消未成交或部分成交的订单：

// Sign a CancelOrder message
const cancelSignature = await signCancelOrder(signer, walletAddress, status.uuid_int);

const cancelRes = await fetch('https://api.sera.cx/api/v1/orders/cancel', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    owner_address: walletAddress,
    order_id: orderId,
    uuid_int: status.uuid_int,
    signature: cancelSignature
  })
});

console.log('Cancelled:', await cancelRes.json());

Note

所有用户都受 5 分钟冷却期限制 — 订单必须至少存在 5 分钟后才能取消。

第 7 步：提款（可选）¶

将资金从 Vault 转回钱包，请使用即时提款流程：

调用 POST /withdraw 获取执行者联签。
调用 POST /withdraw/build 获取未签名的 executeInstantWithdrawDualSig 交易。
在本地签名该交易，然后通过 POST /withdraw/send 广播。

如果 API 不可用，您始终可以回退到链上的 emergencyWithdraw() 流程。

虚拟流动性订单¶

VL 订单的生命周期与标准限价单相同，但共享预算管理。当某个 VL 同胞订单成交时，撮合引擎会自动修改或取消剩余同胞订单，以保持在预算内。

主要区别：

下单 — 使用 POST /orders/vl/batch 代替 POST /orders
取消 — 使用 POST /orders/vl/cancel 取消整个批次，或使用 POST /orders/cancel 取消单个同胞订单
预算跟踪 — 系统在所有同胞订单间跟踪共享的冻结余额；某个同胞的成交会减少其他同胞可用的预算

完整指南请参见虚拟流动性。

订单状态汇总¶

状态	含义	可取消？
`pending`	已提交、挂单中或部分成交	是
`matched`	所有腿在撮合引擎中已交叉，链上结算进行中	否
`settled`	已完全成交且链上确认	否
`cancelled`	已在完全成交前取消	否
`failed`	被拒绝或结算 revert	通常否；查看 `error` 与 `error_code`

pending 可以表示尚未成交、部分成交后仍有剩余数量，或已提交但尚未进入链上结算的订单。前端应结合 filled_amount、remaining_amount、settlement_summary、/fills 以及 settlement_economics 判断用户资金变化。公共 API 不暴露协议价差收入或交易对手转账拆分。