--- # System prepended metadata title: KuChain API 交互文档 --- # KuChain API 交互文档 ## KuChain链上API（由DEX运营方调用主链） ### 注册 Dex 用户需要支付一定的 KCS 来注册 Dex 账户 POST `/api/v1/dex` #### 参数 - uniqueName - displayName - websiteUrl - iconUrl - owner - description - defaultFeeRate: 0.001 (0 - 0.001) #### 返回 ### 查询 Dex 信息 GET `/api/v1/dex` #### 参数 - uniqueName - dexId #### 返回 - dexId - dexAddress 存放手续费资金池地址 - uniqueName - displayName - websiteUrl - iconUrl - owner - description - createdAt ### 注册交易对 POST `/api/v1/symbols` #### 参数 - dexId - uniqueCode - displayName - owner - baseAssetId - baseAssetPrecision - quoteAssetId - quoteAssetPrecision #### 返回 ### 查询交易对 GET `/api/v1/symbols` #### 参数 - symbolId - owner - status #### 返回 - items - symbolId - uniqueCode - displayName - baseAssetId - baseAssetCode - baseAssetPrecision - baseMinSize - quoteAssetId - quoteAssetCode - quoteAssetPrecision - quoteMinSize - owner - status - feeRate - feeSide - settleAssetId - settleAssetCode - settleAssetPrecision - settleDiscountRate - settleAssetAmount ### 启用交易对 POST `/api/v1/symbols/launch` #### 参数 - dexId - symbolId ### 下架交易对 POST `/api/v1/symbols/close` #### 参数 - dexId - symbolId ### 冻结交易对 POST `/api/v1/symbols/freeze` #### 参数 - dexId - symbolId ### 解冻交易对 POST `/api/v1/symbols/unfreeze` #### 参数 - dexId - symbolId ### 修改交易费规则 修改接口只有在交易对冻结的情况下才能修改 UPDATE `/api/v1/symbols/fee` #### 参数 - symbolId - takerFeeRate - makerFeeRate - feeSide - settleAssetId? #### 返回 ### 设置交易对撮合结算币种(可以有折扣) POST `/api/v1/symbols/settle` #### 参数 - symbolId - settleAssetId? - settleAssetPrecision? - settleDiscountRate? - settleAssetAmount? #### 返回 ### 更新交易对撮合结算币种 UPDATE `/api/v1/symbols/settle` #### 参数 - symbolId - settleAssetId? - settleAssetPrecision? - settleDiscountRate?? - settleAssetAmount? #### 返回 ### 查询手续费资金池 GET `/api/v1/feepool` #### 参数 - dexId #### 返回 - assets - assetId - assetCode - balance ### 提现手续费资金池到DEX创建者账号 POST `/api/v1/feepool/claim` #### 参数 - dexId - assetId - amount? #### 返回 - txId --- ### 提交撮合成功的订单列表(完成链上撮合和清算) POST `/api/v1/execute-orders` #### 参数 - dexId - trxs ## KuChain 撮合引擎相关 API 梳理文档(前端调用渲染网页和进行API交易) ## Markets ### 获得订单薄 level1 GET `/api/v1/market/orderbook/level1` #### 参数 - symbolId #### 返回 - bestAsk - size - price - bestBidSize - bestBid - bestAskSize - bestAsk ### 获得订单薄 level2（聚合） GET `/api/v1/market/orderbook/level2` #### 参数 - symbolId - deepth (20 || 100)? #### 返回 - bids[] - price - size - asks[] - price - size ### 获得订单薄 level3 (非聚合结果) GET `/api/v1/market/orderbook/level3` #### 参数 - symbolId #### 返回 - bids[] - price - size - asks[] - price - size ### 获得全局行情快照 GET `/api/v1/market/allTickers` #### 返回 - time - tickers - symbolId - bid - ask - changeRate - changePrice - high - low - vol - volValue - last ### 获得市场成交历史 GET `/api/v1/market/histories` #### 参数 - symbolId #### 返回 - item - time - price - size - side ### 获得历史蜡烛图数据 GET `/api/v1/market/candles` #### 参数 - type 1min, 3min, 5min, 15min, 30min, 1hour, 2hour, 4hour, 6hour, 8hour, 12hour, 1day, 1week - symbolId - startAt - endAt #### 返回 - time - open - close - high - low - volume - turnover ## Orders ### 下单 POST `/api/v1/order` #### 参数 - dexId - symbolId - address - side - price - amount - type - remark - timeInForce - orderId #### 返回 ### 查询订单 GET `/api/v1/orders/{orderID}` #### 参数 - orderId #### 返回 - fee - feeAssetId - lastExecutedPrice - lastExecutedQuantity - orderCreateTime - orderId - owner - price - quantity - side - status [Ack, PartialFill, IocNoFill, FullyFill, Canceled, Expired, FailedBlocking, FailedMatching, IocExpire] - symbolId - timeInForce - tradeId - txHash - txTime ### 取消单个订单 DELETE `/api/v1/orders/{orderID}` #### 参数 - orderId #### 返回 ### 批量取消订单 DELETE `/api/v1/orders` #### 参数 - dexId - address - symbolId? #### 返回 ### 获得订单列表 GET `/api/v1/orders` #### 参数 - status (active||done)？ - symbolId？ - side？ - address？ - startAt？ - endAt？ - offset - limit #### 返回 - totalzNum - items - fee - feeAssetId - lastExecutedPrice - lastExecutedQuantity - orderCreateTime - owner - price - quantity - side - status - symbolId - timeInForce - tradeId - txHash - txTime - clientOrderId - orderId ### 最近的订单记录 GET `/api/v1/hist-orders` #### 参数 - symbolId - side - startAt - endAt - offset - limit #### 返回 - totalNum - items - fee - feeAssetId - lastExecutedPrice - lastExecutedQuantity - orderCreateTime - orderId - owner - price - funds - size - dealFunds - dealSize - side - status [Ack, PartialFill, IocNoFill, FullyFill, Canceled, Expired, FailedBlocking, FailedMatching, IocExpire] - symbolId - timeInForce - tradeId: 撮合成交id ### 成交记录 GET `/api/v1/fills` #### 参数 - orderId - symbolId - side - startAt - endAt - address - offset - limit #### 返回值 - symbolId - tradeId - orderId - txId - counterOrderId - side - liquidity (taker || maker) - price - size - funds - fee - feeRate - feeAssetId - createdAt ## 问题梳理 - Dex 的接口是否考虑多 Dex 的扩展? 不用，查询所有启用的DEX是链的基础API - 列表相关的接口是否支持分页查询？ 理论上需要 - 手续费接口是否需要结合一些具体的治理和链上逻辑去设计（例如之前讨论的如何给不同的节点做优惠） - 手续费抵扣和只收取某种币混合起来设计会不会有性能问题 - 订单创建的 orderId 什么样的规律生成？ 建议客户端生成 - 订单创建的内容是否完全由用户定义在签名体中？ 理论上是的 - 是否能够支持撮合引擎单次 commit 多条成交到链上，如何控制 commit 频率，保证链的处理性能? - 撮合引擎提交需要一个逻辑，超过阈值应该立即提交，防止单次提交计算量过大