系統端點¶

健康檢查¶

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。