订单端点¶

下限价单¶

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 错误见上文。