# Trade 接口

在下面查询相关接口中，返回的卖单都一个一种格式，买单也是一种格式，只在第一个卖单或买单查询中列出其格式，不重复。

**卖单买单状态说明：**

| 状态 | 名称                       | 说明                         |
| :--- | :------------------------- | :--------------------------- |
| 1    | TradeOrderStatusOnSale     | 在售                         |
| 2    | TradeOrderStatusSoldOut    | 售完                         |
| 3    | TradeOrderStatusRevoked    | 卖单被撤回                   |
| 4    | TradeOrderStatusExpired    | 订单超时(目前不支持订单超时) |
| 5    | TradeOrderStatusOnBuy      | 求购                         |
| 6    | TradeOrderStatusBoughtOut  | 购买完成                     |
| 7    | TradeOrderStatusBuyRevoked | 买单被撤回                   |

Buy/Sell ID 在创建交易时不需要带上前缀 “mavl-trade-sell-“ 或 “mavl-trade-buy-“

## 1 查询地址对应的买单 GetOnesBuyOrder

只指定地址，同时指定地址和token

**调用接口**

```
rpc QueryChain(ChainExecutor) returns (Reply) {}
```

**参数：**

```
message ChainExecutor {
    string driver    = 1;
    string funcName  = 2;
    bytes  stateHash = 3;
    bytes  param     = 4;
    bytes  extra     = 5;
}
message ReqAddrAssets {
    string addr               = 1;
    int32  status             = 2;
    repeated string token     = 3;
    int32           direction = 4;
    int32           count     = 5;
    string          fromKey   = 6;
}
```

**参数说明：**

| 参数      | 类型     | 是否必须 | 说明                                                         |
| :-------- | :------- | :------- | :----------------------------------------------------------- |
| driver    | bytes    | 是       | 执行器名称, 这里固定为 trade                                 |
| funcName  | string   | 是       | 操作名称, 这里固定为 GetOnesBuyOrder                         |
| stateHash | bytes    | 否       | 所有交易在对应的执行器执行后写入KVDB中重新计算得到的新state的哈希值 |
| param     | bytes    | 是       | types.Encode(&)                                              |
| extra     | bytes    | 否       | 扩展字段，用于额外的用途                                     |
| addr      | string   | 是       | 买单持有人                                                   |
| token     | []string | 是       | 具体的token的标识符，可以是多个                              |
| status    | int32    | 否       | 状态                                                         |
| direction | int32    | 否       | 查询的方向                                                   |
| count     | int32    | 否       | 最多取的数量                                                 |
| fromKey   | string   | 否       | 开始查询的主键                                               |

**返回数据：**

```
message ReplyTradeOrders {
    repeated ReplyTradeOrder orders = 1;
}
message ReplyTradeOrder {
    string tokenSymbol       = 1;
    string owner             = 2;
    int64  amountPerBoardlot = 3;
    int64  minBoardlot       = 4;
    int64  pricePerBoardlot  = 5;
    int64  totalBoardlot     = 6;
    int64  tradedBoardlot    = 7;
    string buyID             = 8;
    int32  status            = 9;
    string sellID            = 10;
    string txHash            = 11;
    int64  height            = 12;
    string key               = 13;
    int64  blockTime         = 14;
    bool   isSellOrder       = 15;
    string assetExec         = 16;
    string priceExec         = 17;
    string priceSymbol       = 18;
}
```

**参数说明：**

| 参数              | 类型   | 说明                                                         |
| :---------------- | :----- | :----------------------------------------------------------- |
| result            | -      | 对应买单的列表                                               |
| key               | string | 可能是 buyID 或 txhash。 在现价买单中是txHash， 在限价买单中是 buyID |
| txHash            | string | 对应交易的hash                                               |
| sellID            | string | 卖单id                                                       |
| buyID             | string | 买单id                                                       |
| tokenSymbol       | string | token的标识符                                                |
| owner             | string | token购买者的地址                                            |
| blockTime         | int64  | 出块的 UTC 时间                                              |
| isSellOrder       | string | 是否是买单                                                   |
| status            | bool   | 买单状态                                                     |
| height            | int64  | 买单所在区块的高度                                           |
| amountPerBoardlot | int64  | 每一手成交的数量                                             |
| minBoardlot       | int64  | 一次购买最少成交的数量                                       |
| pricePerBoardlot  | int64  | 一手成交的价格                                               |
| totalBoardlot     | int64  | 总共购买的手数                                               |
| tradedBoardlot    | int64  | 已经成交手数                                                 |
| assetExec         | string | 资产来源的执行器名称                                         |
| priceExec         | string |                                                              |
| priceSymbol       | string | -                                                            |

## 2 分状态查询地址的买单 GetOnesBuyOrderWithStatus

**调用接口**

```
rpc QueryChain(ChainExecutor) returns (Reply) {}
```

**参数：**

```
message ChainExecutor {
    string driver    = 1;
    string funcName  = 2;
    bytes  stateHash = 3;
    bytes  param     = 4;
    bytes  extra     = 5;
}
message ReqAddrAssets {
    string addr   = 1;
    int32  status = 2;
    repeated string token     = 3;
    int32           direction = 4;
    int32           count     = 5;
    string          fromKey   = 6;
}
```

**参数说明：**

| 参数      | 类型     | 是否必须 | 说明                                                         |
| :-------- | :------- | :------- | :----------------------------------------------------------- |
| driver    | bytes    | 是       | 执行器名称, 这里固定为 trade                                 |
| funcName  | string   | 是       | 操作名称, 这里固定为 GetOnesBuyOrderWithStatus               |
| stateHash | bytes    | 否       | 所有交易在对应的执行器执行后写入KVDB中重新计算得到的新state的哈希值 |
| param     | bytes    | 是       | types.Encode(&ReqAddrAssets)                                 |
| extra     | bytes    | 否       | 扩展字段，用于额外的用途                                     |
| addr      | string   | 是       | 买单持有人                                                   |
| token     | []string | 否       | 具体的token的标识符，可以是多个                              |
| status    | int32    | 是       | 买单状态                                                     |
| direction | int32    | 否       | 查询的方向                                                   |
| count     | int32    | 否       | 最多取的数量                                                 |
| fromKey   | string   | 否       | 开始查询的主键                                               |

**返回数据：**

```
message ReplyTradeOrders {
    repeated ReplyTradeOrder orders = 1;
}
message ReplyTradeOrder {
    string tokenSymbol       = 1;
    string owner             = 2;
    int64  amountPerBoardlot = 3;
    int64  minBoardlot       = 4;
    int64  pricePerBoardlot  = 5;
    int64  totalBoardlot     = 6;
    int64  tradedBoardlot    = 7;
    string buyID             = 8;
    int32  status            = 9;
    string sellID            = 10;
    string txHash            = 11;
    int64  height            = 12;
    string key               = 13;
    int64  blockTime         = 14;
    bool   isSellOrder       = 15;
    string assetExec         = 16;
    string priceExec         = 17;
    string priceSymbol       = 18;
}
```

result: 对应买单的列表，各项同1.1。

## 3 显示一个token 指定数量的买单 GetTokenBuyOrderByStatus

**调用接口**

```
rpc QueryChain(ChainExecutor) returns (Reply) {}
```

**参数：**

```
message ChainExecutor {
    string driver    = 1;
    string funcName  = 2;
    bytes  stateHash = 3;
    bytes  param     = 4;
    bytes  extra     = 5;
}
message ReqTokenBuyOrder {
    string tokenSymbol = 1;
    string fromKey     = 2;
    int32  count       = 3;
    int32  direction   = 4;
    int32  status      = 5;
}
```

**参数说明：**

| 参数        | 类型   | 是否必须                                                     | 说明                                                         |
| :---------- | :----- | :----------------------------------------------------------- | :----------------------------------------------------------- |
| driver      | bytes  | 是                                                           | 执行器名称, 这里固定为 trade                                 |
| funcName    | string | 是                                                           | 操作名称, 这里固定为 GetTokenBuyOrderByStatus                |
| stateHash   | bytes  | 否                                                           | 所有交易在对应的执行器执行后写入KVDB中重新计算得到的新state的哈希值 |
| param       | bytes  | 是                                                           | types.Encode(&ReqTokenBuyOrder)                              |
| extra       | bytes  | 否                                                           | 扩展字段，用于额外的用途                                     |
| status      | int32  | 订单状态 （默认是4, 求购状态）                               |                                                              |
| count       | int32  | 卖单数量                                                     |                                                              |
| direction   | int32  | 0 上一页; 1下一页                                            |                                                              |
| tokenSymbol | string | 填写token标识符                                              |                                                              |
| fromKey     | string | 买单的key，不填第一页；如果要获取下一页， 填写这一页的最后一个买单的key；如果要获取上一页， 填写这一页的第一个买单的key。 |                                                              |

**返回数据：**

```
message ReplyTradeOrders {    repeated ReplyTradeOrder orders = 1;}
```

result: 对应买单的列表，各项同1.1。

## 4 显示指定token出售者的一个或多个token 或 不指定token 的卖单 GetOnesSellOrder

**调用接口**

```
rpc QueryChain(ChainExecutor) returns (Reply) {}
```

**参数：**

```
message ChainExecutor {
    string driver    = 1;
    string funcName  = 2;
    bytes  stateHash = 3;
    bytes  param     = 4;
    bytes  extra     = 5;
}
message ReqAddrAssets {
    string addr   = 1;
    int32  status = 2;
    repeated string token     = 3;
    int32           direction = 4;
    int32           count     = 5;
    string          fromKey   = 6;
}
```

**参数说明：**

| 参数      | 类型     | 是否必须 | 说明                                                         |
| :-------- | :------- | :------- | :----------------------------------------------------------- |
| driver    | bytes    | 是       | 执行器名称, 这里固定为 trade                                 |
| funcName  | string   | 是       | 操作名称, 这里固定为 GetOnesSellOrder                        |
| stateHash | bytes    | 否       | 所有交易在对应的执行器执行后写入KVDB中重新计算得到的新state的哈希值 |
| param     | bytes    | 是       | types.Encode(&ReqAddrAssets)                                 |
| extra     | bytes    | 否       | 扩展字段，用于额外的用途                                     |
| addr      | string   | 是       | 买单持有人                                                   |
| token     | []string | 是       | 具体的token的标识符，可以是多个， 或不指定                   |
| status    | int32    | 否       | 状态                                                         |
| direction | int32    | 否       | 查询的方向                                                   |
| count     | int32    | 否       | 最多取的数量                                                 |
| fromKey   | string   | 否       | 开始查询的主键                                               |

**返回数据：**

```
message ReplyTradeOrders {
    repeated ReplyTradeOrder orders = 1;
}
message ReplyTradeOrder {
    string tokenSymbol       = 1;
    string owner             = 2;
    int64  amountPerBoardlot = 3;
    int64  minBoardlot       = 4;
    int64  pricePerBoardlot  = 5;
    int64  totalBoardlot     = 6;
    int64  tradedBoardlot    = 7;
    string buyID             = 8;
    int32  status            = 9;
    string sellID            = 10;
    string txHash            = 11;
    int64  height            = 12;
    string key               = 13;
    int64  blockTime         = 14;
    bool   isSellOrder       = 15;
    string assetExec         = 16;
    string priceExec         = 17;
    string priceSymbol       = 18;
}
```

**参数说明：**

| 参数              | 类型   | 说明                                                         |
| :---------------- | :----- | :----------------------------------------------------------- |
| result            | -      | 对应买单的列表                                               |
| key               | string | 可能是 sellID 或 txHash。 在现价卖单中是txHash， 在限价卖单中是 sellID |
| txHash            | string | 对应交易的hash                                               |
| sellID            | string | 卖单id                                                       |
| buyID             | string | 买单id                                                       |
| tokenSymbol       | string | 在售token的标识符                                            |
| owner             | string | token卖单的地址                                              |
| blockTime         | int64  | 出块的 UTC 时间                                              |
| isSellOrder       | string | 是否是买单                                                   |
| status            | bool   | 卖单状态                                                     |
| height            | int64  | 卖单所在区块的高度                                           |
| amountPerBoardlot | int64  | 每一手成交的数量                                             |
| minBoardlot       | int64  | 一次购买最少成交的数量                                       |
| pricePerBoardlot  | int64  | 一手成交的价格                                               |
| totalBoardlot     | int64  | 总共购买的手数                                               |
| tradedBoardlot    | int64  | 已经成交手数                                                 |
| assetExec         | string | 资产来源的执行器名称                                         |
| priceExec         | string |                                                              |
| priceSymbol       | string | -                                                            |

## 5 显示指定状态下的某地址卖单 GetOnesSellOrderWithStatus

**调用接口**

```
rpc QueryChain(ChainExecutor) returns (Reply) {}
```

**参数：**

```
message ChainExecutor {
    string driver    = 1;
    string funcName  = 2;
    bytes  stateHash = 3;
    bytes  param     = 4;
    bytes  extra     = 5;
}
message ReqAddrAssets {
    string addr   = 1;
    int32  status = 2;
    repeated string token     = 3;
    int32           direction = 4;
    int32           count     = 5;
    string          fromKey   = 6;
}
```

**参数说明：**

| 参数      | 类型     | 是否必须 | 说明                                                         |
| :-------- | :------- | :------- | :----------------------------------------------------------- |
| driver    | bytes    | 是       | 执行器名称, 这里固定为 trade                                 |
| funcName  | string   | 是       | 操作名称, 这里固定为 GetOnesSellOrderWithStatus              |
| stateHash | bytes    | 否       | 所有交易在对应的执行器执行后写入KVDB中重新计算得到的新state的哈希值 |
| param     | bytes    | 是       | types.Encode(&ReqAddrAssets)                                 |
| extra     | bytes    | 否       | 扩展字段，用于额外的用途                                     |
| addr      | string   | 是       | 卖单地址                                                     |
| token     | []string | 否       | 具体的token的标识符，可以是多个                              |
| status    | int32    | 是       | 1表示在售状态; 2，表示售罄状态；3，表示卖单被撤销状态        |
| direction | int32    | 否       | 查询的方向                                                   |
| count     | int32    | 否       | 最多取的数量                                                 |
| fromKey   | string   | 否       | 开始查询的主键                                               |

**返回数据：**

```
message ReplyTradeOrders {
    repeated ReplyTradeOrder orders = 1;
}
```

result: 对应卖单的列表，各项同1.4。

## 6 显示一个用户成交的所有买单

见 1.1

## 7 显示一个用户成交的指定一个或者多个token所有买单

见 1.1

## 8 显示一个token 指定数量的卖单 GetTokenSellOrderByStatus

**调用接口**

```
rpc QueryChain(ChainExecutor) returns (Reply) {}
```

**参数：**

```
message ChainExecutor {
    string driver    = 1;
    string funcName  = 2;
    bytes  stateHash = 3;
    bytes  param     = 4;
    bytes  extra     = 5;
}
message ReqTokenSellOrder {
    string tokenSymbol = 1;
    string fromKey     = 2;
    int32  count       = 3;
    int32  direction   = 4;
    int32  status      = 5;
}
```

**参数说明：**

| 参数        | 类型   | 是否必须                                                     | 说明                                                         |
| :---------- | :----- | :----------------------------------------------------------- | :----------------------------------------------------------- |
| driver      | bytes  | 是                                                           | 执行器名称, 这里固定为 trade                                 |
| funcName    | string | 是                                                           | 操作名称, 这里固定为 GetTokenSellOrderByStatus               |
| stateHash   | bytes  | 否                                                           | 所有交易在对应的执行器执行后写入KVDB中重新计算得到的新state的哈希值 |
| param       | bytes  | 是                                                           | types.Encode(&ReqTokenSellOrder)                             |
| extra       | bytes  | 否                                                           | 扩展字段，用于额外的用途                                     |
| status      | int32  | 查询状态 （默认 1, 在售状态）                                |                                                              |
| count       | int32  | 卖单数量                                                     |                                                              |
| direction   | int32  | 0 上一页; 1下一页                                            |                                                              |
| tokenSymbol | string | 填写token标识符                                              |                                                              |
| fromKey     | string | 卖单的key，不填第一页；如果要获取下一页， 填写这一页的最后一个卖单的key；如果要获取上一页， 填写这一页的第一个卖单的key。 |                                                              |

**返回数据：**

```
message ReplyTradeOrders {
    repeated ReplyTradeOrder orders = 1;
}
```

result: 对应卖单的列表，各项同1.4。

## 9 生成 卖出资产的交易（未签名） CreateRawTradeSellTx

**调用接口**

```
rpc CreateRawTradeSellTx(TradeForSell) returns (UnsignTx) {}
```

**参数：**

```
// 创建众筹交易,确定一手交易的token的数量，单价以及总共有多少手token可以进行众筹
message TradeForSell {
    string tokenSymbol = 1;
    // 每一手出售的token的数量
    int64 amountPerBoardlot = 2;
    // 起卖手数,必须达到这个门槛才允许进行交易
    int64 minBoardlot = 3;
    // 每一手token的价格
    int64 pricePerBoardlot = 4;
    int64 totalBoardlot    = 5;
    // 此次出售的起始时间，如果非众筹则可以忽略此时间
    int64 starttime = 6;
    int64 stoptime  = 7;
    bool  crowdfund = 8;
    // 资产来源
    string assetExec = 9;
    // 定价资产
    string priceExec   = 10;
    string priceSymbol = 11;
}
```

**参数说明：**

| 参数              | 类型   | 说明                   |
| :---------------- | :----- | :--------------------- |
| tokenSymbol       | string | 资产标识符             |
| assetExec         | string | 资产来源的执行器名称   |
| amountPerBoardlot | int64  | 每一手成交的数量       |
| minBoardlot       | int64  | 一次购买最少成交的数量 |
| pricePerBoardlot  | int64  | 一手成交的价格         |
| totalBoardlot     | int64  | 总共的出售的手数       |
| priceExec         | string | 标价资产的合约         |
| priceSymbol       | string | 标价资产的名字         |
| fee               | int64  | 交易的手续费           |

**返回数据：**

```
message UnsignTx {
    bytes data = 1;
}
```

**参数说明：**

| 参数 | 类型  | 说明                     |
| :--- | :---- | :----------------------- |
| data | bytes | 交易十六进制编码后的数据 |

## 10 生成买入指定卖单卖出的token的交易（未签名）CreateRawTradeBuyTx

**调用接口**

```
rpc CreateRawTradeBuyTx(TradeForBuy) returns (UnsignTx) {}
```

**参数：**

```
// 购买者发起交易用来购买token持有者之前挂单出售的token
// 其中的hash为token出售者发起出售交易的hash
message TradeForBuy {
    string sellID      = 1;
    int64  boardlotCnt = 2;
}
```

**参数说明：**

| 参数        | 类型   | 说明             |
| :---------- | :----- | :--------------- |
| sellID      | string | 卖单id           |
| boardlotCnt | int64  | 购买数量，单位手 |

**返回数据：**

```
message UnsignTx {
    bytes data = 1;
}
```

**参数说明：**

| 参数 | 类型  | 说明                     |
| :--- | :---- | :----------------------- |
| data | bytes | 交易十六进制编码后的数据 |

## 11 生成撤销卖出token(卖单)的交易（未签名） CreateRawTradeRevokeTx

**调用接口**

```
rpc CreateRawTradeRevokeTx(TradeForRevokeSell) returns (UnsignTx) {}
```

**参数：**

```
message TradeForRevokeSell {
    string sellID = 1;
}
```

**参数说明：**

| 参数   | 类型   | 说明         |
| :----- | :----- | :----------- |
| sellID | string | 卖单id       |
| fee    | int64  | 交易的手续费 |

**返回数据：**

```
message UnsignTx {
    bytes data = 1;
}
```

**参数说明：**

| 参数 | 类型  | 说明                     |
| :--- | :---- | :----------------------- |
| data | bytes | 交易十六进制编码后的数据 |

## 12 生成 买入token的交易（未签名） CreateRawTradeBuyLimitTx

**调用接口**

```
rpc CreateRawTradeBuyLimitTx(TradeForBuyLimit) returns (UnsignTx) {}
```

**参数：**

```
message TradeForBuyLimit {
    string tokenSymbol       = 1;
    int64  amountPerBoardlot = 2;
    int64  minBoardlot       = 3;
    int64  pricePerBoardlot  = 4;
    int64  totalBoardlot     = 5;
    string assetExec         = 6;
    string priceExec         = 7;
    string priceSymbol       = 8;
}
```

**参数说明：**

| 参数              | 类型   | 说明                   |
| :---------------- | :----- | :--------------------- |
| tokenSymbol       | string | token标识符            |
| assetExec         | string | 资产来源的执行器名称   |
| amountPerBoardlot | int64  | 每一手成交的数量       |
| minBoardlot       | int64  | 一次购买最少成交的数量 |
| pricePerBoardlot  | int64  | 一手成交的价格         |
| totalBoardlot     | int64  | 总共的出售的手数       |
| priceExec         | string | 标价资产的合约         |
| priceSymbol       | string | 标价资产的名字         |

**返回数据：**

```
message UnsignTx {
    bytes data = 1;
}
```

**参数说明：**

| 参数 | 类型  | 说明                     |
| :--- | :---- | :----------------------- |
| data | bytes | 交易十六进制编码后的数据 |

## 13 生成卖出指定买单的token的交易（未签名） CreateRawTradeSellMarketTx

**调用接口**

```
rpc CreateRawTradeSellMarketTx(TradeForSellMarket) returns (UnsignTx) {}
```

**参数：**

```
message UnsignTx {
    bytes data = 1;
}
```

**参数说明：**

| 参数        | 类型   | 说明             |
| :---------- | :----- | :--------------- |
| buyID       | string | 买单id           |
| boardlotCnt | int64  | 购买数量，单位手 |

**返回数据：**

```
message UnsignTx {
    bytes data = 1;
}
```

**参数说明：**

| 参数 | 类型  | 说明                     |
| :--- | :---- | :----------------------- |
| data | bytes | 交易十六进制编码后的数据 |

## 14 生成撤销买入token(买单)的交易（未签名） CreateRawTradeRevokeBuyTx

**调用接口**

```
rpc CreateRawTradeRevokeBuyTx(TradeForRevokeBuy) returns (UnsignTx) {}
```

**参数：**

```
message TradeForRevokeBuy {
    string buyID = 1;
}
```

**参数说明：**

| 参数  | 类型   | 说明   |
| :---- | :----- | :----- |
| buyID | string | 买单id |

**返回数据：**

```
message UnsignTx {
    bytes data = 1;
}
```

**参数说明：**

| 参数 | 类型  | 说明                     |
| :--- | :---- | :----------------------- |
| data | bytes | 交易十六进制编码后的数据 |

## 15 根据状态分页列出某地址的订单（包括买单卖单） GetOnesOrderWithStatus

**调用接口**

```
rpc QueryChain(ChainExecutor) returns (Reply) {}
```

**参数：**

```
message ChainExecutor {
    string driver    = 1;
    string funcName  = 2;
    bytes  stateHash = 3;
    bytes  param     = 4;
    bytes  extra     = 5;
}
message ReqAddrAssets {
    string addr   = 1;
    int32  status = 2;
    repeated string token     = 3;
    int32           direction = 4;
    int32           count     = 5;
    string          fromKey   = 6;
}
```

**参数说明：**

| 参数      | 类型     | 是否必须 | 说明                                                         |
| :-------- | :------- | :------- | :----------------------------------------------------------- |
| driver    | bytes    | 是       | 执行器名称, 这里固定为 trade                                 |
| funcName  | string   | 是       | 操作名称, 这里固定为 GetOnesOrderWithStatus                  |
| stateHash | bytes    | 否       | 所有交易在对应的执行器执行后写入KVDB中重新计算得到的新state的哈希值 |
| param     | bytes    | 是       | types.Encode(&ReqAddrAssets)                                 |
| extra     | bytes    | 否       | 扩展字段，用于额外的用途                                     |
| addr      | string   | 是       | 指定地址                                                     |
| token     | []string | 否       | 具体的token的标识符，可以是多个                              |
| status    | int32    | 是       | 1: 未完成交易， 2： 完成的交易， 3： 撤销的交易              |
| direction | int32    | 否       | 查询的方向,0 按高度降序， 1 按高度升序                       |
| count     | int32    | 否       | 最多取的数量                                                 |
| fromKey   | string   | 否       | 开始查询的主键,第一页时不指定。 其他页时，指定上一页的最后一个key |

**返回数据：**

```
message ReplyTradeOrders {
    repeated ReplyTradeOrder orders = 1;
}
```

result: 对应列表，各项同1.1。