整数金额 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 仍可保留有恢复或同步状态的零余额行。