訂單端點¶

掛限價單¶

POST /orders

身份驗證： EIP-712 Order 簽名

請求主體¶

{
  "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",
  "signature": "0x...",
  "expiration": 1713254400
}

欄位	類型	必填	說明
`owner_address`	address	是	訂單擁有者的錢包地址
`side`	string	是	`bid` 或 `ask`
`amount`	string	是	自然單位數量（基礎代幣側）
`price`	string	是	自然單位價格（報價 / 基礎）
`order_type`	string	是	使用 `limit`
`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 秒`

目前公共 API 不接受 client_id 與 fee_bps。

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

回應¶

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

取消訂單¶

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，請先查詢訂單；訂單狀態回應中會回傳該欄位。

取消所有訂單¶

DELETE /orders/cancel-all

身份驗證： 需要 API Key

查詢參數¶

參數	類型	必填	說明
`owner_address`	address	是	必須與已驗證 API Key 的擁有者相符

回應¶

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

total 表示成功取消的訂單數量。

取得訂單¶

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": [
      { "type": "gas", "token": "USDC", "token_address": "0x...", "amount": "0.42", "amount_raw": "420000" }
    ]
  }
}

回應說明¶

order_type 對限價單與 VL 流程為 limit，透過 POST /swap 建立的訂單為 swap。
expiration 存在時會以字串形式回顯簽名中的訂單截止時間。
error_code 是結構化的終態失敗碼。目前公共值包括 ALLOWANCE_INSUFFICIENT、INTENT_DEADLINE_EXPIRED、SLIPPAGE_EXCEEDED 與 TRANSIENT_SETTLEMENT_FAILURE；任何未識別的內部失敗都會折疊為 TRANSIENT_SETTLEMENT_FAILURE。
vl_batch_id 會在該訂單屬於虛擬流動性批次時出現。
settlement_summary 彙總該訂單各筆成交的結算進度。latest_failed_fill_failure_reason 是經過白名單篩選的合約 revert 名稱（不在公開白名單內的值會回傳 null）。
settlement_economics 是該訂單已知成交的公開、所有者視角資金變化。它只包含 gross_debits、gross_credits 和類似 gas 的 fees_paid，不暴露協議價差收入或交易對手的轉帳拆分。
正價差成交時，filled_amount / filled_quote_amount 不一定等於使用者實際扣除的來源代幣總額。錢包或 Vault 資金變動展示應使用 settlement_economics.gross_debits 和 settlement_economics.gross_credits。

外部訂單狀態包括：

pending：已提交、仍在掛單中或部分成交，訂單仍可繼續成交或被取消
matched：所有腿在撮合引擎中已交叉，但鏈上結算仍在進行；該匹配將完成結算（或透過 settlement_summary 暴露 revert 原因），不會回到 pending
settled：鏈上確認的最終成功狀態
failed：鏈上確認的 revert，或在廣播前的失敗 / 拒絕
cancelled：最終取消

列出訂單¶

GET /orders

身份驗證： 需要 API Key

查詢參數¶

參數	類型	預設值	說明
`owner_address`	address	必填	必須與已驗證擁有者相符
`limit`	integer	50	最大 500
`offset`	integer	0	分頁偏移量
`status`	string	全部	依外部狀態篩選：`pending`、`matched`、`settled`、`cancelled`、`failed`。
`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`

篩選會在完整匹配交易集合上套用，再進行分頁；因此 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": []
      }
    }
  ],
  "total": 1
}

提交 VL 批次¶

POST /orders/vl/batch

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

請求主體¶

{
  "orders": [
    {
      "owner_address": "0x...",
      "side": "bid",
      "amount": "100.0",
      "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.0",
      "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"
  ]
}

取消 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.0", "amount_raw": "100000000" }
        ],
        "fees_paid": []
      }
    }
  ]
}

每筆成交的 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": []
      }
    }
  ]
}