Skip to content

Commit

Permalink
Update/Improve API docs
Browse files Browse the repository at this point in the history
  • Loading branch information
Spudz76 committed May 23, 2023
1 parent 2e16703 commit 460ae15
Show file tree
Hide file tree
Showing 4 changed files with 351 additions and 13 deletions.
74 changes: 61 additions & 13 deletions doc/API.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,19 @@ If you want use HTTP API you need enable it (`"enabled": true,`) then choice `po

Offical HTTP client for API: http://workers.xmrig.info/

Example configuration:
Example configuration, used in Curl examples below:

```json
"api": {
"id": null,
"worker-id": null,
},
"http": {
"enabled": false,
"enabled": true,
"host": "127.0.0.1",
"port": 0,
"access-token": null,
"restricted": true
"port": 44444,
"access-token": "SECRET",
"restricted": false
}
```

Expand All @@ -37,30 +37,78 @@ Versions before 2.15 was use another options for API https://github.com/xmrig/xm

## Endpoints

### GET /1/summary
### APIVersion 2

Get miner summary information. [Example](api/1/summary.json).
#### GET /2/summary

### GET /1/threads
Get miner summary information. [Example](api/2/summary.json).

Get detailed information about miner threads. [Example](api/1/threads.json).
#### GET /2/backends

Get detailed information about miner backends. [Example](api/2/backends.json).

### APIVersion 1 (deprecated)

#### GET /1/summary

Get miner summary information. Currently identical to `GET /2/summary`

#### GET /1/threads

**REMOVED** Get detailed information about miner threads. [Example](api/1/threads.json).

Functionally replaced by `GET /2/backends` which contains a `threads` item per backend.

### APIVersion 0 (deprecated)

#### GET /api.json

Get miner summary information. Currently identical to `GET /2/summary`


## Restricted endpoints

All API endpoints below allow access to sensitive information and remote configure miner. You should set `access-token` and allow unrestricted access (`"restricted": false`).

### GET /1/config
### JSON-RPC Interface

Get current miner configuration. [Example](api/1/config.json).
#### POST /json_rpc

Control miner with JSON-RPC. Methods: `pause`, `resume`, `stop`, `start`

### PUT /1/config
Curl example:

```
curl -v --data "{\"method\":\"pause\",\"id\":1}" -H "Content-Type: application/json" -H "Authorization: Bearer SECRET" http://127.0.0.1:44444/json_rpc
```

### APIVersion 2

#### GET /2/config

Get current miner configuration. [Example](api/2/config.json).

#### PUT /2/config

Update current miner configuration. Common use case, get current configuration, make changes, and upload it to miner.

Curl example:

```
curl -v --data-binary @config.json -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer SECRET" http://127.0.0.1:44444/1/config
...GET current config...
curl -v -H "Content-Type: application/json" -H "Authorization: Bearer SECRET" http://127.0.0.1:44444/2/config > config.json
...make changes...
vim config.json
...PUT changed config...
curl -v --data-binary @config.json -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer SECRET" http://127.0.0.1:44444/2/config
```

### APIVersion 1 (deprecated)

#### GET /1/config

Get current miner configuration. Currently identical to `GET /2/config`

#### PUT /1/config

Update current miner configuration. Currently identical to `PUT /2/config`
78 changes: 78 additions & 0 deletions doc/api/2/backends.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
[
{
"type": "cpu",
"enabled": true,
"algo": "rx/0",
"profile": "rx",
"hw-aes": true,
"priority": -1,
"msr": true,
"asm": "intel",
"argon2-impl": "AVX2",
"hugepages": [6, 6],
"memory": 6291456,
"hashrate": [1235.78, 1228.89, null],
"threads": [
{
"intensity": 1,
"affinity": 0,
"av": 1,
"hashrate": [409.75, 406.58, null]
},
{
"intensity": 1,
"affinity": 2,
"av": 1,
"hashrate": [412.9, 411.33, null]
},
{
"intensity": 1,
"affinity": 4,
"av": 1,
"hashrate": [413.11, 410.98, null]
}
]
},
{
"type": "cuda",
"enabled": true,
"algo": "cn-heavy/xhv",
"profile": "cn-heavy/xhv",
"versions": {
"cuda-runtime": "11.6",
"cuda-driver": "11.6",
"plugin": "6.17.1-dev",
"nvml": "11.512.15",
"driver": "512.15"
},
"hashrate": [247.02, 247.34, null],
"threads": [
{
"index": 0,
"threads": 32,
"blocks": 38,
"bfactor": 6,
"bsleep": 25,
"affinity": -1,
"cclock": 0,
"mclock": 0,
"dataset_host": false,
"hashrate": [246.77, 247.26, null],
"name": "NVIDIA GeForce GTX 970",
"bus_id": "01:00.0",
"smx": 13,
"arch": 52,
"global_mem": 4294836224,
"clock": 1177,
"memory_clock": 3666,
"health": {
"temperature": 69,
"power": 161,
"clock": 1328,
"mem_clock": 3662,
"fan_speed": [100]
}
}
]
}
]
136 changes: 136 additions & 0 deletions doc/api/2/config.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,136 @@
{
"api": {
"id": null,
"worker-id": null
},
"http": {
"enabled": true,
"host": "127.0.0.1",
"port": 44444,
"access-token": "SECRET",
"restricted": false
},
"autosave": true,
"background": false,
"colors": true,
"title": true,
"randomx": {
"init": -1,
"init-avx2": -1,
"mode": "auto",
"1gb-pages": true,
"rdmsr": true,
"wrmsr": true,
"cache_qos": false,
"numa": true,
"scratchpad_prefetch_mode": 1
},
"cpu": {
"enabled": true,
"huge-pages": true,
"huge-pages-jit": true,
"hw-aes": null,
"priority": null,
"memory-pool": true,
"yield": true,
"asm": true,
"argon2-impl": null,
"argon2": [0, 2, 4, 6, 5, 7],
"astrobwt/v2": [1, 2, 3, 4, 5, 6, 7],
"cn": [
[1, 0],
[1, 2],
[1, 4]
],
"cn-heavy": [
[1, 0],
[1, 2]
],
"cn-lite": [
[1, 0],
[1, 2],
[1, 4],
[1, 6],
[1, 5],
[1, 7]
],
"cn-pico": [
[2, 1],
[2, 2],
[2, 3],
[2, 4],
[2, 5],
[2, 6],
[2, 7]
],
"cn/2": [
[1, 0],
[1, 2],
[1, 4]
],
"cn/upx2": [
[2, 1],
[2, 2],
[2, 3],
[2, 4],
[2, 5],
[2, 6],
[2, 7]
],
"ghostrider": [
[8, 0],
[8, 2],
[8, 4]
],
"rx": [0, 2, 4],
"rx/arq": [1, 2, 3, 4, 5, 6, 7],
"rx/keva": [0, 2, 4, 6, 5, 7],
"rx/wow": [0, 2, 4, 6, 5, 7],
"cn-lite/0": false,
"cn/0": "cn"
},
"log-file": null,
"donate-level": 0,
"donate-over-proxy": 0,
"pools": [
{
"algo": null,
"coin": null,
"url": "some.pool:10064",
"user": "4blahblahblahblahblahblahblahblahblahblahblahblahblahblahblahblahblahblahblahblahblahblahblahbl",
"pass": "x",
"rig-id": null,
"nicehash": false,
"keepalive": true,
"enabled": true,
"tls": false,
"wss": false,
"daemon": false,
"socks5": null,
"self-select": null,
"submit-to-origin": false
}
],
"retries": 5,
"retry-pause": 5,
"print-time": 64,
"syslog": false,
"tls": {
"enabled": false,
"protocols": null,
"cert": null,
"cert_key": null,
"ciphers": null,
"ciphersuites": null,
"dhparam": null
},
"dns": {
"ipv6": false,
"ttl": 30
},
"user-agent": null,
"verbose": 1,
"watch": true,
"pause-on-battery": false,
"pause-on-active": false
}

0 comments on commit 460ae15

Please sign in to comment.