# Wallet Interface
## 1 Account Administration

### 1.1 Lock the Wallet

**Request message：**

```
request: http.post
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.Lock",
    "params":[] 
}
```

**Response message:**

```
response:
{
    "id":int32,
    "result"::{"isOK":bool,"msg":"string"},
    "error":null
}
```

**Parameter description：**

| Parameter | Type   | Description                                                  |
| :-------- | :----- | :----------------------------------------------------------- |
| isok      | bool   | returns true on success; return false on failure             |
| msg       | string | when successful, return empty; if fail, return error message |

### 1.2 Unlock the Wallet

**Request message：**

```
request: http.post
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.UnLock",
    "params":[{"passwd":"string","walletorticket":bool,"timeout":int32}]
}
```

**Parameter description：**

| Parameter      | Type   | If Necessary | Description                                                  |
| :------------- | :----- | :----------- | :----------------------------------------------------------- |
| passwd         | string | yes          | unlock password                                              |
| walletorticket | bool   | no           | true:only unlock the ticket buying function, false: unlock the entire wallet |
| timeout        | int32  | no           | timeout                                                      |

**Response message:**

```
response:
{
    "id":int32,
    "result"::{"isOK":bool,"msg":"string"},
    "error":null
}
```

**Parameter description：**

| Parameter | Type   | Description                                                  |
| :-------- | :----- | :----------------------------------------------------------- |
| isok      | bool   | returns true on success; false is returned on failure        |
| msg       | string | when successful, return empty; if fail, return error message |

### 1.3 Set/Change the Wallet Password SetPasswd

**Request message：**

```
request: http.post
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.SetPasswd",
    "params":[{"oldPass":"string","newPass":"string"}]
}
```

**Parameter description：**

| Parameter | Type   | If Necessary | Description                                                  |
| :-------- | :----- | :----------- | :----------------------------------------------------------- |
| oldPass   | string | yes          | in the first time of setting password, oldPass is empty      |
| newPass   | string | yes          | new password to be set, must be a combination of numbers and letters of more than or equal to 8 characters |

**Response message:**

```
response:
{
    "id":int32,
    "result"::{"isOK":bool,"msg":"string"},
    "error":null
}
```

**Parameter description：**

| Parameter | Type   | Description                                                  |
| :-------- | :----- | :----------------------------------------------------------- |
| isok      | bool   | returns true on success; false is returned on failure        |
| msg       | string | when successful, return empty; if fail, return error message |

### 1.4 Set Account Label SetLabl

**Request message：**

```
request: http.post
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.SetLabl",
    "params":[{"addr":"string","label":"string"}]
}
```

**Parameter description：**

| Parameter | Type   | If Necessary | Description              |
| :-------- | :----- | :----------- | :----------------------- |
| addr      | string | yes          | account address          |
| label     | string | yes          | account label, to be set |

**Response message:**

```
response:
{
    "id":int32,
    "result":
    {
        "label":"string",
        "acc":{"currency":int32,"balance":int64,"frozen":int64,"addr":"string"}
    },
    "error":null
}
```

**Parameter description：**

| Parameter | Type  | Description                        |
| :-------- | :---- | :--------------------------------- |
| currency  | int32 | currency type                      |
| balance   | int64 | available balance, 1e8 means 1 BTY |
| frozen    | int64 | freeze amount                      |
| addr      | int64 | account address                    |

**Example:**
Request:

```
request: http.post
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.SetLabl",
    "params":[{"addr":"13TbfAPJRmekQxYVEyyGWgfvLwTa8DJW6U","label":"macAddrlabel"}]
}
```

Response:

```
response:
{
    "id":int32,
    "result":
    {
        "label":"macAddrlabel",
        "acc":{"currency":int32,"balance":18357590000,"frozen":0,"addr":"13TbfAPJRmekQxYVEyyGWgfvLwTa8DJW6U"}
    },
    "error":null
}
```

### 1.5 Create Account NewAccount

**Request message：**

```
request: http.post
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.NewAccount",
    "params":[{"label":"string"}]
}
```

**Parameter description：**

| Parameter | Type   | If Necessary | Description             |
| :-------- | :----- | :----------- | :---------------------- |
| label     | string | yes          | account label to be set |

**Response message:**

```
response:
{
    "id":int32,
    "result":
    {
        "label":"string",
        "acc":{"currency":int32,"balance":int64,"frozen":int64,"addr":"string"}
    },
    "error":null
}
```

**Parameter description：**

| Parameter | Type  | Description                        |
| :-------- | :---- | :--------------------------------- |
| currency  | int32 | currency type                      |
| balance   | int64 | available balance, 1e8 means 1 BTY |
| frozen    | int64 | freeze amount                      |
| addr      | int64 | account address                    |

### 1.6 Get Account List GetAccounts

**Request message：**

```
request: http.post
requst
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.GetAccounts",
    "params":[{"withoutBalance" : bool}]
}
```

**Parameter description：**

| Parameter      | Type | If Necessary | Description                                                  |
| :------------- | :--- | :----------- | :----------------------------------------------------------- |
| withoutBalance | bool | no           | leave it blank or false, the account information is returned, if true then return label and abbr information, otherwise 0 |

**Response message:**

```
response:
{
    "id":int32,
    "result":
    {
        "wallets":
        [
            {
                "acc":{"currency":0,"balance":0,"frozen":0,"addr":"12nr235Q6e61HCR7aTCk3LHL1fUb3FAa3w"},
                "label":"123"
            },
            {
                "acc":{"currency":0,"balance":18357590000,"frozen":0,"addr":"13TbfAPJRmekQxYVEyyGWgfvLwTa8DJW6U"},
                "label":"macAddrtest"
            },
            {
                "acc":{"currency":0,"balance":187455654560000,"frozen":0,"addr":"14KEKbYtKKQm4wMthSK9J4La4nAiidGozt"},
                "label":"mac3310101010"
            }
        ]
    },
    "error":null
}
```

### 1.7 Merge Account Balance MergeBalance

**Request message：**

```
request: http.post
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.MergeBalance",
    "params":[{"to":"string"}] 
}
```

**Parameter description：**

| Parameter | Type | If Necessary | Description                                             |
| :-------- | :--- | :----------- | :------------------------------------------------------ |
| to        | bool | yes          | merge all balances on the wallet to one account address |

**Response message:**

```
response:
{
    "id":int32,
    "result":{"hashes":["string"]}
}
```

**Parameter description：**

| Parameter | Type     | Description           |
| :-------- | :------- | :-------------------- |
| hashes    | [string] | transaction hash list |

### 1.8 Import Private Key ImportPrivkey

**Request message：**

```
http.post
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.ImportPrivkey",
    "params":[{"privkey":"string","label":"string"}]  
}
```

**Parameter description：**

| Parameter | Type   | If Necessary | Description          |
| :-------- | :----- | :----------- | :------------------- |
| privkey   | string | yes          | private key          |
| label     | string | yes          | import account label |

**Response message:**

```
response
{
    "id":int32,
    "result":{"label":"string","acc":{"currency":int32,"balance":int64,"frozen":int64,"addr":"string"}},
    "error":null
}
```

**Parameter description：**

| Parameter | Type    | Description     |
| :-------- | :------ | :-------------- |
| label     | string  | account label   |
| acc       | Account | account details |

### 1.9 Export Private Key dumpprivkey

**Request message：**

```
http.post
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.DumpPrivkey",
    "params":[{"data":"string"}]  
}
```

**Parameter description：**

| Parameter | Type   | If Necessary | Description                                       |
| :-------- | :----- | :----------- | :------------------------------------------------ |
| data      | string | yes          | account address of the private key to be exported |

**Response message:**

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

**Parameter description：**

| Parameter | Type   | Description |
| :-------- | :----- | :---------- |
| data      | string | private key |

## 2 Transaction Related

### 2.1 Set Transaction Fee SetTxFee

**Request message：**

```
request: http.post
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.SetTxFee",
    "params":[{"amount":int64}] 
}
```

**Parameter description：**

| Parameter | Type  | If Necessary | Description       |
| :-------- | :---- | :----------- | :---------------- |
| amount    | int64 | yes          | commission charge |

**Response message:**

```
response:
{
    "id":int32,
    "result"::{"isOK":bool,"msg":"string"},
    "error":null
}
```

**Parameter description：**

| Parameter | Type   | Description                                                  |
| :-------- | :----- | :----------------------------------------------------------- |
| isok      | bool   | returns true on success; return false on failure             |
| msg       | string | when successful, return empty; if fail, return error message |

### 2.2 Send Transaction SendToAddress

**Request message：**

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

**Parameter description：**

| Parameter   | Type   | If Necessary | Description                                                  |
| :---------- | :----- | :----------- | :----------------------------------------------------------- |
| from        | string | yes          | source address                                               |
| to          | string | yes          | send to address                                              |
| amount      | int64  | yes          | send the amount                                              |
| note        | string | yes          | note                                                         |
| isToken     | bool   | yes          | whether it is a token transfer (do not fill in this if not)） |
| tokenSymbol | string | yes          | token symbol（do not fill in this if it is not token transfer） |

**Response message:**

```
response:
{
    "id":int32,
    "result":{"hash":[byte]}
    "error":null
}
```

**Parameter description：**

| Parameter | Type   | Description      |
| :-------- | :----- | :--------------- |
| hash      | [byte] | transaction hash |

### 2.3 Get the wallet transaction list WalletTransactionList

**Request message：**

```
request: http.post
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.WalletTxList",
    "params":[{"fromTx":"string","count":int32,"direction":int32}]
}
```

**Parameter description：**

| Parameter | Type   | If Necessary | Description                                                  |
| :-------- | :----- | :----------- | :----------------------------------------------------------- |
| fromTx    | string | yes          | Sprintf(“%018d”, height*100000 + index)represents getting the list of transactions from the index in height; the first pass is empty to get the latest transaction |
| count     | int32  | yes          | get the number of transaction list                           |
| direction | int32  | yes          | search method: 0, get the latest transaction data, sort in reverse order, the time height in the transaction list is decreasing; 1，正序排序，按照时间，区块高度增加的方向获取交易列表 |

**Response message:**

```
response:
{
    "id":0,
    result":
    {
        "txDetails":
        [
            {
                "tx":
                {
                    "execer":"coins",
                    "payload":"0x18010a061080c8afa025",
                    "signature":
                    {
                        "ty":0,
                        "pubkey":"0x02504fa1c28caaf1d5a20fefb87c50a49724ff401043420cb3ba271997eb5a4387",
                        "signature":"0x304402200319c88c5cc349d6c75671f880e6dba2fc46268fe92f9b62ac4b4b52f63cdb700220153374f999044073fb3d12ba686eeb1f237291e3586eafdc4151f44030f86258"
                    },
                    "fee":1000000,
                    "expire":0,
                    "nonce":6281838661429879825,
                    "to":"1Dx744a6KQpDmv76sFMeR7W5SaQGREA2Bu"
                },
                "receipt":
                {
                    "ty":3,
                    "logs":
                    [
                        {
                            "ty":2,
                            "log":"0x08c0cebafefbcf2a1080cafdfdfbcf2a18c0fbc2ffffffffffff01"
                        },
                        {
                            "ty":3,
                            "log":"0x0880cafdfdfbcf2a108082ceddd6cf2a1880b8d0dfdaffffffff01"
                        },
                        {
                            "ty":3,
                            "log":"0x1080c8afa0251880c8afa025"
                        }
                    ]
                },
                "height":21706,
                "index":75,
                "blockTime":1516110740,
                "amount":10000000000,
                "fromAddr":"14KEKbYtKKQm4wMthSK9J4La4nAiidGozt",
                "txHash":"0xc33717bad521f075966a1ed3835904d0acab863493e9cce5d3cd08e7df934751"
                "actionName": "genesis"
            }
        ]
    }    
}
```

**Parameter description：**

| Parameter  | Type       | Description                                                  |
| :--------- | :--------- | :----------------------------------------------------------- |
| execer     | string     | when its value is equal to “coins”, means the transaction is related to the wallet, and the others will be filtered out |
| payload    | []byte     | transaction content, need to be analyzed                     |
| signature  | Signature  | transaction signiture                                        |
| fee        | int64      | transaction fee                                              |
| expire     | int64      | transaction expired block height or time, greater than 1e9 represents the time, otherwise represents the height |
| nonce      | int64      | random number                                                |
| to         | string     | receiving address                                            |
| receipt    | ReceiptLog | if ty is 2, the transaction is valid                         |
| height     | int64      | block height of transaction                                  |
| index      | int64      | used to get transactions                                     |
| txhash     | string     | transaction hash                                             |
| actionname | string     | coins（transfer，withdraw，genesis），ticket（genesis，open，close，miner mining income） |

## 3 Signature Related

### 3.1 Transaction SignRawTx

**Request message：**

```
http.post
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.SignRawTx",
    "params":[{"addr":"string", "key":"string","txhex":"string","expire":"string", "index":int32}]  
}
```

**Parameter description：**

| Parameter | Type   | If Necessary | Description                                                  |
| :-------- | :----- | :----------- | :----------------------------------------------------------- |
| addr      | string | yes          | signature address                                            |
| key       | string | yes          | signature private key，addr and key can be entered either way |
| txhex     | string | yes          | transaction raw data                                         |
| expire    | string | yes          | for expiration time,”300ms”,”-1.5h”or”2h45m” all works，and the unit of effective time are “ns”, “us”(or “µs”),”ms”,”s”,”m”,”h” |
| index     | int32  | yes          | If signature transaction group, then it is the serial number of the transaction to be signed, starting from 1. If it is less than or equal to 0, it is all the transactions in the signature group. |

**Response message:**

```
response
{
    "id":int32,
    "result":{"txhex":"0x7ee6331ed623de7f02721f84f898a502494f9a2f6524cce942fb077e0624896d"},
    "error":null
}
```

**Parameter description：**

| Parameter | Type   | Description                          |
| :-------- | :----- | :----------------------------------- |
| txhex     | string | transaction binary code after signed |

## 4 Seed Related

### 4.1 Generate Random Seed GenSeed

**Request message：**

```
  http.post
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.GenSeed",
    "params":[{"lang":int32}] 
}
```

**Parameter description：**

| Parameter | Type  | If Necessary | Description                                         |
| :-------- | :---- | :----------- | :-------------------------------------------------- |
| lang      | int32 | yes          | lang=0:English lang=1:simplified Chinese characters |

**Response message:**

```
  response
{
    "id":int32,
    "result":{"seed": "string"}
}
```

**Parameter description：**

| Parameter | Type   | Description |
| :-------- | :----- | :---------- |
| seed      | string | seed string |

### 4.2 Save Seed and Encrypt with Password SaveSeed

**Request message：**

```
  http.post
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.SaveSeed",
    "params":[{"seed":"string" ,"passwd":"string"}] 
}
```

**Parameter description：**

| Parameter | Type   | If Necessary | Description                                                  |
| :-------- | :----- | :----------- | :----------------------------------------------------------- |
| seed      | string | yes          | Seeds require 16 words or Chinese characters, refer to the genseed output format, and Spaces are required |
| passwd    | string | yes          | encrypted password, must be a combination of letters and numbers greater than or equal to 8 characters |

**Response message:**

```
  response
{
    "id":int32,
    "result":
    {
        "isOK": bool,
        "msg": "string"
    }
}
```

**Parameter description：**

| Parameter | Type   | Description                                                  |
| :-------- | :----- | :----------------------------------------------------------- |
| isok      | bool   | returns true on success; return false on failure             |
| msg       | string | when successful, return empty; if fail, return error message |

### 4.3 Get Seed Text of Wallet Through Wallet Password GetSeed

**Request message：**

```
  http.post
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.GetSeed",
    "params":[{"passwd":"string"}] 
}
```

**Parameter description：**

| Parameter | Type   | If Necessary | Description        |
| :-------- | :----- | :----------- | :----------------- |
| passwd    | string | yes          | encrypted password |

**Response message:**

```
  response
{
    "id":int32,
    "result":{"seed": "string"}
}
```

**Parameter description：**

| Parameter | Type   | Description        |
| :-------- | :----- | :----------------- |
| seed      | string | return seed string |

## 5 Ticket Binding Mining Related

### 5.1 Create Mining Transaction CreateBindMiner

**Request message：**

```
http.post
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"ticket.CreateBindMiner",
    "params":[{"bindAddr":"string", "originAddr":"string"}]
}
```

**Parameter description：**

| Parameter  | Type   | If Necessary | Description      |
| :--------- | :----- | :----------- | :--------------- |
| bindAddr   | string | yes          | mining address   |
| originAddr | string | yes          | original address |

**Response message:**

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

**Parameter description：**

| Parameter | Type   | Description                |
| :-------- | :----- | :------------------------- |
| txHex     | string | binding mining transaction |

### 5.2 Get Amount of Tickets GetTicketCount

**Request message：**

```
http.post
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"ticket.GetTicketCount",
    "params":[]
}
```

**Response message:**

```
response
{
    "id":int32,
    "result":int64
}
```

**Parameter description：**

| Parameter | Type  | Description                  |
| :-------- | :---- | :--------------------------- |
| result    | int64 | return the number of tickets |

### 5.3 Get Wallet Status GetWalletStatus

**Request message：**

```
  request: http.post
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.GetWalletStatus",
    "params":[] 
}
```

**Response message:**

```
  response:
{
    "isWalletLock": bool,
    "isAutoMining": bool,
    "isHasSeed": bool,
    "isTicketLock": bool
}
```

**Parameter description：**

| Parameter    | Type | Description                                                  |
| :----------- | :--- | :----------------------------------------------------------- |
| isWalletLock | bool | when wallet is unlocked, it returns false; returns true when locked |
| isAutoMining | bool | true means automatically start mining                        |
| isHasSeed    | bool | true means that seed has already existed                     |
| isTicketLock | bool | when ticket is unlocked, it returns false; returns true when locked |

