系统端点¶

健康检查¶

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": "0xef64d15ed6c371545eb6dcd6c026c17dfb6c440f",
      "decimals": 6,
      "min_trade_amount_raw": "0",
      "min_trade_amount": "0"
    }
  ]
}

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

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

市场注册表¶

GET /markets

身份验证： 无

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

{
  "markets": [
    {
      "symbol": "USDC/EURC",
      "base_symbol": "USDC",
      "quote_symbol": "EURC",
      "base_address": "0x965d4b4546716e416e950bc30467d128455d2d0e",
      "quote_address": "0xef64d15ed6c371545eb6dcd6c026c17dfb6c440f",
      "tick_precision": 6,
      "quantity_precision": 6,
      "amount_step": "0.000001",
      "price_step": "0.000001",
      "rounding_mode": "reject_extra_precision",
      "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

身份验证： 无。

查询参数¶

参数	必填	说明
`base`	是	三个 ASCII 字母，不区分大小写的 ISO 货币代码，例如 `USD`
`quote`	是	三个 ASCII 字母，不区分大小写的 ISO 货币代码，例如 `SGD`

响应¶

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

字段	说明
`pair`	请求的 `base/quote` 方向
`rate`	正数十进制字符串汇率
`as_of`	所选来源数据的 Unix 时间戳，不一定是请求时间
`source`	`identity`、`market_oracle` 或 `ecb_reference`
`observation_date`	ECB 观察日期（`YYYY-MM-DD`）；其他来源为 null
`rate_24h_ago`、`as_of_24h_ago`	可用的比较汇率与时间戳，可以为 null
`change_pct`	带正负号、四位小数的百分比变化字符串，可以为 null

来源与时效¶

identity：两侧货币相同时，汇率为 1、比较汇率为 1、变化为 0.0000，观察日期为空，不查询数据存储。
market_oracle：对服务方报价进行时间聚簇、异常剔除和中位数聚合。也可选取反向交易对，以 1 / 反向汇率 计算并保留八位小数。历史查询锁定同一方向；T-24h 附近（默认 ±1 小时）没有历史数据时，比较字段为 null，当前汇率仍返回 200。
ecb_reference：两个市场方向都没有可用数据时，部署已启用且可用的 ECB 来源可返回每日参考汇率，比较字段对应可用的参考观察数据。此回退仅用于公共汇率查询，不会成为 Swap 的执行价格。展示为当前汇率前，应检查 source、as_of 与 observation_date。

状态码¶

HTTP	含义
200	当前汇率可用，比较字段可以为 null
400	已提供的货币代码不满足三个 ASCII 字母要求
422	缺少必填参数，或未通过查询参数模型校验
429	启用公共限流时触发限制
503	市场数据和可选 ECB 回退均不可用，或依赖尚未就绪

Permit 元数据¶

GET /permit/metadata

身份验证： 需要 API Key

查询参数：

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

支持 permit 的代币示例响应：

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

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

公共配置¶

GET /config

身份验证： 无

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

{
  "chain_id": 11155111,
  "sera_address": "0x83475A1bD98a8DC2DCd507A747e4DC85da241D6e",
  "vault_address": "0x3c7945840bAE0d7e7f3824Ebccef1962629250F0",
  "sor_address": "0x83c1368110B640A729f3810De5FBe94b99aa5668",
  "domain_separator": "0x...",
  "eip712_domain": {
    "name": "Sera",
    "version": "1",
    "chainId": 11155111,
    "verifyingContract": "0x83475A1bD98a8DC2DCd507A747e4DC85da241D6e"
  },
  "limits": {
    "vl_batch": { "min": 2, "max": 50 },
    "withdraw": { "cosignature_max_ttl_seconds": 600 }
  },
  "capabilities": {
    "balances": { "sync_enabled": true },
    "deposits": { "enabled": true, "restriction_reason": null },
    "withdrawals": { "instant_enabled": false },
    "orders": { "time_in_force": ["GTC"] }
  }
}

配置处理器返回已知值，未知字段为 null。服务预热或注册表不可用时，启动准入仍可能返回 503。请稍后重试，并在签名前确认所需字段齐全。

运行时读取 limits.vl_batch.{min,max} 与 limits.withdraw.cosignature_max_ttl_seconds。前者可按部署配置，联合签名上限为 600 秒。

账户能力¶

capabilities.balances.sync_enabled 表示是否接受余额同步。capabilities.deposits.enabled 与可为空的 capabilities.deposits.restriction_reason 描述充值可用性；deposit_accounting_paused 表示客户端应暂停构建和广播充值。capabilities.withdrawals.instant_enabled 表示即时提款可用性。请读取当前值，不要照抄示例。能力开关不能替代每次请求的身份、余额或资格校验。

验证签名¶

POST /verify-signature

身份验证： 无

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

fee_bps 可选，默认 0，并以签名字段 feeBps 重建；必须与签名时的值一致。valid=true 只表示签名验证通过，不证明订单精度规范、最低金额、资金、UUID 绑定或下单准入通过；这些检查请结合订单预览与最终下单响应。

请求体¶

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

精度、缓存与能力¶

当前市场满足 quantity_precision = base_decimals、tick_precision = quote_decimals。amount_step、price_step、rounding_mode="reject_extra_precision" 描述下单规则，签名前请使用预览。订单低于最低金额时读取 detail.error_code="AMOUNT_BELOW_MIN"；Swap 报价错误可能改用 detail.code。

GET /markets 支持 ETag / If-None-Match：响应未改变时返回 304 且没有响应体，仅在 200 后解析 JSON。接口支持 gzip，设置 Vary: Accept-Encoding，客户端拒绝所有可用编码时返回 406。

GET /config 还返回 limits.withdraw.cosignature_max_ttl_seconds（600）和 capabilities.orders.time_in_force（["GTC"]）。提款联合签名应遵守该时间上限。公共下单能力不代表 Swap 独立执行流程的能力。

就绪与筛查状态¶

这些端点用于部署、负载均衡和监控，建议仅通过受限的运维入口访问。客户接入不需要轮询这些探针。部分探针会查询下游依赖并返回运行状态；列入文档不代表应将其直接开放到公网。

身份验证： 应用处理器不要求交易 API Key；访问范围由部署入口控制。下列路径包含完整版本前缀。

方法	路径	响应与用途
GET	`/api/v1/livez`	`{ "status": "alive" }`，仅检查进程存活
GET	`/api/v1/warmz`	`status="warm"`、筛查、注册表及订单核算就绪信息；可以在交易激活前成功
GET	`/api/v1/readyz`	`/policy-readyz` 的兼容别名
GET	`/api/v1/policy-readyz`	`status="ready"`，包含筛查策略和已激活交易依赖
GET	`/api/v1/traffic-readyz`	`status="ready"`、`scope="traffic"`、`policy_readiness`；检查接流依赖，不要求筛查可用
GET	`/api/v1/screening/status`	`provider`、`capability`、`state`、`ready`、`can_screen`

运行时接流使用 /traffic-readyz，要求策略就绪时使用 /policy-readyz。依赖失败返回 503。进程存活不等于就绪；可接流的服务仍会对受保护操作单独执行筛查。就绪响应中的 ecb_fx 仅供参考。

筛查状态中的 ready=true 不总是表示实际判断能力已探测：已配置的第三方服务可以有 can_screen=null，开发环境关闭筛查时则为 can_screen=false。此端点不筛查指定钱包。地址查询请使用独立的地址筛查 API。