Contact Sales

Using gRPCurl with BOS API

Here's a quick start guide for using grpcurl with the BOS Public API, streamlined into step-by-step commands, if you want to get more detailed information about the available fields and their values, refer to the Using grpcurl with the BOS Public API page.

1. Download and Install grpcurl:

wget https://github.com/fullstorydev/grpcurl/releases/download/v1.8.9/grpcurl_1.8.9_linux_x86_64.tar.gz
tar -xzf grpcurl_1.8.9_linux_x86_64.tar.gz
sudo mv grpcurl /usr/local/bin/

2. Use Port 50051 for BOS Public API:

  • The default port for the BOS Public API is 50051.

3. Request Authentication Token:

Sample Request:

grpcurl -plaintext -v -d '{"username": "root", "password": ""}' <MINER_IP>:50051 'braiins.bos.v1.AuthenticationService/Login' 2>&1 | grep authorization:
  • Ensure to replace <MINER_IP> with the actual IP address of your miner.

Expected Response:

authorization: pHbLw9hwZ0gWnxYx

4. Example of Get Request (Get Miner Details):

Sample Request:

grpcurl -plaintext -H 'authorization:<YOUR_SESSION_TOKEN>' <MINER_IP>:50051 'braiins.bos.v1.MinerService/GetMinerDetails'
  • Replace <YOUR_SESSION_TOKEN> with the token obtained from the login response and, <MINER_IP> with the actual IP address of your miner.

Expected Response:

{
    "uid": "LQakFUOmGRvnG7pb",
    "miner_identity": {
        "brand": "MINER_BRAND_ANTMINER",
        "model": "MINER_MODEL_ANTMINER_S19J",
        "name": "Antminer S19J88",
        "miner_model": "Antminer S19J88"
    },
    "platform": "PLATFORM_AM3_AML",
    "bos_mode": "BOS_MODE_NAND",
    "bos_version": {
        "current": "2024-02-23-0-b19385b7-24.02-plus-rc",
        "major": "2022-09-13-0-11012d53-22.08-plus",
        "bos_plus": true
    },
    "hostname": "Antminer",
    "mac_address": "02:7a:01:27:3d:4c",
    "system_uptime": "73094",
    "sticker_hashrate": {
        "gigahash_per_second": 87000
    },
    "bosminer_uptime_s": "73037",
    "system_uptime_s": "73094"
}
  1. Example of Set Request (Set Power Target):

Sample Request:

grpcurl -plaintext -H 'authorization <YOUR_SESSION_TOKEN>' -d '{ "power_target": { "watt": "1712" }, "save_action": 2 }' <MINER_IP>:50051 'braiins.bos.v1.PerformanceService/SetPowerTarget'

  • Replace <YOUR_SESSION_TOKEN> with the token obtained from the login response and, <MINER_IP> with the actual IP address of your miner.

  • Set the watt value to your desired power target. Be careful about the power target value you set, as it can affect the miner's performance and stability.

  • The saveAction field specifies how changes made via API calls should be handled regarding the miner's configuration.

Expected Response:

{
    "powerTarget": {
        "watt": "1712"
    }
}

If you need to get more information about the available fields and their values, refer to the Using grpcurl with the BOS Public API page.

6. Example of Stream Request (GetMinerStatus):

Sample Request:

grpcurl -plaintext -H 'authorization: <YOUR_SESSION_TOKEN>' -d '{}' <MINER_IP>:50051 'braiins.bos.v1.MinerService/GetMinerStatus'
  • Replace <YOUR_SESSION_TOKEN> with the token obtained from the login response and, <MINER_IP> with the actual IP address of your miner.

Expected Response:

{
    "status": "MINER_STATUS_NORMAL"
}
  • For streaming responses, grpcurl will print out each message as it's received until the server closes the stream or until you terminate the command (e.g., by pressing Ctrl+C).

7. Additional Resources:

Save Action Field Explanation

The SaveAction field specifies how changes made via API calls should be handled regarding the miner's configuration:

  • SAVE_ACTION_UNSPECIFIED: Default behavior without explicit save action.
  • SAVE_ACTION_SAVE: Saves changes without applying them immediately.
  • SAVE_ACTION_SAVE_AND_APPLY: Saves and applies changes right away.
  • SAVE_ACTION_SAVE_AND_FORCE_APPLY: Forces immediate application of changes, bypassing any normal checks.
Flags and Options

The following are some common flags and options used with grpcurl commands:

  • -plaintext option indicates that the connection should not be encrypted. This is suitable for local testing.
  • -v flag is to get verbose output, helping understand the gRPC calls better and display the request and response headers.
  • -d flag is used to specify the request data.
  • -H flag is used to specify a request header.
  • -msg-template option is used to generate a message template for the request, providing a skeleton with all the fields you need to populate for your actual request.
  • -import-path option is used to specify the path to the directory containing the proto files.
  • -proto option is used to specify the proto file for the service you are interacting with.
Was this helpful?