API 概覽¶
Sera API 是一個 RESTful API，用於程式化存取 Sera 的交易和帳戶管理功能。
基礎 URL¶
內容類型¶
所有請求和回應使用 JSON：
身份驗證¶
API 支援兩種身份驗證方法：
| 方法 | 使用場景 | Header |
|---|---|---|
| API Key | 帳戶讀取端點與交易建構輔助端點 | Authorization: Bearer {key}:{secret} |
| EIP-712 簽名 | 交易寫入、取消、提取與 API Key 管理 | 包含在請求主體或查詢參數中 |
詳情請參閱身份驗證。
速率限制¶
匿名流量限速由邊緣代理/CDN 處理。攜帶 API Key 的請求會在應用內按錢包地址再做限速：
| 分組 | 典型端點 | 限制 |
|---|---|---|
read | GET /orders、GET /balances、GET /fills | 10 req/s |
trade | POST /orders、POST /swap | 5 req/s |
cancel | POST /orders/cancel、DELETE /orders/cancel-all | 2 req/s |
transfer | 充值、授權、提現、轉帳與交易廣播輔助端點 | 2 req/s |
端點¶
系統¶
| 方法 | 路徑 | 驗證 | 說明 |
|---|---|---|---|
| GET | /health | 無 | 服務健康、executor_id 與簽名就緒狀態 |
| GET | /system/time | 無 | 伺服器時間戳 |
| GET | /tokens | 無 | 代幣註冊表 |
| GET | /markets | 無 | 活躍市場中繼資料 |
| GET | /fx/rate | 無 | ISO 貨幣對的聚合匯率與 24 小時漲跌幅 |
| GET | /permit/metadata | API Key | EIP-2612 permit domain、nonce 與額度探測 |
| GET | /config | 無 | 公共鏈上與合約啟動配置 |
| POST | /verify-signature | 無 | 驗證 EIP-712 訂單簽名 |
交易¶
| 方法 | 路徑 | 驗證 | 說明 |
|---|---|---|---|
| POST | /swap/quote | 無 | 取得兌換報價 |
| POST | /swap | EIP-712 | 執行已簽署的兌換 |
| POST | /orders | EIP-712 | 掛限價單 |
| POST | /orders/cancel | EIP-712 | 取消訂單 |
| DELETE | /orders/cancel-all | API Key | 取消所有未完成訂單 |
| POST | /orders/vl/batch | EIP-712 | 提交虛擬流動性批次訂單 |
| POST | /orders/vl/cancel | EIP-712 | 取消虛擬流動性批次 |
帳戶¶
| 方法 | 路徑 | 驗證 | 說明 |
|---|---|---|---|
| GET | /orders/{id} | API Key | 取得訂單狀態 |
| GET | /orders | API Key | 列出訂單 |
| GET | /fills/{order_id} | API Key | 取得單筆訂單成交明細 |
| GET | /fills | API Key | 取得帳戶範圍成交明細 |
| GET | /balances | API Key | 取得帳戶餘額 |
| POST | /approve | API Key | 建構未簽名的 ERC-20 approve(spender, amount) 交易 |
| POST | /deposit | API Key | 建構未簽名的 depositFund 或 depositFundWithPermit 交易 |
| POST | /tx/send | API Key | 廣播已簽名的授權/存款交易 |
| POST | /withdraw | 可選 | 取得提取共簽名 |
| POST | /withdraw/build | 可選 | 建構未簽名的提取交易 |
| POST | /withdraw/send | 可選 | 廣播已簽名的提取交易 |
| POST | /transfer | API Key | 建構未簽名的 ERC-20 轉帳 |
| POST | /transfer/send | API Key | 廣播已簽名的轉帳 |
API Key 管理¶
| 方法 | 路徑 | 驗證 | 說明 |
|---|---|---|---|
| POST | /api-keys | EIP-712 | 建立唯讀 API key |
| GET | /api-keys | EIP-712 | 列出 API key（帶簽章的查詢參數） |
| POST | /api-keys/list | EIP-712 | 列出 API key（帶簽章的 JSON 主體） |
| DELETE | /api-keys | EIP-712 | 撤銷 API key（帶簽章的查詢參數） |
| POST | /api-keys/revoke | EIP-712 | 撤銷 API key（帶簽章的 JSON 主體） |
| POST | /api-keys/revoke-all | EIP-712 | 以單一簽章批次撤銷該錢包下所有有效 API key |
| POST | /api-keys/self-revoke | API Key | 以目前憑證撤銷該 API key 自身 |
| POST | /api-keys/verify | 無 | 驗證 API key/secret 對，且不消耗速率限制 |
錯誤回應¶
所有錯誤回傳包含 detail 欄位的 JSON 主體：
伺服器端故障（原 5xx）會統一對應為 503 且回應主體改寫為通用文案 —— 客戶端看到的是 {"detail": "Service temporarily unavailable; please retry"} 與 Retry-After: 1 回應標頭；具體原因僅記錄在伺服器端日誌，不會回傳給整合方。
狀態碼¶
| 代碼 | 含義 |
|---|---|
| 200 | 成功 |
| 201 | 資源已建立 |
| 400 | 請求無效（參數錯誤、簽章不符） |
| 401 | 身份驗證失敗 |
| 403 | 禁止存取（存取其他使用者的資料） |
| 404 | 資源未找到 |
| 409 | 衝突（重複簽章、自成交拒絕等） |
| 410 | 已過期（報價過期、已消費或不存在） |
| 422 | 驗證失敗 |
| 429 | 觸發限速或取消冷卻 |
| 503 | 服務暫時不可用；請依 Retry-After 重試 |
程式碼範例¶
// Public endpoint (no auth)
const tokens = await fetch('https://api.sera.cx/api/v1/tokens')
.then(r => r.json());
// Authenticated endpoint (API key)
const orders = await fetch('https://api.sera.cx/api/v1/orders?owner_address=0x...', {
headers: { 'Authorization': 'Bearer sera_abc123:secret456' }
}).then(r => r.json());
import requests
# Public endpoint
tokens = requests.get("https://api.sera.cx/api/v1/tokens").json()
# Authenticated endpoint
headers = {"Authorization": "Bearer sera_abc123:secret456"}
orders = requests.get(
"https://api.sera.cx/api/v1/orders",
params={"owner_address": "0x..."},
headers=headers
).json()