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，不能把這兩個欄位作為所有錯誤的必填項。