跳轉至

訂單端點

預覽限價單

POST /orders/preview

身份驗證： 無

簽名前先呼叫預覽。該端點只校驗公開市場中繼資料和請求欄位，並回傳應當展示、 簽名和最終提交的規範化數值與 EIP-712 Order payload。

請求主體

{
  "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",
  "expiration": 1713254400
}

from_address 是市場基礎代幣，to_address 是市場報價代幣。side 決定簽名 Order 中實際支出的代幣：bid 支出報價代幣，ask 支出基礎代幣。

回應

{
  "ok": true,
  "symbol": "EURC/USDC",
  "side": "bid",
  "normalized_amount": "1000",
  "normalized_price": "1.085",
  "amount_step": "0.01",
  "price_step": "0.0001",
  "rounding_mode": "reject_extra_precision",
  "canonicalization_required": false,
  "from_token": "0x...",
  "to_token": "0x...",
  "from_amount": "1085000000",
  "to_amount": "1000000000",
  "notional": "1085.000000",
  "eip712_order": {
    "user": "0x...",
    "expiration": "1713254400",
    "feeBps": "0",
    "recipient": "0x0000000000000000000000000000000000000000",
    "fromToken": "0x...",
    "toToken": "0x...",
    "fromAmount": "1085000000",
    "toAmount": "1000000000",
    "initialDepositAmount": "0",
    "uuid": "6427948336465191935941739505432058208337171677044006212075520"
  },
  "eip712_types": {
    "Order": [
      { "name": "user", "type": "address" }
    ]
  }
}

eip712_types.Order 在真實回應中包含完整 Order 類型；上例為簡寫。請按回傳的 eip712_order 簽名，然後用 normalized_amount 和 normalized_price 提交最終 POST /orders。

預覽不會檢查餘額、可用流動性、帳戶資格或其他最終提交檢查。這些檢查在最終提交時執行。

掛限價單

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 是 市場 amount_step 網格上的規範數量字串
price string 是 市場 price_step 網格上的規範價格字串
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 取得。

amount 與 price 必須是普通 fixed-point 十進位字串：不能包含正負號、 指數、分隔符、逗號、底線或空白。最終下單會在簽名驗證前拒絕非規範字串和 非零額外精度。請先呼叫 POST /orders/preview，並按回傳的規範值提交。

回應

{
  "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" }
    ],
    "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" }
    ],
    "fees_paid": []
  }
}

回應說明

  • 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 是該訂單已知成交的公開、所有者視角資金變化。它包含相容欄位 gross_debits / gross_credits、建議用於對帳的 balance_debits / balance_credits，以及類似 gas 的明確使用者可見 fees_paid。
  • 錢包或 Vault 資金變動展示應使用 settlement_economics.balance_debits 和 settlement_economics.balance_credits。公共 gross_debits / gross_credits 是相容欄位，應視為所有者可見的公開總額，不應用於重構公開回應 schema 之外的值。
  • filled_amount / filled_base_amount / filled_quote_amount 在有結算經濟資料時是所有者可見的進度值。from_amount 等來源代幣原始金額優先來自簽名或會計原始值，而不是用十進位展示價格重新計算。

外部訂單狀態包括：

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

錯誤信封

POST /orders 的 4xx 失敗會回傳結構化信封：

{
  "detail": {
    "detail": "Order placement failed",
    "error_code": "INSUFFICIENT_EQUITY"
  }
}

請依 error_code 分支；人類可讀的 detail 只用於顯示。

error_code 何時出現 客戶端動作
ALLOWANCE_INSUFFICIENT ERC-20 授權不足，或 permit 簽名無效 / 過期 重新 permit 或 approve 後重試
INTENT_DEADLINE_EXPIRED 簽名截止時間已過 用新的截止時間重新下單
SLIPPAGE_EXCEEDED IOC/FOK 無法按簽名價格成交 放寬滑點後重新提交
NO_LIQUIDITY 該價格沒有可成交深度 降低數量或更換交易對
QUOTE_STALE 報價、計劃或簽名截止時間過期 提交新的訂單
AMOUNT_BELOW_MIN 金額低於市場最小值 增加金額
INVALID_PRECISION amount 或 price 超出市場精度且包含非零額外位數 使用預覽回傳的規範值重試
INVALID_DECIMAL_FORMAT amount 或 price 不是規範 fixed-point 正數十進位字串 按預覽回傳的格式重新提交
STP_BLOCKED 自成交保護：訂單會與自己的反向掛單成交 撤銷已有掛單或調整方向
INSUFFICIENT_EQUITY 可用餘額不足以覆蓋支出代幣凍結額 充值或撤銷占用餘額的訂單
PAIR_INACTIVE 交易對目前不可交易 使用 GET /markets 查詢可交易市場
TRANSIENT_SETTLEMENT_FAILURE 非客戶端可修復的暫時失敗或安全預設值 稍後重試；持續出現時聯絡支援

列出訂單

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": [],
        "balance_debits": [],
        "balance_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" }
        ],
        "balance_debits": [
          { "token": "USDC", "token_address": "0x...", "amount": "75.0", "amount_raw": "75000000" }
        ],
        "balance_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 與訂單級相同，都是公開安全的所有者視角。成交行的 price 在會計提供所有者有效價格時使用該公開價格。成交行可以包含 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": [],
        "balance_debits": [],
        "balance_credits": [],
        "fees_paid": []
      }
    }
  ]
}