DEX 限价单 API 完整操作手册

想依托一套极简接口，把 限价单交易、跨链聚合、钱包管理打包进 DApp？本指南围绕 DEX API、限价单 API、Web3 API、钱包即服务 等关键词，拆解全套开发要点，帮助你在 30 分钟内完成从申请权限到订单上线的完整链路。文章末还准备了高频 FAQ，照着操作，能直接跑通 Demo。

第一节：准备工作

1.1 钱包即服务接入清单

Web3 API Docs 把接入流程切割为三步：

注册开发者账号 → 获得 API Key
参照 接入前提 检查应用包名、签名、Bundle ID 是否与申请表一致
在后台勾选可用网络（见下一节）

完成上述步骤后，后端会颁发两个凭证：

public_key：公开参数，用于验签
private_secret：高保密，仅限服务器到服务器调用

👉 还没拿到 API Key？点击 5 秒取码通道，秒过开发测试期

1.2 支持的网络

GET /dex/v1/markets/chains 可查实时列表，当前覆盖：

EVM：Ethereum、BSC、Polygon、Arbitrum、Optimism
非 EVM：Solana、Tron、Aptos
BTC 生态：Bitcoin 主网（Ordinals、Runes）、Fractal Bitcoin

你只需要在前端轮询一次，缓存结果即可，无需每次都查。

第二节：钱包 API 速通

本小节帮助你熟悉 钱包 API 的核心方法，为后面创建 限价单 API 打地基。

2.1 链上信息查询

余额查询：GET /wallet/v1/{chain}/balance?address={addr}
返回数组，包含代币地址、符号、余额、美元估值
Nonce 查询：GET /wallet/v1/{chain}/nonce?address={addr}
用于原生链手续费计算，避免交易被覆盖

2.2 交易广播

创建并签名后，把 hex raw tx 通过 POST /wallet/v1/broadcast 推送，接口会自动选择最优 RPC，失败自动重试 3 次，无需额外队列。

示例代码（Node.js）

await fetch(`${base}/wallet/v1/broadcast`, {
  method: 'POST',
  headers: { 'X-Api-Key': key },
  body: JSON.stringify({ chain: 'ethereum', rawTx })
});

第三节：限价单 API 完整链路

本节拆解 创建 → 查询 → 取消 三条主干，同时穿插捕获授权、手续费预估、失败重试等细节。

3.1 获取币种列表 & 授权额度

币种列表是前端展示价格的卡点。调用 GET /dex/v1/tokens?chain={chain}，30 分钟缓存即可：

{
  "symbol": "USDC",
  "address": "0x...",
  "decimals": 6,
  "logo": "https://...",
  "is_native": false
}

接着查询 授权额度：
GET /dex/v1/allowance?chain={}&token={}&owner={}&spender={}
返回 allowance 数值，低于下单数量就需先授权。

一键授权 只需两步：

调 POST /dex/v1/approve-calldata 获取交易体
用钱包 API 广播，成功后等待 1～2 区块确认

👉 想直接体验一键授权 Demo？立刻体验零 gas 测试网

3.2 创建限价单

核心接口：POST /dex/v1/limit-order/create

字段	描述
chain	目标网络
maker	你的用户地址
tokenIn	支付币种
tokenOut	获得币种
amountIn	锁定数量（需先授权）
amountOutMin	期望最少收到数量
price	限价
deadline	UTC 时间戳，默认 7 天

成功后将返回 orderHash，后续查询 / 取消都需要它。

场景示例：用户想把 100 USDC 换 0.045 ETH，限价 2222 USDC/ETH，前端填写 amountIn = 1e8，amountOutMin = 45000000000000000。

3.3 查询与取消

列表查询：GET /dex/v1/limit-order/list?maker={} 支持分页、状态过滤
订单详情：GET /dex/v1/limit-order/{orderHash} 返回剩余可成交额度、成交历史
撤销订单：先 GET /dex/v1/limit-order/{orderHash}/cancel-calldata 获取 calldata，再钱包 API 广播即可。注意撤销也有矿工费，要提前留足。

第四节：跨链聚合加速版

当大单价差跨多条链时，可沿用上节订单结构，只要在 chain 字段填入 目标链 ID，系统先内部桥接，再挂单撮合，用户完全无感。该功能由 跨链 API 组合 限价单 API 完成，开发者无需额外调用。

第五节：典型业务场景参考

DEX Aggregator：前端汇聚 限价单、市价池子、跨链桥，自定路由策略
GameFi 兑换：玩家领取奖励时自动 创建限价单 卖掉代金币，后台静默执行
资产管理：基金机器人实时监控 订单状态，修改 amountOutMin 后撤回再重建，锁定滑点

第六节：智能合约层补充

平台限价单其实运行在链上合约 OKXLimitOrderBook.sol，源码已开源审计：

采用 EIP-712 结构化签名，前端无需私钥落盘
支持部分成交，资金安全留存合约，可随时撤回
通过链下 Keeper 网络广播撮合，成交即结算

常见问题 FAQ

Q1：没有服务器，纯前端可以下发限价单吗？
A：不行。创建接口需要 API Key + Secret，必须走 BFF 中继，否则明文 Secret 会泄露。

Q2：限价单最长有效期？
A：7 天。你可以在 deadline 字段自定义，但网络会回退到 7 天上限。

Q3：手续费谁来付？
A：

链上 gas：maker 自付
撮合成功后的协议费：平台按万分之三收取，已从成交币自动扣除

Q4：测试网能跑完整链路吗？
A：支持 Sepolia、BNB Testnet、Polygon Mumbai 等网络。授权额度、下单过程完全一致，可直接 Fork 官方代码仓库的 Jest 用例。

Q5：能否批量取消多个 orderHash？
A：目前需逐条调用。未来版本会开放批量接口，届时返回 txnHash 一并撤销多笔。

Q6：如果 Keeper 宕机怎么办？
A：Keeper 公开可部署，社区可运行备用节点；Keepers 超时未执行时，用户随时可在链上 cancel 合约调用 SafeExit 取回资产。

至此，你已掌握基于 DEX API 打造一整套 限价单系统 的全部招式：获取币种、授权、挂单、查单、撤单，加跨链一步到位。接下来，放开手去测试网实验吧！