整數金額 API（v2）¶

v2 接口以十進制字串接收和回傳整數金額。現有 v1 接口繼續保留。本頁路徑已包含 /api/v2，不要將其拼接到 /api/v1 基礎 URL 後。

金額與價格¶

amount_raw 是基礎代幣的最小單位數量；展示時除以 10 ** base_decimals。
price_tick 是報價/基礎價格乘以 10 ** tick_precision。金額計算必須使用整數或精確十進制，不能使用 JavaScript Number。
當前市場滿足 quantity_precision = base_decimals、tick_precision = quote_decimals；請從 GET /api/v1/markets 讀取。
請求金額必須是正 uint256 字串。回應中的 left_amount_raw 等數量可以爲 "0"。raw_encoding 固定爲 "int"。

下單¶

POST /api/v2/orders

身份驗證： EIP-712 Order 簽名。可選 API Key 必須屬於同一所有者。

請求體¶

{
  "owner_address": "0x...",
  "side": "bid",
  "amount_raw": "1000000000",
  "price_tick": "1085000",
  "order_type": "limit",
  "from_address": "0x...",
  "to_address": "0x...",
  "order_id": "00000000-0000-4000-8000-000000000001",
  "uuid_int": "6427948336465191935941739505432058208337171677044006212075520",
  "signature": "0x...",
  "expiration": 1800000000,
  "fee_bps": 0
}

示例假定兩種代幣及價格均爲六位精度。簽名前請替換地址、標識符和截止時間。

欄位	必填	說明
`owner_address`	是	簽名錢包
`side`	是	`bid` 或 `ask`
`amount_raw` / `price_tick`	是	正 uint256 十進制字串；不接受 `amount` / `price`
`from_address` / `to_address`	是	市場基礎/報價代幣地址，不隨買賣方向改變
`order_type`	是	`limit` 或 `market`；此接口不接受 `fok`、`IOC`、`post_only`
`order_id` / `uuid_int`	是	相互綁定的標識符，遵循 UUID 規則
`signature`	是	EIP-712 Order 簽名
`expiration`	是	未來的 Unix 秒數，最多領先 365 天減 300 秒
`fee_bps`	否	非負 uint48 整數，預設 0；進入簽名 Order 的 `feeBps`
`client_id`	否	請求模型接受，但不作爲訂單標識符或冪等鍵傳遞

簽名 Order 使用原始 fromAmount / toAmount。當前市場精度下，基礎數量爲 amount_raw，報價數量爲 floor(amount_raw * price_tick / 10 ** base_decimals)。買單支出報價數量、接收基礎數量；賣單相反。也可將對應的自然單位值傳給訂單預覽，簽署回傳的 eip712_order。簽名域取自 GET /api/v1/config。

回應¶

HTTP 201：

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

查詢訂單¶

GET /api/v2/orders/{order_id}
GET /api/v2/orders

身份驗證： 需要 API Key。所有者來自憑據，這兩個接口均不要求 owner_address 查詢參數。

列表參數¶

參數	預設值	說明
`status`	全部	存儲的訂單狀態，不是 v1 展示狀態
`symbol`	全部	市場標識
`limit`	100	1–1000
`before_timestamp`	無	時間戳遊標
`before_order_id`	無	與時間戳遊標配套的訂單 ID

列表回傳 JSON 陣列，不是 {trades, total}。v2 回應沒有 offset、total、next_cursor 或 created_at。不能從未回傳的欄位推導時間戳遊標；請使用應用已經掌握的時間邊界。如需帶創建時間和總數的展示型歷史分頁，請使用 v1 GET /orders。

訂單欄位¶

欄位	說明
`order_id`、`owner_address`、`symbol`、`side`、`order_type`	訂單身份與市場
`status`	`submitted`、`open`、`filled`、`partially_filled`、`cancelled`、`rejected`、`failed`；`filled` 本身不代表鏈上已結算
`amount_raw`、`left_amount_raw`、`filled_base_amount_raw`	原始、剩餘及已成交基礎代幣數量
`filled_quote_amount_raw`、`price_tick`	已成交報價代幣數量和整數價格
`quantity_precision`、`tick_precision`、`base_decimals`、`quote_decimals`	用於解釋數值的整數精度元數據
`raw_encoding`	`"int"`
`expiration`、`uuid_int`、`vl_batch_id`、`error`、`error_code`	可爲 null 的元數據；此處 `expiration` 是整數，與 v1 字串不同

查詢成交¶

GET /api/v2/fills/{order_id}
GET /api/v2/fills

身份驗證： 需要 API Key。只回傳憑據所有者的記錄。

兩個接口均接受 limit（預設 100，最大 500）和 offset（預設 0，最大 10000）。賬戶級接口還接受 settlement_status，不支援 v1 的 order_status 篩選。

均回傳 { "items": [...] }。每項包含 quantity_raw、price_tick、settlement_base_amount_raw、settlement_quote_amount_raw、maker_order_id、taker_order_id、is_taker_buyer、settlement_status、raw_encoding，以及可爲 null 的 trade_id、timestamp、tx_hash、failure_reason。應根據結算證據區分撮合完成與轉賬確認。

餘額與取消¶

GET /api/v2/balances

這是 v1 餘額接口的別名：需要 API Key，owner_address 必須匹配已認證所有者，include_zero 預設爲 false，金額仍爲 raw 字串。

取消操作繼續使用已簽名的 v1 取消接口，沒有獨立的 v2 取消路由。4xx/503 處理請參閱錯誤回應。

餘額同步¶

POST /api/v2/balances/sync 與 v1 餘額同步共用必填欄位、API Key 所有者校驗、HTTP 202 回應和版本衝突處理。先讀取 capabilities.balances.sync_enabled。v2 餘額同樣回傳可花資格與恢復欄位，不能僅憑 vault_available 判斷可花金額。include_zero=false 仍可保留有恢復或同步狀態的零餘額行。