---
# 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)

#### 返回

- dexId
- dexAddr 存放手续费资金池地址
- createdAt 


### 查询 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


#### 返回


- dexId
- uniqueCode
- displayName
- owner
- baseAssetId
- baseAssetCode
- baseAssetPrecision
- quoteAssetId
- quoteAssetCode
- quoteAssetPrecision
- status


### 查询交易对

GET `/api/v1/symbols`


#### 参数

- symbolId
- owner
- status


#### 返回

- items
    - symbolId
    - uniqueCode
    - displayName
    - baseAssetId
    - baseAssetCode
    - baseAssetPrecision
    - baseMinSize
    - quoteAssetId
    - quoteAssetCode
    - quoteAssetPrecision
    - quoteMinSize
    - owner
    - status
    - feeRate
    - feeSide
    - settleAssetId

### 启用交易对

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


<!-- ### 设置交易费规则
交易对启用前才能够设置接口
POST `/api/v1/symbols/fee`

#### 参数

- symbolId
- feeRate
- feeSide

#### 返回

同交易对查询 -->

### 修改交易费规则

修改接口只有在交易对冻结的情况下才能修改
UPDATE `/api/v1/symbols/fee`

#### 参数

- symbolId
- takerFeeRate
- makerFeeRate
- feeSide
- settleAssetId?

#### 返回

- symbolId
- uniqueCode
- displayName
- baseAssetId
- baseAssetCode
- baseAssetPrecision
- baseMinSize
- quoteAssetId
- quoteAssetCode
- quoteAssetPrecision
- quoteMinSize
- owner
- status
- takerFeeRate
- makerFeeRate
- feeSide: base|quote
- settleAssetId
- settleAssetCode


### 设置交易对撮合结算币种(可以有折扣)
POST `/api/v1/symbols/settle`

#### 参数

- symbolId
- settleAssetId?
- settleAssetPrecision?
- settleDiscountRate?
- settleAssetAmount?

#### 返回

- symbolId
- settleAssetId
- settleAssetCode
- settleAssetPrecision
- settleDiscountRate
- settleAssetAmount

### 更新交易对撮合结算币种

UPDATE `/api/v1/symbols/settle`

#### 参数

- symbolId
- settleAssetId?
- settleAssetPrecision?
- settleDiscountRate??
- settleAssetAmount?


#### 返回

- symbolId
- settleAssetId
- settleAssetCode
- 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`





## KuChain 撮合引擎相关 API 梳理文档(前端调用渲染网页和进行API交易)



## Markets

### 获得订单薄 level1

GET `/api/v1/market/orderbook/level1`

#### 参数

- symbolId


#### 返回

- bestAsk
- size
- price
- bestBidSize
- bestBid
- bestAskSize


### 获得订单薄 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

#### 返回

<!-- - 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
 -->
 
 


### 查询订单

GET `/api/v1/orders/{orderID}`

#### 参数


- orderId

#### 返回

同上



### 取消单个订单

DELETE `/api/v1/orders/{orderID}`

#### 参数


- orderId

#### 返回

同上



### 批量取消订单

DELETE `/api/v1/orders`

#### 参数

- dexId
- address
- symbolId?

#### 返回

- cancelledOrderIds




### 获得订单列表

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 频率，保证链的处理性能? - 撮合引擎提交需要一个逻辑，超过阈值应该立即提交，防止单次提交计算量过大