PoP Miner API

See: PoP_Miner_CommandLine

Introduction

The VeriBlock PoP Mining software has an embedded HTTP API that makes available some basic functionality for third-party integrations. By default, this HTTP API is bound to 127.0.0.1:8600. Both the host address and port can be configured in the ncpop.properties file via the properties: http.api.address and http.api.port, respectively. If running multiple miners on a single machine, each miner will need at least the port configured uniquely or it will be unable to start the embedded HTTP server.

Any requests requiring a message body should be formatted as JSON, and conversely all responses will be formatted as JSON as well.

NOTE: This requires 0.3.12-rc.5 of the PoP Miner CLI or higher.

Sample client to call PoP API: https://github.com/VeriBlock/samples/tree/master/pop/pop-api-client/csharp/PoPClient

Setup the API

1. [OPTIONAL] In "ncpop.properties", configure the http.api.address and http.api.port. If not configured, by default these will be 127.0.0.1:8600
2. Start the PoP Miner. See: https://wiki.veriblock.org/index.php?title=HowTo_run_PoP_Miner
3. Ensure the PoP Miner is ready to mine. If the PoP Miner cannot run the "mine" command, then the API will not run the "mine" command either.

API Documentation

GET /api/config

Lists the effective configuration values. Same as running listconfig from the command-line. The response will be formatted as a JSON object in which each property name represents the configuration name and the property value represents the configuration value.

Response

{
    "auto.mine.round1": "false",
    "pop.cron.schedule": "",
    "bitcoin.fee.max": "8000",
    "bitcoin.fee.perkb": "20000",
    "http.api.port": "8600",
    "bitcoin.minrelayfee.enabled": "false",
    "nodecore.rpc.password": "",
    "nodecore.rpc.ssl": "false",
    "nodecore.rpc.cert.chain.path": "",
    "http.api.address": "127.0.0.1",
    "bitcoin.network": "mainnet",
    "nodecore.rpc.host": "127.0.0.1",
    "pop.action.timeout": "90",
    "nodecore.rpc.port": "10501",
    "auto.mine.round4": "false",
    "auto.mine.round3": "false",
    "auto.mine.round2": "false"
}

PUT /api/config

Updates a single configuration value. Same as running setconfig from the command-line.

Request

Request properties:

Property	Constraint	Data Type	Description
key	Required	String	Represents the name of a configuration property to set. Possible values are listed under GET /api/config.
value	Required	String	Represents the value to be set for a given configuration property. The value should be a string but must be convertible to the appropriate type for that configuration property. (E.g. "auto.mine.round1" must have a value of "true" or "false")

{
    "key": "auto.mine.round4",
    "value": "true"
}

Response

A successful request will return a 200 OK status code response with the following body:

[
    {}
]

An unsuccessful action will return a 500 Server Error status code with some explanation for the failure in the body:

[
    {
        "details": [
            "Property 'pop.action.timeout' requires a positive integer value representing the number of seconds to wait before timing out."
        ]
    }
]

GET /api/miner

Lists several miner properties, like the BTC address and amount, and VBK address.

The very first time this is called, if the 'y' acknowledgement hasn't been accepted yet, it will also list the wallet seeds.

NOTE: pass in '-skipAck' from the command line on startup to bypass the 'y' acknowledgement and therefore automate a fully new instance

Response

            {
              "minerAddress": "V9uC3ywS12qW4ESD9783eZXVU3voMo",
              "bitcoinAddress": "1CRb4b5u2AYdaoovgV9aQWV3kSt9x66rJq",
              "bitcoinBalance": 0,
              "walletSeed": [
                "1548958861",
                "cave",
                "conduct",
                "pottery"
              ]
            }

GET /api/operations

Lists the current running operations. Same as running listoperations from the command-line.

Response

[
    {
        "operationId": "ce3c3e8b",
        "endorsedBlockNumber": 22,
        "state": "RUNNING",
        "action": "Waiting for transaction to be included in Bitcoin block",
        "message": ""
    },
    {
        "operationId": "736be6e4",
        "endorsedBlockNumber": 22,
        "state": "RUNNING",
        "action": "Waiting for transaction to be included in Bitcoin block",
        "message": ""
    }
]

GET /api/operations/:id

Gets the details of the specified operation. Same as running getoperation from the command-line. :id is to be substituted with an actual operation ID, e.g. GET /api/operations/797b3b15

Response

{
    "operationId": "ce3c3e8b",
    "status": "RUNNING",
    "currentAction": "WAIT",
    "miningInstruction": {
        "publicationData": [
            ...
        ],
        "endorsedBlockHeader": [
            ...
        ],
        "lastBitcoinBlock": [
            ...
        ],
        "minerAddress": [
            ...
        ],
        "endorsedBlockContextHeaders": [
            [
                ...
            ]
        ]
    },
    "transaction": [
        ...
    ],
    "submittedTransactionId": "2897ba47dfed819879ebe3c5cdbb17e56fcc15d49e3cb42331d2c683b949aeb3",
    "merklePath": "",
    "detail": "",
    "popTransactionId": ""
}

GET /api/lastbitcoinblock

NOTE: Available in latest beta version: SegWit_PoP_Miner

Gets the last known bitcoin block. Same as running showlastbitcoinblock from the command-line.

Response

{
  "header": "0000002005B2B5EF66F47670478DD6462E020E8F9A49BAD1B4C85F6E36C0D675000000007959A7784C5CF4AE38D3EF8ED8E14548FFE3E87A4E39A37AE233001B83B26C854D4E925DFFFF001DA60E33E8",
  "hash": "000000001DD4FAC03E838027EB10FCEB031F14AD0DE943B4F8AB82D0B31F3899",
  "height": 1580114
}

POST /api/quit

NOTE: Available in latest beta version: SegWit_PoP_Miner

Sends a shutdown command to the pop miner. Same as running quit from the command-line.

Since nodecore-pop-0.4.8-dev.24 it's possible to restart the PoP miner by adding the optional restart parameter: "/api/quit?restart=true"

Response

{
  "failed": false,
  "messages": []
}

POST /api/mine

Begins a new mining operation. Same as running mine from the command-line.

Request

Request properties:

Property	Constraint	Data Type	Description
block	Optional	Integer	Represents a specific block number to endorse in this mining operation.

{
    "block": 32040
}

By not specifying a block number the most recent VeriBlock block will be endorsed. An empty JSON object must be sent in the body:

{}

Response

If the miner is able to successfully begin a new operation a 200 OK response will be return with the following body:

{
    "operationId": "c692ed9e",
    "failed": false,
    "messages": [
        {
            "code": "V201",
            "message": "Mining operation started",
            "details": [
                "To view details, run command: getoperation c692ed9e"
            ],
            "error": false
        }
    ]
}

If the miner is unable to begin a 200 OK response will be returned, but will contain the following body:

{
    "failed": true,
    "messages": [
        {
            "code": "V412",
            "message": "Miner is not ready",
            "details": [
                "Waiting for connection to NodeCore",
                "Bitcoin blockchain is not downloaded",
                "Bitcoin service is not ready"
            ],
            "error": true
        }
    ]
}