跳转至

订单端点

预览限价单

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