订单生命周期¶

网络与兼容性

资源	值
API 基础 URL	`https://api.sera.cx/api/v1`
链	以太坊主网（chainId `1`）
Sera 合约	`0xB5C50C5D5f038404F85970b7f5B7259C4AC0E198`
Vault 合约	`0xC7d4Fd2638e6630C8C61329878676b88A8A24D43`
SOR 合约	`0xa7A0cf7cd6f043fCA23f29d8ae5aae6b46e11c18`

签名原语。 所有交易型变更都是针对 Sera 域的 EIP-712 类型化数据签名。走 permit 路径的充值使用 ERC-2612 Permit 扩展 — USDC、EURC 以及许多现代稳定币支持，但并非所有 ERC-20 都支持；签名前请调用 GET /permit/metadata 检查。API key 管理使用 EIP-712 ManageApiKey 载荷。

已验证客户端。 Python eth_account >= 0.10 + requests；TypeScript ethers v6（signer.signTypedData）。已验证支持 EIP-712 类型化数据的浏览器钱包：MetaMask、Rabby、Frame、Coinbase Wallet、Trust、Rainbow。Safe 多签通过 EIP-1271 支持（消息在链上验证，而非通过 ecrecover）。

地址大小写。 读取类端点（/balances、/orders、/fills）将 owner_address 视为大小写敏感 — 请传入小写形式。EIP-712 签名载荷接受 EIP-55 校验和地址。

本教程将引导您了解 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 步：检查服务器时间¶

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

PythonTypeScript

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}")

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

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

第 2 步：查询可用代币¶

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

PythonTypeScript

tokens = requests.get("https://api.sera.cx/api/v1/tokens").json()["tokens"]

# 查找 USDC 和 EURC 地址
usdc = next(t for t in tokens if t["symbol"] == "USDC")
eurc = next(t for t in tokens if t["symbol"] == "EURC")

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

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

第 3 步：下限价单¶

构造并签署 EIP-712 Order，然后提交。完整签名流程见身份验证与做市商指南 → 下达单笔限价单。代码节选：

PythonTypeScript

import time, uuid, requests

# 生成唯一订单 ID
order_id    = str(uuid.uuid4())
executor_id = requests.get("https://api.sera.cx/api/v1/health").json()["executor_id"]
raw         = int(uuid.UUID(order_id))
group_id    = raw >> 16
uuid_int    = str((executor_id << 252) | (raw << 124) | (group_id << 12))

# 构造订单。from_address 是市场基础代币，to_address 是报价代币。
# 最终支出哪一边由 side 决定。
order = {
    "owner_address": wallet_address,
    "side":          "bid",                # 用 USDC 买 EURC
    "amount":        "1000.0",             # 1000 EURC
    "price":         "1.085",              # 每 EURC 1.085 USDC
    "order_type":    "limit",
    "from_address":  EURC_ADDRESS,         # 市场基础代币，也是您要买入的代币
    "to_address":    USDC_ADDRESS,         # 市场报价代币，在 bid 中是您支出的代币
    "order_id":      order_id,
    "uuid_int":      uuid_int,
    "expiration":    int(time.time()) + 86_400,
}

# 使用 EIP-712 签名（完整签名细节见 身份验证）
signature = sign_order(signer, order)

result = requests.post(
    "https://api.sera.cx/api/v1/orders",
    json={**order, "signature": signature},
    timeout=10,
).json()
print("Order placed:", result["order_id"])

import { v4 as uuidv4 } from "uuid";

// 生成唯一订单 ID
const orderId  = uuidv4();
const { executor_id: executorId } = await fetch("https://api.sera.cx/api/v1/health")
  .then(r => r.json());
const raw      = BigInt("0x" + orderId.replace(/-/g, ""));
const groupId  = raw >> 16n;
const uuidInt  = ((BigInt(executorId) << 252n) | (raw << 124n) | (groupId << 12n)).toString();

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

// 使用 EIP-712 签名（完整签名细节见 身份验证）
const signature = await signOrder(signer, 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 密钥轮询订单状态：

PythonTypeScript

status = requests.get(
    f"https://api.sera.cx/api/v1/orders/{order_id}",
    headers={"Authorization": "Bearer YOUR_API_KEY:YOUR_API_SECRET"},
    timeout=10,
).json()
print("Status:", status["status"])
# 外部状态："pending"、"matched"、"settled"、"cancelled"、"failed"
print("Filled:", status["filled_amount"])
print("Signed uuid_int:", status["uuid_int"])

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 余额中：

PythonTypeScript

balances = requests.get(
    "https://api.sera.cx/api/v1/balances",
    params={"owner_address": wallet_address},
    headers={"Authorization": "Bearer YOUR_API_KEY:YOUR_API_SECRET"},
    timeout=10,
).json()["balances"]

for bal in balances:
    print(f"{bal['symbol']}: vault_raw={bal['vault_available']}, "
          f"frozen_raw={bal['vault_frozen']}, decimals={bal['decimals']}")

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) {
  console.log(`${bal.symbol}: vault_raw=${bal.vault_available}, ` +
              `frozen_raw=${bal.vault_frozen}, decimals=${bal.decimals}`);
}

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

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

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

PythonTypeScript

# 签署 CancelOrder 消息
cancel_signature = sign_cancel_order(signer, wallet_address, int(status["uuid_int"]))

cancel_res = requests.post(
    "https://api.sera.cx/api/v1/orders/cancel",
    json={
        "owner_address": wallet_address,
        "order_id":      order_id,
        "uuid_int":      status["uuid_int"],
        "signature":     cancel_signature,
    },
    timeout=10,
).json()
print("Cancelled:", cancel_res)

// 签署 CancelOrder 消息
const cancelSignature = await signCancelOrder(signer, walletAddress, BigInt(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 分钟的撤单冷却期；命中冷却会返回 429。请在冷却后重试，或先查询订单状态再重新提交。

第 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 判断用户资金变化。文档响应 schema 之外的字段不属于公共 API 契约。