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

<!-- ### 设置交易费规则
交易对启用前才能够设置接口
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`

#### 参数

- 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

#### 返回

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

#### 返回

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

#### 返回

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