xmrig/doc/API.md
2023-07-12 02:06:53 -06:00

3.5 KiB

HTTP API

If you want use HTTP API you need enable it ("enabled": true,) then choice port and optionaly host. API not available if miner built without HTTP support (-DWITH_HTTP=OFF).

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

Example configuration, used in Curl examples below:

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

Global API options

  • id Miner ID, if not set created automatically.
  • worker-id Optional worker name, if not set will be detected automatically.

HTTP API options,

  • enabled Enable (true) or disable (false) HTTP API.
  • host Host for incoming connections http://<host>:<port>, to allow connections from all interfaces use 0.0.0.0 (IPv4) or :: (IPv4+IPv6).
  • port Port for incoming connections http://<host>:<port>, zero port is valid option and means random port.
  • access-token Bearer access token to secure access to API. Miner support this token only via Authorization header.
  • restricted Use false to allow remote configuration.

If you prefer use command line options instead of config file, you can use options: --api-id, --api-worker-id, --http-enabled, --http-host, --http-access-token, --http-port, --http-no-restricted.

Versions before 2.15 was use another options for API https://github.com/xmrig/xmrig/issues/1007

Endpoints

APIVersion 2

GET /2/summary

Get miner summary information. Example.

GET /2/backends

Get detailed information about miner backends. Example.

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.

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).

JSON-RPC Interface

POST /json_rpc

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

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.

PUT /2/config

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

Curl example:

...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