WhatsMiner API v2.0.5

Posted on Edited on In Views: Word count in article: 24k Reading time ≈ 21 mins.

Summary

This article describes how to use the whatsminer’s API. The intendedaudience is mine management software developers. The mine management
software functions similar to WhatMinerTool can be realized throughtheAPI. The API read permission is granted by default, and the API write permissionneeds to be enabled through the WhatMinerTool, follow these steps:

1.Change the default password(admin);
2.Enable the API by the WhatsMinerTool;

Protocol

The whatsminer API TCP port is 4028.

Notice:

  1. If no data is received within 10 seconds after the port is connected, theconnection will time out and be closed.
  2. Miner supports max 16 IP clients, one IP can get 32 tokens, and a tokenkeepalive time is 30 minutes.

JSON API return format:

1
2
3
4
5
6
7
{
    "STATUS":"string", 
    "When":12345678, // integer 
    "Code":133, 
    "Msg":"string", // string or object 
    "Description":"string"
}

Message Code:

Code Message
14 invalid API command or data
23 invalid JSON message
45 permission denied
131 command OK
132 command error
134 get token message OK
135 check token error
136 token over max times
137 base64 decode error

API ciphertext

Notice: the readable API supports two communication modes: plaintext andciphertext; the writable API supports only ciphertext communication

Encryption algorithm:
Ciphertext = aes256(plaintext)，ECB mode
Encode text = base64(ciphertext)

Steps as follows:
(1)api_cmd = token,$sign|api_str
(2)enc_str = aes256(api_cmd, $key)
(3)tran_str = base64(enc_str)

api_str is API command plaintext

Generate aeskey step：
(1)Get token from miner: $time $salt $newsalt
(2)Generate key:
key = md5(salt + admin_password)
Reference code:
key = openssl passwd -1 -salt $salt "${admin_password}"
(3)Generate aeskey:
aeskey = sha256($key)

e.g.:
set_led|auto ->
token,$sign|set_led|auto ->
ase256(“token,sign|set_led|auto”, $aeskey) ->
base64(ase256(“token,sign|set_led|auto”, $aeskey) ) ->
enc|base64(ase256(“token,sign|set_led|auto”, $aeskey))

1
2
3
4
{
    "enc": 1 , // integer
    "data":"base 64 str"
}

The flow

flowchart TD
    A[Start] --> B[Get token]
    B --> C{Return error?}
    C -->|Yes| D[END]
    C -->|No| E[Token]
    E --> F[aes256 api command with sign]
    F --> G[base64 api command]
    G --> H[Send API]
    H --> I[Receive]
    I --> D

Readable API

Summary

Contains fan speed, power info, etc

1
2
3
{
    "cmd":"summary" 
}

retrun

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
    "STATUS": [
        {
            "STATUS": "S",
            "Msg": "Summary"
        }
    ],
    "SUMMARY": [
        {
            "Elapsed": 2648,
            "MHS av": 84983730.62,
            "MHS 5s": 102423869.64,
            "MHS 1m": 86361423.06,
            "MHS 5m": 84941366.02,
            "MHS 15m": 84969424.09,
            "HS RT": 84941366.02,
            "Accepted": 804,
            "Rejected": 0,
            "Total MH": 225043191209.0000,
            "Temperature": 80.00,
            "freq_avg": 646,
            "Fan Speed In": 4530,
            "Fan Speed Out": 4530,
            "Power": 3593,
            "Power Rate": 42.31,
            "Pool Rejected%": 0.0000,
            "Pool Stale%": 0.0000,
            "Last getwork": 0,
            "Uptime": 20507,
            "Security Mode": 0,
            "Hash Stable": true,
            "Hash Stable Cost Seconds": 17569,
            "Hash Deviation%": 0.1398,
            "Target Freq": 574,
            "Target MHS": 76157172,
            "Env Temp": 32.00,
            "Power Mode": "Normal",
            "Factory GHS": 84773,
            "Power Limit": 3600,
            "Chip Temp Min": 75.17,
            "Chip Temp Max": 101.25,
            "Chip Temp Avg": 89.60,
            "Debug": "-0.0_100.0_354",
            "Btminer Fast Boot": "disable"
        }
    ]
}

Pools

Contains pool miner information.

1
2
3
{
    "cmd":"pools" 
}

return

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
{
    "STATUS": [
        {
            "STATUS": "S",
            "Msg": "1 Pool(s)"
        }
    ],
    "POOLS": [
        {
            "POOL": 1,
            "URL": "stratum+tcp://btc.ss.poolin.com:443",
            "Status": "Alive",
            "Priority": 0,
            "Quota": 1,
            "Long Poll": "N",
            "Getworks": 1,
            "Accepted": 0,
            "Rejected": 0,
            "Works": 0,
            "Discarded": 0,
            "Stale": 0,
            "Get Failures": 0,
            "Remote Failures": 0,
            "User": "microbtinitial",
            "Last Share Time": 0,
            "Diff1 Shares": 0,
            "Proxy Type": "",
            "Proxy": "",
            "Difficulty Accepted": 0.00000000,
            "Difficulty Rejected": 0.00000000,
            "Difficulty Stale": 0.00000000,
            "Last Share Difficulty": 0.00000000,
            "Work Difficulty": 0.00000000,
            "Has Stratum": 1,
            "Stratum Active": true,
            "Stratum URL": "btc-vip-3dcoa7jxu.ss.poolin.com",
            "Stratum Difficulty": 65536.00000000,
            "Best Share": 0,
            "Pool Rejected%": 0.0000,
            "Pool Stale%": 0.0000,
            "Bad Work": 0,
            "Current Block Height": 0,
            "Current Block Version": 536870916
        }
    ]
}

Edevs/devs

Contains information for each hash board.

1
2
3
{
    "cmd":"edevs" 
}

return

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
{
    "STATUS": [
        {
            "STATUS": "S",
            "Msg": "3 ASC(s)"
        }
    ],
    "DEVS": [
        {
            "ASC": 0,
            "Slot": 0,
            "Enabled": "Y",
            "Status": "Alive",
            "Temperature": 80.00,
            "Chip Frequency": 587,
            "MHS av": 10342284.80,
            "MHS 5s": 5298845.66,
            "MHS 1m": 8508905.30,
            "MHS 5m": 10351110.56,
            "MHS 15m": 10296867.74,
            "HS RT": 10351110.56,
            "HS Factory": 28836,
            "Accepted": 18,
            "Rejected": 0,
            "Last Valid Work": 1643183296,
            "Upfreq Complete": 0,
            "Effective Chips": 156,
            "PCB SN": "HEM1EP9C400929K60003",
            "Chip Data": "K88Z347-2039 BINV01-195001D",
            "Chip Temp Min": 80.56,
            "Chip Temp Max": 97.00,
            "Chip Temp Avg": 89.89,
            "chip_vol_diff": 9
        },
        {
            "ASC": 1,
            "Slot": 1,
            "Enabled": "Y",
            "Status": "Alive",
            "Temperature": 80.00,
            "Chip Frequency": 590,
            "MHS av": 10259948.84,
            "MHS 5s": 5413853.90,
            "MHS 1m": 8577249.68,
            "MHS 5m": 10441143.92,
            "MHS 15m": 10214893.36,
            "HS RT": 10441143.92,
            "Accepted": 16,
            "Rejected": 0,
            "Last Valid Work": 1643183291,
            "Upfreq Complete": 0,
            "Effective Chips": 156,
            "PCB SN": "HEM1EP9C400929K60001",
            "Chip Data": "K88Z347-2039 BINV01-195001D",
            "Chip Temp Min": 77.94,
            "Chip Temp Max": 96.50,
            "Chip Temp Avg": 88.23,
            "chip_vol_diff": 9
        },
        {
            "ASC": 2,
            "Slot": 2,
            "Enabled": "Y",
            "Status": "Alive",
            "Temperature": 80.00,
            "Chip Frequency": 590,
            "MHS av": 10258829.89,
            "MHS 5s": 5571781.71,
            "MHS 1m": 8675316.17,
            "MHS 5m": 10479953.41,
            "MHS 15m": 10213779.32,
            "HS RT": 10479953.41,
            "Accepted": 19,
            "Rejected": 0,
            "Last Valid Work": 1643183296,
            "Upfreq Complete": 0,
            "Effective Chips": 156,
            "PCB SN": "HEM1EP9C400929K60002",
            "Chip Data": "K88Z347-2039 BINV01-195001D",
            "Chip Temp Min": 80.50,
            "Chip Temp Max": 97.44,
            "Chip Temp Avg": 90.91,
            "chip_vol_diff": 9
        }
    ]
}

Devdetails

1
2
3
{
    "cmd":"devdetails" 
}

return

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
{
    "STATUS": [
        {
            "STATUS": "S",
            "When": 1643181852,
            "Code": 69,
            "Msg": "Device Details",
            "Description": "btminer"
        }
    ],
    "DEVDETAILS": [
        {
            "DEVDETAILS": 0,
            "Name": "SM",
            "ID": 0,
            "Driver": "bitmicro",
            "Kernel": "",
            "Model": "M30S+VE40"
        },
        {
            "DEVDETAILS": 1,
            "Name": "SM",
            "ID": 1,
            "Driver": "bitmicro",
            "Kernel": "",
            "Model": "M30S+VE40"
        },
        {
            "DEVDETAILS": 2,
            "Name": "SM",
            "ID": 2,
            "Driver": "bitmicro",
            "Kernel": "",
            "Model": "M30S+VE40"
        }
    ]
}

Get PSU

Contains power information

1
2
3
{
    "cmd":"get_psu" 
}

return

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
    "STATUS": "S",
    "When": 1643182793,
    "Code": 131,
    "Msg": {
        "name": "P221B",
        "hw_version": "V01.00",
        "sw_version": "V01.00.V01.03",
        "model": "P221B",
        "iin": "8718",
        "vin": "22400",
        "pin": "3000",
        "fan_speed": "6976",
        "version": "-1",
        "serial_no": "A1232B0120100049",
        "vendor": "7",
        "temp0": "33.5"
    },
    "Description": ""
}

Get version

Get miner API version.

1
2
3
{
    "cmd":"get_version" 
}

return

1
2
3
4
5
6
7
8
9
10
11
12
{
    "STATUS": "S",
    "When": 1643187652,
    "Code": 131,
    "Msg": {
        "api_ver": "2.0.5",
        "fw_ver": "20220125.13.Rel",
        "platform": "H6OS",
        "chip": "K88Z001-2039 BINV01-195001B"
    },
    "Description": ""
}

Get token

Plaintext must be used, and the miner returns plaintext.

1
2
3
{
    "cmd":"get_token" 
}

return

1
2
3
4
5
6
7
8
9
10
11
{
    "STATUS": "string",
    "When": 12345678,
    "Code": 133,
    "Msg": {
        "time": "str",
        "salt": "str",
        "newsalt": "str"
    },
    "Description": ""
}

Status

Get btminer status and firmware version.

1
2
3
{
    "cmd":"status" 
}

return

1
2
3
4
5
6
7
8
{
    "btmineroff": "str",      // "true"/"false"
    "Firmware Version": "str",
    "power_mode": "str",
    "power_limit_set": "str", // Empty string is the default value
    "hash_percent": "str"      // changed by set_target_freq
}

Get miner info

1
2
3
4
5
{
    "cmd": "get_miner_info",
    "info": "ip,proto,netmask,gateway,dns,hostname,mac,ledstat,minersn,powersn"
}

return

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
    "STATUS": "S",
    "When": 1618212903,
    "Code": 131,
    "Msg": {
        "ip": "192.168.2.16",
        "proto": "dhcp",
        "netmask": "255.255.255.0",
        "dns": "114.114.114.114",
        "mac": "C6:07:20:00:1E:C2",
        "ledstat": "auto",
        "gateway": "192.168.2.1",
        "minersn": "str",
        "powersn": "str",
        "ut_speed": "5"
    },
    "Description": ""
}

Get error code

You can use this command to obtain the machine error codes.

1
2
3
{
    "cmd":"get_error_code"
}

return

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "STATUS": "S",
    "When": 1642392343,
    "Code": 131,
    "Msg": {
        "error_code": [
            {
                "329": "2022-01-17 11:28:11"
            }
        ]
    },
    "Description": ""
}

The API command can be used for two joins

eg.

1
2
3
{
    "cmd":"summary+pools"
}

Writable API

Writable API only supports ciphertext.

The writable API must first obtain the token as follows:

1
2
3
4
5
6
client -> miner：
{"cmd":"get_token"}
miner -> client：
{"time":"str","salt":"str","newsalt":"str"}
e.g.：
{"time":"5626","salt":"BQ5hoXV9","newsalt":"jbzkfQls"}
  • time: timestamp, this count starts at the Unix Epoch on January 1st, 1970 at UTC.
  • salt: a random salt is generated for each password
  • newsalt: new salt for sign

Token calculation method:
Get token from miner: time salt newsalt.

  1. calculate key use admin’s password and salt.
  2. time is the last four characters of time.
    key = md5(salt + admin_password)
    sign = md5(newsalt + key + time)

The reference code in Ubuntu:
First, Get those values from miner: $time $salt $newsalt.

Ubuntu Shell command:
key = openssl passwd -1 -salt $salt "${admin_password}"|cut -f 4 -d'$'
sign=openssl passwd -1 -salt $newsalt "${key}${time:0-4}"|cut -f 4 -d'$'
The default user name and password are admin

Update pools information

This operation updates the pool configuration and switches immediately

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "token": "str",
  "cmd": "update_pools",
  "pool1": "str",
  "worker1": "str",
  "passwd1": "str",
  "pool2": "str",
  "worker2": "str",
  "passwd2": "str",
  "pool3": "str",
  "worker3": "str",
  "passwd3": "str"
}

Restart btminer

This operation only restarts the btminer process, not the control board.

1
2
3
4
{
  "token": "str",
  "cmd": "restart_btminer"
}

Power off hashboard

This operation simply stops mining and turns off the power of the hashboard.

1
2
3
4
{
  "token": "str",
  "cmd": "power_off"
}

Power on hashboard

This operation simply starts mining and turns on the power of the hashboard.

1
2
3
4
{
  "token": "str",
  "cmd": "power_on"
}

Manage led

Recovery to automatic control:

1
2
3
4
5
{
    "token": "str",
    "cmd": "set_led",
    "param": "auto"   // The LED flashes in auto mode
}

LED manual setting:

1
2
3
4
5
6
7
8
{
    "token": "str",
    "cmd": "set_led",
    "color": "str",    // str must be "red" or "green"
    "period": integer,  // flash cycle (ms)
    "duration": integer, // LED on time in cycle (ms)
    "start": integer    // LED on time offset in cycle (ms)
}

Switch power mode

After the miner power mode is successfully configured, btminer will berestarted.

1
2
3
4
{
  "token": "str",
  "cmd": "set_low_power"  // or "set_high_power" or "set_normal_power"
}

Firmware upgrading

Upgrade flow:
Client -> miner(text flow): “update_firmware”

1
2
3
4
{
  "token": "str",
  "cmd": "update_firmware"
}

Miner -> client(text flow): “ready”

1
2
3
4
5
6
7
{
  "STATUS": "S",
  "When": 1594179080,
  "Code": 131,
  "Msg": "ready",
  "Description": ""
}

Client -> miner(binary flow): file_size(4Bytes) file_data
file_size: size of upgrade file,send integer to stream as little endian. file_data:file binary flow
Check upgrading by the value of “Firmware Version” returned by summary.

All interactions are one-time TCP connections.

Reboot system

This operation restarts the control board.

1
2
3
4
{
  "token": "str",
  "cmd": "reboot"
}

Restore to factory setting

This operation restores the network configuration, systempasswords, user
permission, turns off the api switch, web pools set, removes pools, power
mode, power limit, etc.

1
2
3
4
{
  "token": "str",
  "cmd": "factory_reset"
}

Modify the password of admin account

The maximum password length is 8 bytes. Notice: the token must be acquired again from miner for encrypted transmission.

1
2
3
4
5
6
{
    "token": "str",
    "cmd": "update_pwd",
    "old": "str",  // use letters, numbers, and underscores
    "new": "str"   // use letters, numbers, and underscores
}

Modify network configuration

Notice: after modifying the configuration, miner will restart.

1
2
3
4
5
{
  "token": "str",
  "cmd": "net_config",
  "param": "dhcp"
}
1
2
3
4
5
6
7
8
9
{
    "token": "str",
    "cmd": "net_config",
    "ip": "str",
    "mask": "str",
    "gate": "str",
    "dns": "str",  // eg.: "114.114.114.114 192.168.0.1", divide by space
    "host": "str"
}

Download logs

This operation exports the miner log files.

Download flow:
Client -> miner(text flow):

1
2
3
4
{
  "token": "str",
  "cmd": "download_logs"
}

Miner -> client(text flow):

1
2
3
4
5
6
7
8
9
{
  "STATUS": "S",
  "When": 1603280777,
  "Code": 131,
  "Msg": {
    "logfilelen": "str"
  },
  "Description": ""
}

Miner -> client(binary flow):
The miner sends the file contents after 10ms delay.

Set target frequency

Set a new target mining frequency, which adjusts a certain percentagebasedon the mining frequency in normal power mode (a percentage of 0 meansnoadjustment). Please note that only water-cooled and liquid-cooled machinessupport overclocking, while fan-cooled machines only support underclocking. After successful setting, the mining service will automatically restart.

1
2
3
4
5
{
    "cmd": "set_target_freq",
    "percent": "str",  // range: -100 ~ 100
    "token": "str"
}

Enablebt miner fastboot

Set the mining service to quickly increase power at startup, useful for miningfarm load power situations that require a quick start. Please note that thissetting allows the machine’s power to quickly rise to the target value, not
the hash rate to stabilize quickly, so it has little impact on the time tostabilize hash rate. The setting will take effect upon the next startupof themining service.

1
2
3
4
{
  "cmd": "enable_btminer_fast_boot",
  "token": "str"
}

Disablebt miner fastboot

Disable the btminer fast boot mode. The setting will take effect uponthenext
startup of the mining service.

1
2
3
4
{
  "cmd": "disable_btminer_fast_boot",
  "token": "str"
}

Enableweb pools

Allows configuration of pools on web pages with immediate effect.

1
2
3
4
{
  "cmd": "enable_web_pools",
  "token": "str"
}

Disableweb pools

Turn off the configure pools feature on the web page with immediate effect.

1
2
3
4
{
  "cmd": "disable_web_pools",
  "token": "str"
}

Set hostname

This configuration does not take effect until the network is restarted.

1
2
3
4
5
{
  "cmd": "set_hostname",
  "hostname": "str",
  "token": "str"
}

Set zone

This configuration does not take effect until the network is restarted.

1
2
3
4
5
6
{
  "cmd": "set_zone",
  "timezone": "CST-8",
  "zonename": "Asia/Shanghai",
  "token": "str"
}

Load log

Configure the rsyslog log server.

1
2
3
4
5
6
7
{
    "cmd": "load_log",
    "ip": "str",
    "port": "str",
    "proto": "str",  // tcp/udp
    "token": "str"
}

Set power percent(Fastmode)

The dynamic adjustment of the power percentage is based on the initial
stable mining power. The adjustment process is completed within onesecond. Please note that only an approximate power percentage canbeachieved, and the lowest percentage that can maintain stable operationisrelated to the machine’s own characteristics, environmental temperature, and cooling conditions. If the target percentage is too low, it may causethemachine to become unbalanced and automatically restart the miningservice. The maximum percentage cannot exceed 100%. This is recommendedfor
temporary adjustments only, as running for extended periods may leadtoinstability. Compared to Set power percent V2 (Normal mode), it is faster inadjusting power percentage, however, it comes with a greater loss inperformance. If speed of adjustment is not a priority, it is recommendedto
use Set power percent V2 (Normal mode).

1
2
3
4
5
{
    "cmd": "set_power_pct",
    "percent": "str",  // range: 0 ~ 100
    "token": "str"
}

Set power percent V2 (Normalmode)

The dynamic adjustment of power percentage is based on the initial stablemining power. This adjustment process will last for a few minutes andmayresult in a slight but not significant loss in hash rate. Please note that onlyanapproximate power percentage can be achieved, and the lowest percentagethat can maintain stable operation is related to the machine’s own
characteristics, environmental temperature, and cooling conditions. If thetarget percentage is too low, it may cause the machine to become
unbalanced and automatically restart the mining service. This functionis
only permitted for fan-cooled machines in normal or low power mode; thereare no power mode restrictions for water-cooled and liquid-cooled machines. The maximum percentage cannot exceed 100% (future versions will allowwater-cooled and liquid-cooled machines to exceed 100%). Althoughits
impact on performance is less than that of Set power percent (Fast mode), the machine is still not in its optimal state in terms of performance andstability. It is suitable for scenarios where power costs frequently changeandpower adjustments are constantly required. If there is no need for frequent
power adjustments and long-term operation at a specific power level is
preferred, it is recommended to use Adjust power limit or Set target
frequency.

1
2
3
4
5
{
    "cmd": "set_power_pct_v2",
    "percent": "str",  // range: 0 ~ 100
    "token": "str"
}

Set temp offset

Set the target temperature offset for the machine’s hashboard (range: -30to0℃). This will increase the machine fan speed, reducing the strain onthemining farm’s cooling system. This is only effective for air-cooled machines. The setting will take effect upon the next startup of the mining service

1
2
3
4
5
{
    "cmd": "set_temp_offset",
    "temp_offset": "str",  // range: -30 ~ 0
    "token": "str"
}

Adjust power limit

Set the upper limit of the miner’s power. Not higher than the ordinary power
of the machine. If the Settings take effect, the machine will restart.

1
2
3
4
5
{
    "cmd": "adjust_power_limit",
    "power_limit": "str",  // range: 0 ~ 99999
    "token": "str"
}

Adjust upfreq speed

Set the startup speed of the mining service (or the speed of the miner
frequency adjustment and stabilization). The faster the speed, the shorter thetime it takes to reach stable hash rate. 0 represents normal speed, while9represents the fastest speed. The faster the speed, the greater the deviationin target hash rate and power, and the greater the impact on performanceand stability. Fast boot mode cannot be used concurrently.

1
2
3
4
5
{
    "cmd": "adjust_upfreq_speed",
    "upfreq_speed": "str",  // range: 0 ~ 9
    "token": "str"
}

Set poweroff cool

Set whether to cool machine when stopping mining.

1
2
3
4
5
{
    "cmd": "set_poweroff_cool",
    "poweroff_cool": "str",  // type: bool, range: [0, 1]
    "token": "str"
}

Set fan zero speed

Sets whether the fan speed supports the lowest 0 speed.

1
2
3
4
5
{
    "cmd": "set_fan_zero_speed",
    "fan_zero_speed": "str",  // type: bool, range: [0, 1]
    "token": "str"
}

Set heat mode

The water-cooling miner is set to default anti-icing mode. The power-keeping mode ensures that the miner maintains full power duringnetwork outages.

1
2
3
4
5
{
    "cmd": "set_heat_mode",
    "mode": "str",  // anti-icing, heating
    "token": "str"
}

Disable btminer init

Disable miner startup for mining

1
2
3
4
{
  "cmd": "disable_btminer_init",
  "token": "str"
}

Enable btminer init

Enable miner startup for mining.

1
2
3
4
{
  "cmd": "enable_btminer_init",
  "token": "str"
}