matroskin 0.1.0

whatsminer api client lib
Documentation 
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

# Overview

This section provides an overview of how to interact with the API.

## Connection

The API listens for TCP connections on port **4433**. A maximum of **10** concurrent clients are supported.

The **heartbeat packet** is `0x00,0x00,0x00,0x00`. For details on data framing, see TCP Data Framing.

## Permissions

The API has two access levels:

- **Read-only access** (for `get.*` commands) is enabled by default and requires no special configuration.
- **Write access** (for `set.*` commands) is disabled by default for security. To enable it, you must:
  - Change the default password for the admin account, as write operations are blocked when using the default password.
  - Use the **WhatsminerTool** to enable the API write access switch.

Attempting a write operation without completing these steps will result in a "no permission" error.

## Authentication for Write Commands

To execute a write command (`set.*`), a security token is required. First, call the `get.device.info` command to retrieve a unique salt value. This salt is essential for generating the security token. For the detailed algorithm, see Token Generation.

## Request Format

The request JSON object structure depends on the command type:

- **Read Commands (`get.*`)**: These requests typically only require the `cmd` field. Some may also use the `param` field for specific queries.
- **Write Commands (`set.*`)**: These are more complex and require authentication. The object must include `cmd`, `ts`, `token`, `account` and `param`.
  - `account`: Specifies the operator for the command. Supported accounts are `super`, `user1`, `user2`, `user3`. For security, using the admin account is deprecated and no longer supported.
  - `ts`: A Unix timestamp used for the token generation.
  - `token`: The security token required for authentication.

## Response Format

The response JSON object includes the following properties: `code`, `when`, `msg`, and `desc`.

- `desc`: Indicates which command the response corresponds to.
- `msg`: Contains the response data, which can be a string or a JSON object.
- `code`: Indicates the status of the request, as defined in the table below.

| Code value | Details |
|------------|---------|
| 0 | Success |
| -1 | Fail |
| -2 | Invalid command |
| -3 | Invalid json item |
| -4 | No permission |
| -5 | Out of memory |