API 概述¶

Sera API 是一个 RESTful API，用于程序化访问 Sera 的交易和账户管理功能。

基础 URL¶

https://api.testnet.sera.cx/api/v1

内容类型¶

所有请求和响应使用 JSON：

Content-Type: application/json

身份验证¶

API 支持两种身份验证方式：

详情请参阅身份验证。

频率限制¶

边缘代理/CDN 也可配置客户端限流，请以目标环境公布的限制为准。携带 API Key 的请求会在应用内按钱包地址限流：

接口访问范围¶

客户接口可供外部集成，调用时仍须满足各端点的 API Key、钱包签名或已签名交易要求。表中的“无”仅表示无需交易 API Key，不代表无限制访问；凭据校验仍须提供待校验的凭据。功能和访问入口以目标环境实际开放的范围为准。

运维探针供部署、负载均衡和监控使用，应通过受限的运维入口访问，不属于客户交易流程。文档记录这些路径不代表要求将其开放到公网。

端点¶

系统¶

交易¶

账户¶

API Key 管理¶

其他 API 版本与服务¶

v1 与 v2 并存，v2 的金额、状态解释和分页方式不同，请使用以上完整版本路径。地址筛查 API 是独立服务，有自己的主机与响应契约。系统端点还介绍 GET /api/v1/livez、/api/v1/warmz、/api/v1/readyz、/api/v1/policy-readyz、/api/v1/traffic-readyz、/api/v1/screening/status。

运维探针¶

以下端点供运维使用。代码中未要求交易 API Key，部署入口应另行限制访问；不要将“无 API Key”理解为已具备公网访问保护。

错误响应¶

多数错误返回包含 detail 字段的 JSON 体：

{
  "detail": "Human-readable error message"
}

多数处理器 5xx 故障返回 503、{"detail":"Service temporarily unavailable; please retry"} 和 Retry-After: 1。启动准入可能返回不同详情。结构化错误和安全重试请参阅下方客户端处理说明。

状态码¶

代码示例¶

import requests

# 公共端点
tokens = requests.get("https://api.testnet.sera.cx/api/v1/tokens").json()

# 鉴权端点
headers = {"Authorization": "Bearer sera_abc123:secret456"}
orders = requests.get(
    "https://api.testnet.sera.cx/api/v1/orders",
    params={"owner_address": "0x..."},
    headers=headers,
).json()

// 公共端点（无需鉴权）
const tokens = await fetch("https://api.testnet.sera.cx/api/v1/tokens")
  .then(r => r.json());

// 鉴权端点（API key）
const orders = await fetch(
  "https://api.testnet.sera.cx/api/v1/orders?owner_address=0x...",
  { headers: { "Authorization": "Bearer sera_abc123:secret456" } },
).then(r => r.json());

# 公共端点
curl https://api.testnet.sera.cx/api/v1/tokens

# 鉴权端点
curl -H "Authorization: Bearer sera_abc123:secret456" \
  "https://api.testnet.sera.cx/api/v1/orders?owner_address=0x..."

客户端处理说明¶

报价、下单等端点接入应用层公共限流；生产类环境要求启用其 429 拒绝行为。不能据此推断每条匿名端点都使用相同限额。批量报价每条消耗一个额度，不是每个 HTTP 请求只消耗一个。API Key 钱包限额仍适用。返回 X-RateLimit-Limit、X-RateLimit-Remaining、Retry-After 时请使用这些值。

多数处理器 5xx 会被替换为通用 503 和 Retry-After: 1。缓存预热期间，启动准入可能返回不同的 503 detail。X-Sera-Retry-Safe: true 明确标识部分准入前失败；没有该标记时，不能推断写入未生效。替换结果未知的执行前，先按订单/报价身份查询。

不能假定 detail 总是字符串，也不能假定每个 422 都有 Pydantic 字段详情。请求模型错误使用 { "detail": "Invalid request" }。新增流程还使用 202（执行待确认）、304（市场响应未变化，无响应体）、406（编码不可接受）。未知错误码仍应视为失败，并保留请求 ID 供排查。

示例用于说明请求/响应结构。实际调用前请替换占位地址和历史时间戳，从 /config 读取当前链与合约信息，从 /system/time 读取当前秒数。文档列出某条路径，不代表每个部署都已启用该功能。

请求体大小¶

交易 API 对整个请求体默认限制 64 KiB（65,536 字节），以目标部署设置为准；流式请求也受此限制。批量条数和单个签名长度满足要求，不代表合计大小符合要求。超限返回 HTTP 413、{"detail":"Request body too large"}；应缩小请求，不要原样反复重试。筛查服务有独立的请求体与错误规则，其协议错误及 429 不一定带 schema_version、error.retryable，不能把这两个字段作为所有错误的必填项。