系统端点¶

健康检查¶

GET /health

身份验证： 无

返回服务健康状态，以及当前 executor_id 和签名验证是否就绪。

{
  "status": "healthy",
  "version": "v1",
  "timestamp": "2026-04-15T08:00:00+00:00",
  "executor_id": 0,
  "relayer_executor_id": 0,
  "signature_ready": true
}

说明：

当签名验证就绪、且本地解析的 executor_id 与链上探测一致时，status 为 healthy。
当签名验证尚未就绪，或 executor_id 与 relayer_executor_id 不一致时，status 为 degraded（用于在订单被拒绝前提前发现漂移）。
当链上探测暂时不可达时 relayer_executor_id 可能为 null。仅 null 本身不是降级信号；只有它与 executor_id 实际不一致才是。
生成组合 uuid_int 时请使用 executor_id。
当后端依赖不可用时，该端点会返回 503。

服务器时间¶

GET /system/time

身份验证： 无

{
  "timestamp": 1713168000
}

请使用该值来设置签名请求中的 expiration 和 deadline。

代币注册表¶

GET /tokens

身份验证： 无

{
  "tokens": [
    {
      "currency": "USD",
      "symbol": "USDC",
      "address": "0xDcaEcdd8Db64f4316A11917Ad0162DEBD935285b",
      "decimals": 6,
      "min_trade_amount_raw": "8800000",
      "min_trade_amount": "8.800000"
    },
    {
      "currency": "EUR",
      "symbol": "EURC",
      "address": "0xd3BdB2CE9cD98566EFc2e2977448c40578371779",
      "decimals": 6,
      "min_trade_amount_raw": "0",
      "min_trade_amount": "0"
    }
  ]
}

响应是一个包含 tokens 数组的对象。

min_trade_amount_raw 对应链上 Sera 合约为每个代币维护的最小成交输入数量（原始单位）。如果提交的输入金额低于这个阈值，/swap/quote 和 /orders 会在预检阶段直接返回 HTTP 400，并携带 detail.code = "AMOUNT_BELOW_MIN"。"0" 表示没有最低限制。min_trade_amount 则是按 decimals 缩放后的展示值。

市场注册表¶

GET /markets

身份验证： 无

返回当前活跃市场及其 base/quote 元数据。

{
  "markets": [
    {
      "symbol": "EURC/USDC",
      "base_symbol": "EURC",
      "quote_symbol": "USDC",
      "base_address": "0xd3BdB2CE9cD98566EFc2e2977448c40578371779",
      "quote_address": "0xDcaEcdd8Db64f4316A11917Ad0162DEBD935285b",
      "tick_precision": 4,
      "quantity_precision": 2,
      "base_decimals": 6,
      "quote_decimals": 6,
      "min_ask_amount_raw": "0",
      "min_ask_amount": "0",
      "min_bid_quote_amount_raw": "8800000",
      "min_bid_quote_amount": "8.800000"
    }
  ]
}

base_address 与 quote_address 是唯一标识该交易对的 ERC-20 合约地址。 base_symbol / quote_symbol 是显示用的代币符号，与 symbol 字符串的两部分对应。交易对方向由服务端规范化：以小写字节序比较，base_address 严格小于 quote_address。

min_ask_amount_raw / min_bid_quote_amount_raw 来源于链上的最小成交金额：

ASK 下限 使用基础代币最小值，因此与价格无关。
BID 下限 以报价代币侧展示，因为最小基础数量会随价格变化。

对应的十进制展示值分别在 min_ask_amount 与 min_bid_quote_amount 中给出。

FX 汇率¶

GET /fx/rate

身份验证： 无

返回某个 ISO 货币对的聚合汇率，以及与 24 小时前相比的涨跌幅。该端点复用了撮合定价所使用的同一条服务方报价聚合管线（时间聚簇 + 异常过滤 + 中位数），但不会再套用撮合定价的"聚合后再判鲜活度"那道闸门——返回的 as_of 时间戳即为最新一条服务方报价的时间，由调用方自行判断鲜活度。

查询参数¶

名称	类型	必填	说明
`base`	string	是	ISO 货币代码（例如 `USD`），仅字母，大小写不敏感。
`quote`	string	是	ISO 货币代码（例如 `SGD`），仅字母，大小写不敏感。

响应¶

{
  "pair": "USD/SGD",
  "rate": "1.2843",
  "as_of": 1777372800.12,
  "rate_24h_ago": "1.2901",
  "as_of_24h_ago": 1777286400.05,
  "change_pct": "-0.4496"
}

pair 始终按调用方请求的方向（base/quote）输出，不论底层数据来自哪一侧。
rate 是聚合后的中位数（已经过时间聚簇与异常剔除）。
as_of 是参与聚合的最新一条服务方报价的 Unix 时间戳。
当 T-24h 附近 ±1 小时窗口内查不到任何报价时，rate_24h_ago / as_of_24h_ago / change_pct 三项均会返回 null，端点仍以 200 返回—— 历史数据缺失不视为鲜活度失败。
change_pct 带正负号，保留 4 位小数。

自动反向¶

当 now 锚点处仅存在反向交易对（例如调用方请求 SGD/USD，但抓取器只存储了 USD/SGD）时，端点会以 1 / 反向汇率 计算正向汇率，并量化到 8 位小数。历史锚点会被锁定为与当前锚点相同的方向——两个锚点之间永远不会混用方向。

同一货币¶

请求 ?base=USD&quote=USD 直接返回 rate=1、rate_24h_ago=1、 change_pct=0，不会查询数据存储。

状态码¶

状态码	含义
200	成功；`rate` 一定有，历史相关字段可能为 `null`。
400	`base`/`quote` 缺失或非字母。
503	当前锚点的近鲜窗口（默认 4 小时）内两个方向都查不到任何服务方报价。

Permit 元数据¶

GET /permit/metadata

身份验证： 需要 API Key

查询参数：

token：ERC-20 代币地址
owner：可能签署 permit 的钱包地址
spender：额度接收方，通常取自 GET /config 的 sor_address 或 vault_address
amount（可选）：要与当前 allowance 比较的原始 uint256 数量

支持 permit 的代币示例响应：

{
  "token": "0xDcAEcdd8Db64f4316A11917Ad0162DEBD935285b",
  "owner": "0x...",
  "spender": "0x...",
  "current_allowance_raw": "0",
  "required": true,
  "permit_supported": true,
  "nonce": 4,
  "domain": {
    "name": "USD Coin",
    "version": "2",
    "chainId": 11155111,
    "verifyingContract": "0xDcAEcdd8Db64f4316A11917Ad0162DEBD935285b"
  }
}

不支持 permit 的代币会返回 permit_supported: false，并省略 nonce 与 domain。只有在传入 amount 时，响应里才会包含可选的 required 字段。

公共配置¶

GET /config

身份验证： 无

返回签名与交易构建所需的公共引导信息。

{
  "chain_id": 11155111,
  "sera_address": "0xd0fc92d8eF9bE26D7288fCa1D6458f675e72B83a",
  "vault_address": "0x5d6ffA9b9710C7Ab69105496a0fD8C48DfF40110",
  "sor_address": "0xAfDb9f6071feD09941930246E78ce301DF7d1ace",
  "domain_separator": "0x...",
  "eip712_domain": {
    "name": "Sera",
    "version": "1",
    "chainId": 11155111,
    "verifyingContract": "0xd0fc92d8eF9bE26D7288fCa1D6458f675e72B83a"
  },
  "limits": {
    "vl_batch": { "min": 2, "max": 50 }
  }
}

这个端点即使在部分启动阶段也会尽量返回 200。未知字段会返回 null；客户端应重试，而不是把空值当成永久失败。

limits 字段承载随部署可能不同的公共 API 上限。请在运行时通过 GET /config 读取这些值，不要在客户端硬编码。当前包含 limits.vl_batch.{min,max}（VL 批次下单数量的上下限）；后续会在该字段下新增其他子键。

验证签名¶

POST /verify-signature

身份验证： 无

可用于在提交订单前测试 EIP-712 订单签名是否正确。

请求体¶

{
  "owner_address": "0x...",
  "side": "bid",
  "amount": "1000.0",
  "price": "1.085",
  "from_address": "0x...",
  "to_address": "0x...",
  "order_id": "00000000-0000-4000-8000-000000000001",
  "uuid_int": "6427948336465191935941739505432058208337171677044006212075520",
  "signature": "0x...",
  "expiration": 1713254400
}

from_address 是市场的基础代币，to_address 是报价代币。expiration 为必填，并且必须满足与 POST /orders 相同的有界未来时间规则。

响应¶

{
  "valid": true,
  "recovered_address": "0x...",
  "expected_address": "0x...",
  "error": null
}