訂單端點¶

掛限價單¶

POST /orders

身份驗證： EIP-712 Order 簽名

請求主體¶

{
  "owner_address": "0x...",
  "side": "bid",
  "amount": "1000",
  "price": "1.085",
  "order_type": "limit",
  "from_address": "0x...",
  "to_address": "0x...",
  "order_id": "00000000-0000-4000-8000-000000000001",
  "uuid_int": "6427948336465191935941739505432058208337171677044006212075520",
  "signature": "0x...",
  "expiration": 1713254400
}

欄位	類型	必填	說明
`owner_address`	address	是	訂單擁有者的錢包地址
`side`	string	是	`bid` 或 `ask`
`amount`	string	是	自然單位數量（基礎代幣側）
`price`	string	是	自然單位價格（報價 / 基礎）
`order_type`	string	是	`limit` 或 `market`；不提供公共 IOC/FOK/post-only 策略
`from_address`	address	是	市場基礎代幣的 ERC-20 地址
`to_address`	address	是	市場報價代幣的 ERC-20 地址（必須與 `from_address` 不同）
`order_id`	UUID string	是	人類可讀的 UUID4 訂單 ID
`uuid_int`	decimal string	是	與 `order_id` 綁定的組合 uint256
`signature`	hex string	是	EIP-712 Order 簽名
`expiration`	integer	是	Unix 時間戳截止時間，必須滿足 `now < expiration <= now + 365 天 - 300 秒`

fee_bps 可選（非負 uint48 整數，預設 0），以 feeBps 進入簽名。請求模型接受 client_id，但不將其作爲訂單標識符或冪等鍵傳遞。數量與價格必須是規範十進制字串，簽名前請使用訂單預覽。請求也接受 order_type="market"，但不提供 IOC/FOK/post-only 執行策略；當前公共能力請讀取 GET /config。

from_address 與 to_address 用來標識市場，而不是直接表示「支出 / 接收」方向。對於 bid，您是用 to_address 買入 from_address；對於 ask，您是賣出 from_address 換取 to_address。這些地址請透過 GET /tokens 取得。

回應¶

{
  "order_id": "00000000-0000-4000-8000-000000000001"
}

預覽訂單¶

POST /api/v1/orders/preview

身份驗證： 無。預覽校驗公共市場精度和最低輸入金額，不預留流動性，也不檢查餘額、自成交或合規准入。

請求使用與 POST /orders 相同的欄位，包括 order_id、uuid_int、expiration，但不傳 signature、client_id。fee_bps 可選，預設 0。請求示例：

{
  "owner_address": "0x...",
  "side": "bid",
  "amount": "1000.0",
  "price": "1.085",
  "order_type": "limit",
  "from_address": "0x...",
  "to_address": "0x...",
  "order_id": "00000000-0000-4000-8000-000000000001",
  "uuid_int": "6427948336465191935941739505432058208337171677044006212075520",
  "expiration": 1800000000
}

回應¶

欄位	說明
`ok`	成功時爲 `true`
`symbol`、`side`	解析後的市場與買賣方向
`normalized_amount`、`normalized_price`	規範正十進制字串；`"1000.0"` 變爲 `"1000"`
`amount_step`、`price_step`	允許的數量/價格步長
`rounding_mode`	`reject_extra_precision`
`canonicalization_required`	提交的字串表示是否需要變更
`from_token`、`to_token`、`from_amount`、`to_amount`、`notional`	簽名代幣方向、raw 數量和展示名義金額
`eip712_order`、`eip712_types`	應使用 `GET /config` 域簽名的完整 Order 消息與類型

把規範化後的值和生成的簽名提交到 POST /orders。允許預覽 "1000.0"，但不能把該未規範字串直接用於下單。超出市場精度的非零小數位回傳 422 / INVALID_PRECISION；其他非規範提交字串回傳 INVALID_DECIMAL_FORMAT，不會靜默取整。預覽業務錯誤使用頂層 {ok:false, detail, error_code, ...}，下單則將相同業務詳情包裝在 detail 內。

原始整數金額和價格接口請參閱整數金額 API（v2）。

取消訂單¶

POST /orders/cancel

身份驗證： EIP-712 CancelOrder 簽名

請求主體¶

{
  "owner_address": "0x...",
  "order_id": "00000000-0000-4000-8000-000000000001",
  "uuid_int": "6427948336465191935941739505432058208337171677044006212075520",
  "signature": "0x..."
}

uuid_int 為必填，因為簽名中的 CancelOrder.orderId 使用的是組合 uint256，而不是 UUID 字串。

回應¶

{
  "status": "ok"
}

說明¶

訂單受取消冷卻期限制，預設值為 5 分鐘。
在冷卻期內取消會回傳 429。
如果遺失了 uuid_int，請先查詢訂單；訂單狀態回應中會回傳該欄位。

取消所有訂單¶

POST /orders/cancel-all?owner_address=0x...

身份驗證： API Key 與 EIP-712 CancelAll 簽名。

仍必須傳入小寫 owner_address 查詢參數，且與 API Key 所有者及請求體所有者一致。

請求體¶

{
  "owner_address": "0x...",
  "nonce": "123456789",
  "deadline": 1800000000,
  "signature": "0x..."
}

nonce 是該所有者下唯一的正 uint256 字串；deadline 是簽名有效期範圍內未來的 Unix 秒數整數。使用 Sera 域簽署 CancelAll(owner address, nonce uint256, deadline uint256)，詳見身份驗證。伺服器只消費一次 nonce，重放回傳 409。請保存請求，回應不確定時先查詢訂單狀態，再決定是否重新簽署取消。

回應¶

{
  "cancelled": [
    "order-id-1"
  ],
  "failed": [],
  "skipped_cooldown": [
    "order-id-2"
  ],
  "total": 1
}

total 統計成功接受的取消，包括已處於終態的訂單。已派發取消仍需後續查詢訂單狀態，以確認終態和餘額釋放。請檢查 failed、skipped_cooldown，該回應不保證所有未結訂單均已取消。

取得訂單¶

GET /orders/{order_id}

身份驗證： 需要 API Key

回應¶

{
  "trade_id": "00000000-0000-4000-8000-000000000001",
  "owner_address": "0x...",
  "status": "pending",
  "order_type": "limit",
  "symbol": "EURC/USDC",
  "side": "bid",
  "base_symbol": "EURC",
  "quote_symbol": "USDC",
  "base_token": "0x...",
  "quote_token": "0x...",
  "price": "1.085",
  "amount": "1000.0",
  "remaining_amount": "600.0",
  "filled_base_amount": "400.0",
  "filled_quote_amount": "434.0",
  "notional": "1085.0",
  "remaining_notional": "651.0",
  "from_token": "0x...",
  "to_token": "0x...",
  "from_amount": "1085000000",
  "filled_amount": "434000000",
  "to_amount": "1000000000",
  "created_at": "2026-04-15T08:00:00+00:00",
  "updated_at": "2026-04-15T08:01:00+00:00",
  "expiration": "1713254400",
  "error": null,
  "error_code": null,
  "uuid_int": "6427948336465191935941739505432058208337171677044006212075520",
  "vl_batch_id": null,
  "settlement_summary": {
    "status": "settled",
    "total_fill_count": 1,
    "pending_fill_count": 0,
    "settled_fill_count": 1,
    "failed_fill_count": 0,
    "reverted_fill_count": 0,
    "latest_settlement_id": 42,
    "latest_tx_hash": "0x...",
    "latest_parent_status": "confirmed",
    "latest_fill_settlement_status": "settled",
    "latest_failed_fill_failure_reason": null
  },
  "settlement_economics": {
    "perspective_order_id": "00000000-0000-4000-8000-000000000001",
    "gross_debits": [
      {
        "token": "USDC",
        "token_address": "0x...",
        "amount": "434.0",
        "amount_raw": "434000000"
      }
    ],
    "gross_credits": [
      {
        "token": "EURC",
        "token_address": "0x...",
        "amount": "400.0",
        "amount_raw": "400000000"
      }
    ],
    "fees_paid": [],
    "balance_debits": [
      {
        "token": "USDC",
        "token_address": "0x...",
        "amount": "434.0",
        "amount_raw": "434000000"
      }
    ],
    "balance_credits": [
      {
        "token": "EURC",
        "token_address": "0x...",
        "amount": "400.0",
        "amount_raw": "400000000"
      }
    ]
  }
}

回應說明¶

order_type 對限價單與 VL 流程為 limit，透過 POST /swap 建立的訂單為 swap。
expiration 存在時會以字串形式回顯簽名中的訂單截止時間。
error_code 是結構化的終態失敗碼；完整說明見下方錯誤碼。未識別的內部失敗會摺疊爲 TRANSIENT_SETTLEMENT_FAILURE。
vl_batch_id 會在該訂單屬於虛擬流動性批次時出現。
settlement_summary 彙總該訂單各筆成交的結算進度。latest_failed_fill_failure_reason 是經過白名單篩選的合約 revert 名稱（不在公開白名單內的值會回傳 null）。
settlement_economics 是所有者視角的資金變化摘要，完整欄位見下方結算資金變化說明。
正價差成交時，filled_amount / filled_quote_amount 不一定等於使用者實際扣除的來源代幣總額。錢包或 Vault 資金變動展示應使用 settlement_economics.balance_debits 和 settlement_economics.balance_credits。

外部訂單狀態包括：

pending：已提交、仍在掛單中或部分成交，訂單仍可繼續成交或被取消
matched — 已全部撮合，結算結果仍未確定；通過結算證據判斷成功或失敗。符合條件的失敗限價 taker 可能在恢復時重新回到 pending，不能假定狀態只會單向前進。
settled：鏈上確認的最終成功狀態
failed：鏈上確認的 revert，或在廣播前的失敗 / 拒絕
cancelled — 當前已從訂單簿移除。用戶主動撤單會阻止恢復；失敗結算後的系統移除，對符合條件的限價 taker 可能可恢復。請結合當前訂單及逐筆成交結算狀態判斷。

列出訂單¶

trade_ids 最多接受 50 個 ID。offset 範圍爲 0–10000（成交列表同樣適用）。查詢超出支援的掃描窗口時回傳 400，請按市場、狀態或時間縮小範圍。只有成功查詢的 total 才表示完整篩選結果數。

GET /orders

身份驗證： 需要 API Key

查詢參數¶

參數	類型	預設值	說明
`owner_address`	address	必填	必須與已驗證擁有者相符
`limit`	integer	50	最大 500
`offset`	integer	0	分頁偏移量
`status`	string	全部	篩選接受 `pending`、`settled`、`cancelled`、`failed`；目前傳入 `matched` 回傳 422。
`type`	string	全部	`swap` 或 `limit`
`symbol`	string	全部	正規化後的交易對精確匹配，例如 `EURC/USDC`；不是模糊搜尋。
`side`	string	全部	`bid` 或 `ask`
`from_token`	string	全部	依解析後的輸入代幣地址篩選
`to_token`	string	全部	依解析後的輸出代幣地址篩選
`base_token`	string	全部	依基礎代幣地址篩選
`quote_token`	string	全部	依報價代幣地址篩選
`base_currency`	string	全部	相容舊參數名，實際依 `base_symbol` 過濾，例如 `EURC`
`quote_currency`	string	全部	相容舊參數名，實際依 `quote_symbol` 過濾，例如 `USDC`
`trade_ids`	string	全部	以逗號分隔的 trade ID 清單
`search`	string	全部	橫跨交易欄位的自由文字搜尋
`has_error`	boolean	全部	`true` 時只回傳有錯誤的交易
`min_price` / `max_price`	string	全部	價格區間篩選
`min_amount` / `max_amount`	string	全部	數量區間篩選
`min_remaining_amount` / `max_remaining_amount`	string	全部	剩餘數量區間篩選
`min_filled_amount` / `max_filled_amount`	string	全部	已成交數量區間篩選
`min_notional` / `max_notional`	string	全部	名目金額區間篩選
`created_after` / `created_before`	string	全部	ISO8601 或相容時間戳的建立時間範圍
`updated_after` / `updated_before`	string	全部	ISO8601 或相容時間戳的更新時間範圍
`sort_by`	string	`created_at`	允許值見下文。
`order`	string	`desc`	排序方向：`asc` 或 `desc`

sort_by 接受 amount、created_at、filled_base_amount、filled_quote_amount、notional、price、remaining_amount、remaining_notional、status、symbol、trade_id、type、updated_at；order_type 是 type 的別名。非法值回傳 422。

status、type、symbol、side、from_token、to_token、base_token、quote_token、base_currency、quote_currency 與 trade_ids 接受逗號分隔的多個值。同一欄位內為「或」，不同篩選欄位組合生效。symbol 轉為大寫後精確匹配，自由文字使用 search。

matched 仍是已撮合待結算訂單的合法回傳狀態，只是目前訂單列表篩選不接受它；GET /fills?order_status=matched 仍受支援。查詢這類訂單時可取得較寬範圍的列表後檢查回傳狀態，不要傳送 status=matched。

篩選會在完整匹配交易集合上套用，再進行分頁；因此 total 反映全部篩選後的匹配數量，可直接依此分頁。

回應¶

trades 中每筆紀錄的欄位與查詢單筆訂單的回應一致，包含 base_token / quote_token、完整數量明細（remaining_amount、filled_base_amount、filled_quote_amount、notional、remaining_notional）、vl_batch_id、settlement_summary 與公開安全的 settlement_economics。total 反映篩選後的總筆數，而非當前頁大小。

{
  "trades": [
    {
      "trade_id": "00000000-0000-4000-8000-000000000001",
      "owner_address": "0x...",
      "status": "pending",
      "order_type": "limit",
      "symbol": "EURC/USDC",
      "side": "bid",
      "base_symbol": "EURC",
      "quote_symbol": "USDC",
      "base_token": "0x...",
      "quote_token": "0x...",
      "price": "1.085",
      "amount": "1000.0",
      "remaining_amount": "1000.0",
      "filled_base_amount": "0",
      "filled_quote_amount": "0",
      "notional": "1085.0",
      "remaining_notional": "1085.0",
      "from_token": "0x...",
      "to_token": "0x...",
      "from_amount": "1085000000",
      "filled_amount": "0",
      "to_amount": "1000000000",
      "created_at": "2026-04-15T08:00:00+00:00",
      "updated_at": "2026-04-15T08:00:00+00:00",
      "expiration": "1713254400",
      "error": null,
      "error_code": null,
      "uuid_int": "6427948336465191935941739505432058208337171677044006212075520",
      "vl_batch_id": null,
      "settlement_summary": {
        "status": "pending",
        "total_fill_count": 0,
        "pending_fill_count": 0,
        "settled_fill_count": 0,
        "failed_fill_count": 0,
        "reverted_fill_count": 0,
        "latest_settlement_id": null,
        "latest_tx_hash": null,
        "latest_parent_status": null,
        "latest_fill_settlement_status": null,
        "latest_failed_fill_failure_reason": null
      },
      "settlement_economics": {
        "perspective_order_id": "00000000-0000-4000-8000-000000000001",
        "gross_debits": [],
        "gross_credits": [],
        "fees_paid": [],
        "balance_debits": [],
        "balance_credits": []
      }
    }
  ],
  "total": 1
}

提交 VL 批次¶

POST /orders/vl/batch

身份驗證： 每筆同組訂單都需要 EIP-712 Order 簽名

請求主體¶

{
  "orders": [
    {
      "owner_address": "0x...",
      "side": "bid",
      "amount": "100",
      "price": "0.75",
      "order_type": "limit",
      "from_address": "0x...",
      "to_address": "0x...",
      "order_id": "00000000-0000-4000-8000-000000000010",
      "uuid_int": "6427948336465191935942058520151046588146668590738473494773760",
      "signature": "0x...",
      "expiration": 1713254400
    },
    {
      "owner_address": "0x...",
      "side": "bid",
      "amount": "100",
      "price": "0.80",
      "order_type": "limit",
      "from_address": "0x...",
      "to_address": "0x...",
      "order_id": "00000000-0000-4000-8000-000000000011",
      "uuid_int": "6427948336465191935942079787798979146800635051651437980286977",
      "signature": "0x...",
      "expiration": 1713254400
    }
  ]
}

VL 驗證規則¶

規則	說明
批次大小	2 到 50 筆訂單（執行時透過 `GET /config` 的 `limits.vl_batch` 取得當前上限）
相同擁有者	所有同組訂單必須共用同一個 `owner_address`
相同支出代幣	所有同組訂單解析後的 `fromToken` 必須一致
唯一市場	拒絕完全重複的市場與正反向互逆市場
共用分組	所有 `uuid_int` 都必須共用同一個 VL `group_id`
連續腿序	`leg_id` 必須依陣列順序為 `0, 1, 2, ...`

每個同級訂單都沿用 POST /orders 的同一套語意：from_address 是市場基礎代幣，to_address 是報價代幣，且 expiration 為必填。

回應¶

{
  "order_ids": [
    "00000000-0000-4000-8000-000000000010",
    "00000000-0000-4000-8000-000000000011"
  ],
  "amendments": [],
  "cancelled": [],
  "fills": [],
  "vl_group": {
    "primary_id": "00000000-0000-4000-8000-000000000010",
    "max_budget": "80",
    "budget_consumed": null,
    "spent_token": "USDC",
    "status": "pending"
  }
}

order_ids 按提交順序標識所有腿，不證明每條腿已掛單或已結算。替換訂單前應逐腿核對訂單與結算狀態。

下單結果明細¶

批次回應還回傳 amendments、cancelled、fills 和可爲 null 的 vl_group。空陣列只表示本次回應未攜帶相應結果；待確認時不能據此推斷掛單數量。

欄位	說明
`amendments[]`	`order_id`、`original_amount`、`actual_amount`、`reason` 和可選 `quantity_semantics`
`quantity_semantics`	`placement_total_quantity` 表示下單總量，`remaining_quantity` 表示剩餘量；必須按此值解釋 `actual_amount`
`cancelled[]`	下單期間被移除腿的 `order_id` 和 `reason`
`fills[]`	`order_id`、即時 `trades[]`（`quantity`、`price`、可選 `counterparty_order_id`、`ts`）及 `remaining`
`vl_group`	`primary_id`、`max_budget`、`spent_token`、`status`、`budget_consumed`
`vl_group.status`	`confirmed` 表示預算消耗已知；`pending` 表示尚未確認，此時 `budget_consumed` 爲 null

不能把待確認預算當作零，也不能假定每條已簽名腿都按原始數量掛單。舊回應可能省略 quantity_semantics 或 status，不能從欄位缺失推斷已確認。

取消 VL 批次¶

POST /orders/vl/cancel

身份驗證： EIP-712 CancelVLBatch 簽名

請求主體¶

{
  "owner_address": "0x...",
  "vl_batch_id": "00000000-0000-4000-8000-000000000010",
  "signature": "0x..."
}

回應¶

{
  "status": "ok"
}

status 為取消結果，通常為 ok。

查詢單筆訂單的成交紀錄¶

GET /fills/{order_id}

身份驗證： 需要 API Key

查詢參數¶

參數	類型	預設值
`limit`	integer	100
`offset`	integer	0

回應¶

{
  "items": [
    {
      "maker_order_id": "maker-order-id",
      "taker_order_id": "taker-order-id",
      "quantity": "100.0",
      "price": "0.75",
      "settlement_status": "pending",
      "tx_hash": null,
      "timestamp": "2026-04-15T08:00:00+00:00",
      "failure_reason": null,
      "settlement_economics": {
        "perspective_order_id": "taker-order-id",
        "gross_debits": [
          {
            "token": "USDC",
            "token_address": "0x...",
            "amount": "75.0",
            "amount_raw": "75000000"
          }
        ],
        "gross_credits": [
          {
            "token": "EURC",
            "token_address": "0x...",
            "amount": "100",
            "amount_raw": "100000000"
          }
        ],
        "fees_paid": [],
        "balance_debits": [
          {
            "token": "USDC",
            "token_address": "0x...",
            "amount": "75.0",
            "amount_raw": "75000000"
          }
        ],
        "balance_credits": [
          {
            "token": "EURC",
            "token_address": "0x...",
            "amount": "100",
            "amount_raw": "100000000"
          }
        ]
      }
    }
  ]
}

每筆成交的 settlement_status 取值：

pending：結算交易尚未廣播（tx_hash 為 null）
confirming：結算交易已廣播並等待區塊確認（tx_hash 已填入，可在鏈上觀察）
settled：鏈上已最終確認成功
failed：結算層級失敗
reverted：鏈上批次結算合約中的單腿 revert；父結算交易仍可能成功

failure_reason 出現時來自固定的合約 revert 名稱白名單；不在該白名單內的取值會被改寫為 null，確保欄位形態為封閉集合。

成交級 settlement_economics 與訂單級相同，都是公開安全的所有者視角。成交行可以包含 maker_order_id 與 taker_order_id 作為引用，但不會展開交易對手的簽名訂單、協議價差收入或交易對手轉帳拆分。tx_hash 可以公開，因為它是鏈上結算交易引用。

跨訂單列出成交紀錄¶

GET /fills

身份驗證： 需要 API Key

查詢參數¶

參數	類型	預設值	說明
`owner_address`	address	必填	必須與已驗證擁有者相符
`order_status`	string	全部	`pending`、`matched`、`settled`、`cancelled`、`failed`
`settlement_status`	string	全部	`pending`、`confirming`、`settled`、`failed`、`reverted`
`limit`	integer	100	最大 500
`offset`	integer	0	分頁偏移量

回應¶

{
  "items": [
    {
      "maker_order_id": "maker-order-id",
      "taker_order_id": "taker-order-id",
      "quantity": "100.0",
      "price": "0.75",
      "settlement_status": "pending",
      "tx_hash": null,
      "timestamp": "2026-04-15T08:00:00+00:00",
      "failure_reason": null,
      "settlement_economics": {
        "perspective_order_id": "taker-order-id",
        "gross_debits": [],
        "gross_credits": [],
        "fees_paid": [],
        "balance_debits": [],
        "balance_credits": []
      }
    }
  ]
}

結算資金變化與錯誤碼¶

訂單與成交的 settlement_economics 包含 perspective_order_id、gross_debits、gross_credits、balance_debits、balance_credits、fees_paid。代幣金額項包含 token、token_address、展示金額 amount 和原始金額 amount_raw，費用項還包含 type。balance_debits / balance_credits 描述所有者可見的餘額變動。上游提供 balance 項時，公共 API 會將 gross_debits / gross_credits 映射爲相同變動以保持兼容；不能僅憑 gross 名稱將其視爲手續費前交易總額。fees_paid 列出明確展示的費用。不要將 gross 與 balance 陣列相加，也不要從已調整的餘額變動中再次扣除所列費用。

除原有額度/截止時間/滑點/臨時失敗碼外，公共訂單錯誤還包括 STP_BLOCKED、INSUFFICIENT_EQUITY、PAIR_INACTIVE、AMOUNT_BELOW_MIN、QUOTE_STALE、COMPLIANCE_BLOCKED、DUPLICATE_ORDER_ID、INVALID_PRECISION、INVALID_DECIMAL_FORMAT。提交業務錯誤使用 detail.error_code，已存訂單的 error_code 描述訂單結果。校驗/鑑權錯誤也可能只有字串 detail。這些結構不能與 Exact Output 或篩查混用。

VL 下單的每一腿只接受 order_type="limit"。獨立訂單支持 market 不代表 /orders/vl/batch 也接受它。

已存訂單與提交錯誤碼¶

`error_code`	含義與處理
`ALLOWANCE_INSUFFICIENT`	allowance 不足或 permit 無效/過期；確認原請求不能執行後，重新授權或簽 permit
`INTENT_DEADLINE_EXPIRED`	已簽名截止時間過期；確認原請求結果後，使用新截止時間創建新訂單
`SLIPPAGE_EXCEEDED`	無法按已簽名價格執行；核對原訂單後再調整價格
`NO_LIQUIDITY`	當前價格下無可執行深度；核對結果後減量或選擇其他市場
`QUOTE_STALE`	報價/計劃或簽名截止時間過期；確認前次不能執行後重新提交
`AMOUNT_BELOW_MIN`	金額低於最低要求；提高金額
`STP_BLOCKED`	會與自己的訂單成交；取消原掛單或調整方向
`INSUFFICIENT_EQUITY`	支出代幣可用抵押品不足；充值或取消佔用餘額的訂單
`PAIR_INACTIVE`	市場未激活；使用 `GET /markets` 選擇活躍市場
`TRANSIENT_SETTLEMENT_FAILURE`	未映射或暫時性結算失敗；保留原請求身份，查詢後按重試規則處理

GET /orders/{order_id} 的 error_code 描述已存訂單結果；提交拒絕使用 detail.error_code。error 是展示用錯誤文本，不應作為客戶端分支依據。其餘校驗、合規及重復 ID 錯誤見上文。