订单端点¶

下限价单¶

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