系統端點¶

健康檢查¶

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

回應是一個包含 tokens 陣列的物件。

min_trade_amount_raw 對應鏈上 Sera 合約為每個代幣維護的最小成交輸入數量（原始單位）。如果提交的輸入金額低於這個門檻，/swap/quote 與 /orders 會在預檢階段直接回傳 HTTP 400，並附帶 detail.code = "AMOUNT_BELOW_MIN"。"0" 代表沒有最低限制。min_trade_amount 則是依 decimals 縮放後的顯示值。

市場註冊表¶

GET /markets

身份驗證： 無

回傳目前活躍市場及其 base/quote 中繼資料。

{
  "markets": [
    {
      "symbol": "EURC/USDC",
      "base_symbol": "EURC",
      "quote_symbol": "USDC",
      "base_address": "0xd3BdB2CE9cD98566EFc2e2977448c40578371779",
      "quote_address": "0xDcaEcdd8Db64f4316A11917Ad0162DEBD935285b",
      "tick_precision": 4,
      "quantity_precision": 2,
      "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

身份驗證： 無

返回某個 ISO 貨幣對的聚合匯率，以及與 24 小時前相比的漲跌幅。該端點重用了撮合定價所使用的同一條服務方報價聚合管線（時間聚簇 + 異常過濾 + 中位數），但不會再套用撮合定價那道「聚合後再判鮮活度」的閘門——返回的 as_of 時間戳即為最新一筆服務方報價的時間，由呼叫方自行判斷鮮活度。

查詢參數¶

名稱	類型	必填	說明
`base`	string	是	ISO 貨幣代碼（例如 `USD`），僅字母，大小寫不敏感。
`quote`	string	是	ISO 貨幣代碼（例如 `SGD`），僅字母，大小寫不敏感。

回應¶

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

pair 始終按呼叫方請求的方向（base/quote）輸出，無論底層資料來自哪一側。
rate 是聚合後的中位數（已經過時間聚簇與異常剔除）。
as_of 是參與聚合的最新一筆服務方報價的 Unix 時間戳。
當 T-24h 附近 ±1 小時窗口內查不到任何報價時，rate_24h_ago / as_of_24h_ago / change_pct 三項皆會回傳 null，端點仍以 200 回應—— 歷史資料缺失不視為鮮活度失敗。
change_pct 帶正負號，保留 4 位小數。

自動反向¶

當 now 錨點處僅存在反向交易對（例如呼叫方請求 SGD/USD，但抓取器僅儲存了 USD/SGD）時，端點會以 1 / 反向匯率 計算正向匯率，並量化到 8 位小數。歷史錨點會被鎖定為與當前錨點相同的方向——兩個錨點之間永遠不會混用方向。

同一貨幣¶

請求 ?base=USD&quote=USD 直接回傳 rate=1、rate_24h_ago=1、 change_pct=0，不會查詢資料儲存。

狀態碼¶

狀態碼	含義
200	成功；`rate` 一定有，歷史相關欄位可能為 `null`。
400	`base`/`quote` 缺失或非字母。
503	當前錨點的近鮮窗口（預設 4 小時）內兩個方向都查不到任何服務方報價。

Permit 中繼資料¶

GET /permit/metadata

身份驗證： 需要 API Key

查詢參數：

token：ERC-20 代幣地址
owner：可能簽署 permit 的錢包地址
spender：額度接收方，通常取自 GET /config 的 sor_address 或 vault_address
amount（可選）：要與目前 allowance 比較的原始 uint256 數量

支援 permit 的代幣示例回應：

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

不支援 permit 的代幣會回傳 permit_supported: false，並省略 nonce 與 domain。只有在傳入 amount 時，回應才會包含可選的 required 欄位。

公共設定¶

GET /config

身份驗證： 無

回傳簽名與交易建構所需的公共啟動資訊。

{
  "chain_id": 11155111,
  "sera_address": "0xd0fc92d8eF9bE26D7288fCa1D6458f675e72B83a",
  "vault_address": "0x5d6ffA9b9710C7Ab69105496a0fD8C48DfF40110",
  "sor_address": "0xAfDb9f6071feD09941930246E78ce301DF7d1ace",
  "domain_separator": "0x...",
  "eip712_domain": {
    "name": "Sera",
    "version": "1",
    "chainId": 11155111,
    "verifyingContract": "0xd0fc92d8eF9bE26D7288fCa1D6458f675e72B83a"
  },
  "limits": {
    "vl_batch": { "min": 2, "max": 50 }
  }
}

這個端點即使在部分啟動階段也會盡量回傳 200。未知欄位會回傳 null；客戶端應重試,而不是把空值視為永久失敗。

limits 欄位承載隨部署可能不同的公共 API 上限。請在執行時透過 GET /config 讀取這些值,不要在客戶端硬編碼。目前包含 limits.vl_batch.{min,max}(VL 批次下單數量的上下限);未來會在此欄位下新增其他子鍵。

驗證簽名¶

POST /verify-signature

身份驗證： 無

可用於在提交訂單前測試 EIP-712 訂單簽名是否正確。

請求主體¶

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