# Token 接口

## 1 发行token

### 1.1 生成预创建token 的交易（未签名） CreateRawTokenPreCreateTx

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"token.CreateRawTokenPreCreateTx",
    "params":[
        {
            "name":"string",
            "symbol":"string",
            "introduction":"string",
            "total":int64,
            "price":int64,
            "category":int64,
            "owner":"string"
        }
    ]
}
```

**参数说明：**

| 参数         | 类型   | 说明                                                       |
| :----------- | :----- | :--------------------------------------------------------- |
| name         | string | token的全名，最大长度是128个字符                           |
| symbol       | string | token标记符，最大长度是16个字符，且必须为大写字符和数字    |
| introduction | string | token介绍，最大长度为1024个字节                            |
| total        | int64  | 发行总量,需要乘以10的8次方，比如要发行100个币，需要100*1e8 |
| price        | int64  | 发行该token愿意承担的费用                                  |
| owner        | string | token拥有者地址                                            |
| category     | int32  | token属性类别， 0 为普通token， 1 可增发和燃烧             |

**响应报文：**

```
{
    "id":int32,
    "error":null,
    "result":"string"
}
```

**参数说明：**

| 参数   | 类型   | 说明                       |
| :----- | :----- | :------------------------- |
| result | string | 交易十六进制编码后的字符串 |

**示例：**
Request:

```
{
    "id":1,
    "method":"token.CreateRawTokenPreCreateTx",
    "params":[
        {
            "name":"Develop Coins",
            "symbol":"DEVCOIND",
            "introduction":"Develop Coins",
            "total":19900000000000000,
            "price": 0,
            "owner":"14Gkp5kUEMo7fXhHuDRnRN6vJxNpSdDw1T"
        }
    ]
}
```

Response:

```
{
    "id":1,
    "result":"0a14757365722e702e646576746573742e746f6b656e123538070a310a0d446576656c6f7020436f6",
    "error":null
}
```

### 1.2 生成完成创建token 的交易（未签名） CreateRawTokenFinishTx

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"token.CreateRawTokenFinishTx",
    "params":[{"symbol":"string","owner":"string"}]
}
```

**参数说明：**

| 参数   | 类型   | 说明                                              |
| :----- | :----- | :------------------------------------------------ |
| symbol | string | token标记符，最大长度是16个字符，且必须为大写字符 |
| owner  | string | token拥有者地址                                   |

**响应报文：**

```
{
    "id":int32,
    "error":null,
    "result":"string"
}
```

**参数说明：**

| 参数   | 类型   | 说明                         |
| :----- | :----- | :--------------------------- |
| result | string | 交易对象的十六进制字符串编码 |

**示例：**
Request:

```
{
    "id":1,
    "method":"token.CreateRawTokenFinishTx",
    "params":[{"symbol":"DEVCOINZ","owner":"14Gkp5kUEMo7fXhHuDRnRN6vJxNpSdDw1T"}]
}
```

Response:

```
{
    "id":1,
    "result":"0a14757365722e702e646576746573742e746f6b656e12323808122e0a08444556434f494e4412223134476b70",
    "error":null
}
```

### 1.3 生成撤销创建token 的交易（未签名） CreateRawTokenRevokeTx

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"token.CreateRawTokenRevokeTx",
    "params":[{"symbol":"string","owner":"string"}]
}
```

**参数说明：**

| 参数   | 类型   | 是否必填 | 说明                                              |
| :----- | :----- | :------- | :------------------------------------------------ |
| symbol | string | 是       | token标记符，最大长度是16个字符，且必须为大写字符 |
| owner  | string | 是       | token拥有者地址                                   |

**响应报文：**

```
{
    "id":int32,
    "error":null,
    "result":"string"
}
```

**参数说明：**

| 参数   | 类型   | 说明                         |
| :----- | :----- | :--------------------------- |
| result | string | 交易对象的十六进制字符串编码 |

**示例：**
Request:

```
{
    "id":1,
    "method":"token.CreateRawTokenRevokeTx",
    "params":[{"symbol":"DEVECOIN","owner":"14Gkp5kUEMo7fXhHuDRnRN6vJxNpSdDw1T"}]
}
```

Response:

```
{
    "id":1,
    "result":"0a14757365722e702e646576746573742e746f6b656e12323",
    "error":null
}
```

### 1.4 查询所有预创建的token GetTokens

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.Query",
    "params":[
        {
            "execer":"token",
            "funcName":"GetTokens",
            "payload":{"status": 0,"queryAll":true,"symbolOnly":true}
        }
    ]
}
```

**参数说明：**

| 参数     | 类型   | 说明                                                         |
| :------- | :----- | :----------------------------------------------------------- |
| execer   | []byte | 主链上查询：token 平行链上查询:user.p.xxxx.token             |
| funcName | string | GetTokens                                                    |
| payload  | []byte | status: 0, queryAll: true/false, symbolOnly:选填（true/false） |

**响应报文：**

```
{
    "id":int32,
    "result":{
        "tokens":[
            {
                "name":"string",
                "symbol":"string",
                "introduction":"string",
                "total":int64,
                "price":int64,
                "owner":"string",
                "creator":"string",
                "status":int32,
                "createdHeight":int64,
                "createdTime":int64,
                "prepareCreateHeight":int64,
                "prepareCreateTime":int64,
                "precision":int32,
                "totalTransferTimes":int64,
                "revokedHeight":int64,
                "revokedTime":int64,
                "category":int32
            }
        ]
    },
    "error":null
}
```

**参数说明：**

| 参数                | 类型   | 说明                                              |
| :------------------ | :----- | :------------------------------------------------ |
| name                | string | token的全名，最大长度是128个字符                  |
| symbol              | string | token标记符，最大长度是16个字符，且必须为大写字符 |
| introduction        | string | token介绍，最大长度为1024个字节                   |
| total               | int64  | 发行总量                                          |
| price               | int64  | 发行该token愿意承担的费用                         |
| ownerAddr           | string | token拥有者地址                                   |
| creator             | string | 预创建人地址                                      |
| status              | int32  | 0表示 TokenStatusPreCreated 状态                  |
| createdHeight       | int64  |                                                   |
| createdTime         | int64  |                                                   |
| prepareCreateHeight | int64  |                                                   |
| prepareCreateTime   | int64  |                                                   |
| precision           | int32  |                                                   |
| totalTransferTimes  | int64  |                                                   |
| revokedHeight       | int64  |                                                   |
| revokedTime         | int64  |                                                   |
| category            | int32  | -                                                 |

### 1.5 查询所有创建成功的token GetTokens

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.Query",
    "params":[
        {
            "execer":"token",
            "funcName":"GetTokens",
            "payload":{"status": 1,"queryAll":true,"symbolOnly":true}
        }
    ]
}
```

**参数说明：**

| 参数     | 类型   | 说明                                                         |
| :------- | :----- | :----------------------------------------------------------- |
| execer   | []byte | 主链上查询：token 平行链上查询:user.p.xxxx.token             |
| funcName | string | GetTokens                                                    |
| payload  | []byte | status: 1, queryAll 是否查询所有: true/false, symbolOnly:是否只返回symbol值 选填（true/false） |

**响应报文：**

```
{
    "id":int32,
    "result":{
        "tokens":[
            {
                "name":"string",
                "symbol":"string",
                "introduction":"string",
                "total":int64,
                "price":int64,
                "owner":"string",
                "creator":"string",
                "status":int32,
                "createdHeight":int64,
                "createdTime":int64,
                "prepareCreateHeight":int64,
                "prepareCreateTime":int64,
                "precision":int32,
                "totalTransferTimes":int64,
                "revokedHeight":int64,
                "revokedTime":int64,
                "category":int32
            }
        ]
    },
    "error":null
}
```

**参数说明：**

| 参数                | 类型   | 说明                                              |
| :------------------ | :----- | :------------------------------------------------ |
| name                | string | token的全名，最大长度是128个字符                  |
| symbol              | string | token标记符，最大长度是16个字符，且必须为大写字符 |
| introduction        | string | token介绍，最大长度为1024个字节                   |
| total               | int    | 发行总量                                          |
| price               | int    | 发行该token愿意承担的费用                         |
| ownerAddr           | string | token拥有者地址                                   |
| creator             | string | 预创建人地址                                      |
| status              | int    | 1表示 Token已经完成创建状态                       |
| createdHeight       | int64  |                                                   |
| createdTime         | int64  |                                                   |
| prepareCreateHeight | int64  |                                                   |
| prepareCreateTime   | int64  |                                                   |
| precision           | int32  |                                                   |
| totalTransferTimes  | int64  |                                                   |
| revokedHeight       | int64  |                                                   |
| revokedTime         | int64  |                                                   |
| category            | int32  | -                                                 |

### 1.6 查询指定创建成功的token GetTokenInfo

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.Query",
    "params":[
        {
            "execer":"token",
            "funcName":"GetTokenInfo",
            "payload":{"data":"ADDRE"}
        }
    ]
}
```

**参数说明：**

| 参数     | 类型   | 说明                                              |
| :------- | :----- | :------------------------------------------------ |
| execer   | []byte | 执行器名，主链上:token, 平行链上:user.p.xxx.token |
| funcName | string | GetTokenInfo                                      |
| payload  | []byte | token的Symbol                                     |

**响应报文：**

```
{
    "id":int32,
    "result":{
        "name":"string",
        "symbol":"string",
        "introduction":"string",
        "total":int64,
        "price":int64,
        "owner":"string",
        "creator":"string",
        "status":int32,
        "createdHeight":int64,
        "createdTime":int64,
        "prepareCreateHeight":int64,
        "prepareCreateTime":int64,
        "precision":int32,
        "totalTransferTimes":int64,
        "revokedHeight":int64,
        "revokedTime":int64,
        "category":int32
    },
    "error":null
}
```

**参数说明：**

| 参数                | 类型   | 说明                                              |
| :------------------ | :----- | :------------------------------------------------ |
| name                | string | token的全名，最大长度是128个字符                  |
| symbol              | string | token标记符，最大长度是16个字符，且必须为大写字符 |
| introduction        | string | token介绍，最大长度为1024个字节                   |
| total               | int    | 发行总量                                          |
| price               | string | 发行该token愿意承担的费用                         |
| ownerAddr           | string | token拥有者地址                                   |
| creator             | string | 预创建人地址                                      |
| status              | string | 1. 0表示 TokenStatusCreated 状态                  |
| createdHeight       | int64  |                                                   |
| createdTime         | int64  |                                                   |
| prepareCreateHeight | int64  |                                                   |
| prepareCreateTime   | int64  |                                                   |
| precision           | int32  |                                                   |
| totalTransferTimes  | int64  |                                                   |
| revokedHeight       | int64  |                                                   |
| revokedTime         | int64  |                                                   |
| category            | int32  | -                                                 |

**示例：**
Request:

```
{
    "jsonrpc":"2.0",
    "id":2,
    "method":"Chain33.Query",
    "params":[{"execer":"user.p.ganme.token","funcName":"GetTokenInfo","payload": {"data":"GANMEB"}}]
}
```

Response:

```
{
    "id":2,
    "result":{
        "name":"ganme",
        "symbol":"GANMEB",
        "introduction":"ganme_token",
        "total":1990000000000000000,
        "price":0,
        "owner":"14S4UKuggZW17YfJ8cnrK5ACkPwW3kUJUc",
        "creator":"1N84sP4Nep9k72kE69AoKjEi4uKZ5h7ZVz",
        "status":1,
        "createdHeight":196,
        "createdTime":1544776259,
        "prepareCreateHeight":195,
        "prepareCreateTime":1544776220,
        "precision":8,
        "totalTransferTimes":0,
        "revokedHeight":0,
        "revokedTime":0,
        "category":0
    },
    "error":null
}
```

## 2 token操作

### 2.1 token转账 SendToAddress

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.SendToAddress",
    "params":[{"from":"string","to":"string","amount":int64,"note":"string","isToken":true,"tokenSymbol":"string"}]
}
```

**参数说明：**

| 参数        | 类型   | 说明                                              |
| :---------- | :----- | :------------------------------------------------ |
| from        | string | 来源地址                                          |
| to          | string | 发送到地址                                        |
| amount      | int64  | 发送金额                                          |
| note        | string | 备注                                              |
| isToken     | bool   | 发送的是否是token，false 的情况下发送的bty        |
| tokenSymbol | string | token标记符，最大长度是16个字符，且必须为大写字符 |

**响应报文：**

```
{
    "id":int32,
    "error":null,
    "result":{"hash":"string"}
}
```

**参数说明：**

| 参数 | 类型   | 说明         |
| :--- | :----- | :----------- |
| hash | string | 返回结果哈希 |

### 2.2 token提币 SendToAddress

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.SendToAddress",
    "params":[{"from":"string","to":"string","amount":int64,"note":"string","isToken":true, "tokenSymbol":"string"}]
}
```

**参数说明：**

| 参数        | 类型   | 说明                                              |
| :---------- | :----- | :------------------------------------------------ |
| from        | string | token提币地址                                     |
| to          | string | token保存的合约地址                               |
| amount      | int64  | 发送金额，填写负数                                |
| note        | string | 备注                                              |
| isToken     | bool   | 发送的是否是token，false 的情况下发送的bty        |
| tokenSymbol | string | token标记符，最大长度是16个字符，且必须为大写字符 |

**响应报文：**

```
{
    "id":int32,
    "error":null,
    "result":{"hash":"string"}
}
```

**参数说明：**

| 参数 | 类型   | 说明         |
| :--- | :----- | :----------- |
| hash | string | 返回结果哈希 |

## 3 token查询

### 3.3 查询地址下的token合约下的token资产 GetAccountTokenAssets

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.Query",
    "params":[
        {
            "execer":"token",
            "funcName":"GetAccountTokenAssets",
            "payload":{"address":"string","execer":"string"}
        }
    ]
}
```

**参数说明：**

| 参数     | 类型   | 说明                                              |
| :------- | :----- | :------------------------------------------------ |
| execer   | []byte | 执行器名，主链上:token, 平行链上:user.p.xxx.token |
| funcName | string | GetAccountTokenAssets                             |
| payload  | []byte | address:查询的地址, execer: token                 |

**响应报文：**

```
{
    "id":int32,
    "error":null,
    "result":[
        {
            "symbol": "string",
            "account" :{
                "currency":int32
                "balance":int64
                "frozen":int64
                "addr":"stirng"
            },
        },
    ]
}
```

**参数说明：**

| 参数    | 类型   | 说明                                              |
| :------ | :----- | :------------------------------------------------ |
| symbol  | string | token标记符，最大长度是16个字符，且必须为大写字符 |
| account | string | token 对应地址的帐号信息                          |
| balance | int    | 帐号的可用余额                                    |
| frozen  | int    | 帐号中冻结余额                                    |
| addr    | string | 帐号的地址                                        |

**示例：**
Request:

```
{
    "jsonrpc":"2.0",
    "id":2,
    "method":"Chain33.Query",
    "params":[
        {
            "execer":"user.p.ganme.token",
            "funcName":"GetAccountTokenAssets",
            "payload": {"address":"14S4UKuggZW17YfJ8cnrK5ACkPwW3kUJUc","execer":"token"}
        }
    ]
}
```

Response:

```
{
    "id":2,
    "result":{
        "tokenAssets":[
            {
                "symbol":"GANMEB",
                "account":{
                    "currency":0,
                    "balance":"1989999900000000000",
                    "frozen":"0",
                    "addr":"14S4UKuggZW17YfJ8cnrK5ACkPwW3kUJUc"
                }
            }
        ]
    },
    "error":null
}
```

### 3.4 查询token相关的交易 GetTxByToken

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.Query",
    "params":[
        {
            "execer":"token",
            "funcName":"GetTxByToken",
            "payload":{
                "symbol":"string",
                "count":int32,
                "flag":int32,
                "height":int64,
                "index":int64,
                "direction":int32,
                "addr":"string"
            }
        }
    ]
}
```

**参数说明：**

| 参数     | 类型   | 说明                                                         |
| :------- | :----- | :----------------------------------------------------------- |
| execer   | []byte | 执行器名，主链上:token, 平行链上:user.p.xxx.token            |
| funcName | string | GetTxByToken                                                 |
| payload  | []byte | symbol: token标记符，count: 交易的数量，flag /height / index / direction : 分页相关参数，addr: 地址 |

**响应报文：**

```
{
    "id":int32,
    "result" : {
        "txInfos" : [
            {
                "index" : int64,
                "height" : int64,
                "hash" : "string"
                "assets": [{"exec": "string","symbol": "string","amount":int64}]
            }
        ]
    },
    "error":null
}
```

**参数说明：**

| 参数    | 类型 | 说明                               |
| :------ | :--- | :--------------------------------- |
| txInfos | List | 交易列表，包括交易hash，资产信息等 |

**示例：**
Request:

```
{
    "jsonrpc":"2.0",
    "id":2,
    "method":"Chain33.Query",
    "params":[
        {
            "execer":"user.p.ganme.token",
            "funcName":"GetTxByToken",
            "payload": {"symbol":"GANMEB","direction": 0,"height": -1,"flag": 0,"index": 0,"count": 8}
        }
    ]
}
```

Response:

```
{
    "id":2,
    "result":{
        "txInfos":[
            {
                "hash":"0x3a9bce21222aa9c71aea71fad33a1ec57ce6174dcbc580f3de31e3d324e875a7",
                "height":"208",
                "index":"2",
                "assets":[{"exec":"token","symbol":"GANMEB","amount":"0"}]
            }
        ]
    },
    "error":null
}
```

## 4 token的增发和燃烧

### 4.1 token的增发 CreateRawTokenMintTx

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"token.CreateRawTokenMintTx",
    "params":[{"symbol": string,"amount":int64}]
}
```

**参数说明：**

| 参数   | 类型   | 说明                                 |
| :----- | :----- | :----------------------------------- |
| amount | int64  | 增发token的数量, 需要 填写 数目* 1e8 |
| symbol | string | token的标记符                        |

**响应报文：**

```
{    "id":int32,    "result": "string",    "error":null}
```

**参数说明：**

| 参数   | 类型   | 说明                       |
| :----- | :----- | :------------------------- |
| result | string | 交易十六进制编码后的字符串 |

**示例：**
Request:

```
{
    "jsonrpc":"2.0",
    "id":1,
    "method":"token.CreateRawTokenMintTx",
    "params":[{"symbol": "TC","amount":10000000000}]
}
```

Response:

```
{
    "id":1,
    "result":"0a14757365722e702e646576746573742e746f6b656e123538070a310a0d446576656c6f7",
    "error":null
}
4.2 tok
```

### 4.2 token的燃烧 CreateRawTokenBurnTx

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"token.CreateRawTokenBurnTx",
    "params":[{"symbol": string,"amount":int64}]
}
```

**参数说明：**

| 参数   | 类型   | 说明                                 |
| :----- | :----- | :----------------------------------- |
| amount | int64  | 燃烧token的数量, 需要 填写 数目* 1e8 |
| symbol | string | token的标记符                        |

**响应报文：**

```
{
    "id":int32,
    "result":"string",
    "error":null
}
```

**参数说明：**

| 参数   | 类型   | 说明                       |
| :----- | :----- | :------------------------- |
| result | string | 交易十六进制编码后的字符串 |

**示例：**
Request:

```
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"token.CreateRawTokenBurnTx",
    "params":[{"symbol": "TC","amount":1000000000}]
}
```

Response:

```
{
    "id":1,
    "result":"0a14757365722e702e646576746573742e746f6b656e123538070a310a0d446576656",
    "error":null
}
```

### 4.3 查询token 的变化记录 GetTokenHistory

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.Query",
    "params":[
        {
            "execer" : "token",
            "funcName" : "GetTokenHistory",
            "payload" : {"data": "string"}
        }
    ]
}
```

**参数说明：**

| 参数     | 类型   | 说明                                              |
| :------- | :----- | :------------------------------------------------ |
| execer   | []byte | 执行器名，主链上:token, 平行链上:user.p.xxx.token |
| funcName | string | GetTokenHistory                                   |
| payload  | []byte | data : token标记符                                |

**响应报文：**

```
{
    "id":int32,
    "error":null,
    "result" : {
        "logs": [
            {
                "symbol": "string",
                "txIndex": "string",
                "actionType":int32,
                "txHash": "string"
            }
        ]
    }
}
```

**参数说明：**

| 参数 | 类型 | 说明                                                         |
| :--- | :--- | :----------------------------------------------------------- |
| logs | List | txHash 交易hash，symbol token标记符, 具体信息可以通过交易hash查询, actionType: 8 是token创建， 12 是增发， 13 是燃烧 |

**示例：**
Request:

```
{
    "jsonrpc":"2.0",
    "id":2,
    "method":"Chain33.Query",
    "params":[
        {
            "execer":"user.p.ganme.token",
            "funcName":"GetTokenHistory",
            "payload": {"data":"GANMEB"}
        }
    ]
}
```

Response:

```
{
    "id":int32,
    "error":null,
    "result" : {
        "logs": [
            {
                "symbol": "TC",
                "txIndex": "000000000002300000",
                "actionType": 13,
                "txHash": "0xa288cc1c9b265ee3ddaf75630282c14a9461c4e97715014eb32d33e94b4f7636"
            },
            {
                "symbol": "TC",
                "txIndex": "000000000002000000",
                "actionType": 12,
                "txHash": "0x28d2be9acd00f473cb29cc77fb85ca14305d35089a446dcc7dadf4fd8c13757f"
            },
            {
                "symbol": "TC",
                "txIndex": "000000000000800000",
                "actionType": 8,
                "txHash": "0x0f7419ef74cd75715e860d5fe1421b3fda37766d35af87a59882ce0a1ea1cb95"
            }
        ]
    }
}
```

## 5 token 的转币 提币等

1. [参考链接](./transactionAPI.md#111-构造资产交易-createrawtransaction)