View source for PoP Miner API 0.4.9

<languages/>

<translate>

<!--T:5-->
See: [[PoP_Miner_CommandLine_0.4.9]]

<!--T:6-->
__TOC__

== Introduction == <!--T:1-->

<!--T:7-->
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 '''application.conf''' 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.

<!--T:8-->
Any requests requiring a message body should be formatted as JSON, and conversely all responses will be formatted as JSON as well.


<!--T:9-->
NOTE: This requires 0.3.12-rc.5 of the PoP Miner CLI or higher.

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

=== Setup the API === <!--T:2-->

<!--T:11-->
# [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
# Start the PoP Miner. See: https://wiki.veriblock.org/index.php?title=HowTo_run_PoP_Miner
# 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 == <!--T:12-->

=== GET /api/config === <!--T:3-->

<!--T:13-->
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 ==== <!--T:4-->

 <!--T:14-->
<pre>
{
    "vpm.api.host": "127.0.0.1",
    "vpm.api.port": "8080",
    "vpm.autoMine.round1": "false",
    "vpm.autoMine.round2": "false",
    "vpm.autoMine.round3": "false",
    "vpm.autoMine.round4": "false",
    "vpm.bitcoin.enableMinRelayFee": "true",
    "vpm.bitcoin.feePerKB": "20000",
    "vpm.bitcoin.maxFee": "8000",
    "vpm.bitcoin.maxPeerConnections": "12",
    "vpm.bitcoin.maxPeersToDiscoverCount": "100",
    "vpm.bitcoin.minPeerBroadcastConnections": "0",
    "vpm.bitcoin.minimalPeerProtocolVersion": "BLOOM_FILTER",
    "vpm.bitcoin.network": "mainnet",
    "vpm.bitcoin.peerDiscoveryTimeoutMillis": "5000",
    "vpm.bitcoin.peerDownloadTxDependencyDepth": "2147483647",
    "vpm.bitcoin.peerPingIntervalMillis": "2000",
    "vpm.bitcoin.requiredPeerServices": "NONE",
    "vpm.bitcoin.useLocalhostPeer": "false",
    "vpm.nodeCoreRpc.host": "127.0.0.1",
    "vpm.nodeCoreRpc.port": "10500",
    "vpm.nodeCoreRpc.ssl": "false"
}
</pre>

=== PUT /api/config === <!--T:15-->

<!--T:16-->
Updates a single configuration value. Same as running '''setconfig''' from the command-line.

==== Request ==== <!--T:17-->

<!--T:18-->
Request properties:

<!--T:19-->
{| class="wikitable"
! style="text-align:left;"| Property
! style="text-align:left;"| Constraint
! style="text-align:left;"| Data Type
! style="text-align:left;"| 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")
|}

 <!--T:20-->
<nowiki>
{
    "key": "auto.mine.round4",
    "value": "true"
}</nowiki>

==== Response ==== <!--T:21-->

<!--T:22-->
A successful request will return a 200 OK status code response with the following body:
 <nowiki>
[
    {}
]</nowiki>

<!--T:23-->
An unsuccessful action will return a 500 Server Error status code with some explanation for the failure in the body:
 <nowiki>
[
    {
        "details": [
            "Property 'pop.action.timeout' requires a positive integer value representing the number of seconds to wait before timing out."
        ]
    }
]</nowiki>

=== GET /api/miner === <!--T:24-->

<!--T:25-->
Lists several miner properties, like the BTC address and amount, and VBK address.

<!--T:26-->
The very first time this is called, if the 'y' acknowledgement hasn't been accepted yet, it will also list the wallet seeds.

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

==== Response ==== <!--T:28-->

<!--T:29-->
<pre>
            {
              "minerAddress": "V9uC3ywS12qW4ESD9783eZXVU3voMo",
              "bitcoinAddress": "1CRb4b5u2AYdaoovgV9aQWV3kSt9x66rJq",
              "bitcoinBalance": 0,
              "walletSeed": [
                "1548958861",
                "cave",
                "conduct",
                "pottery"
              ]
            }
</pre>

=== GET /api/operations === <!--T:30-->

<!--T:31-->
Lists the current running operations. Same as running '''listoperations''' from the command-line.

==== Response ==== <!--T:32-->

<!--T:33-->
<pre>
[
    {
        "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": ""
    }
]
</pre>

=== GET /api/operations/:id === <!--T:34-->

<!--T:35-->
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 ==== <!--T:36-->

 <!--T:37-->
<nowiki>{
    "operationId": "ce3c3e8b",
    "status": "RUNNING",
    "currentAction": "WAIT",
    "miningInstruction": {
        "publicationData": [
            ...
        ],
        "endorsedBlockHeader": [
            ...
        ],
        "lastBitcoinBlock": [
            ...
        ],
        "minerAddress": [
            ...
        ],
        "endorsedBlockContextHeaders": [
            [
                ...
            ]
        ]
    },
    "transaction": [
        ...
    ],
    "submittedTransactionId": "2897ba47dfed819879ebe3c5cdbb17e56fcc15d49e3cb42331d2c683b949aeb3",
    "merklePath": "",
    "detail": "",
    "popTransactionId": ""
}</nowiki>

=== GET /api/lastbitcoinblock === <!--T:38-->

<!--T:39-->
NOTE: Available in latest beta version: [[SegWit_PoP_Miner]]

<!--T:40-->
Gets the last known bitcoin block. Same as running '''showlastbitcoinblock''' from the command-line.

==== Response ==== <!--T:41-->

 <!--T:42-->
<nowiki>{
  "header": "0000002005B2B5EF66F47670478DD6462E020E8F9A49BAD1B4C85F6E36C0D675000000007959A7784C5CF4AE38D3EF8ED8E14548FFE3E87A4E39A37AE233001B83B26C854D4E925DFFFF001DA60E33E8",
  "hash": "000000001DD4FAC03E838027EB10FCEB031F14AD0DE943B4F8AB82D0B31F3899",
  "height": 1580114
}
</nowiki>

=== POST /api/quit === <!--T:43-->

<!--T:44-->
NOTE: Available in latest beta version: [[SegWit_PoP_Miner]]

<!--T:45-->
Sends a shutdown command to the pop miner. Same as running '''quit''' from the command-line.

<!--T:46-->
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 ==== <!--T:47-->

 <!--T:48-->
<nowiki>{
  "failed": false,
  "messages": []
}
</nowiki>

=== POST /api/mine === <!--T:49-->

<!--T:50-->
Begins a new mining operation. Same as running '''mine''' from the command-line.

==== Request ==== <!--T:51-->

<!--T:52-->
Request properties:

<!--T:53-->
{| class="wikitable"
! style="text-align:left;"| Property
! style="text-align:left;"| Constraint
! style="text-align:left;"| Data Type
! style="text-align:left;"| Description
|-
|block
|Optional
|Integer
|Represents a specific block number to endorse in this mining operation.
|}

 <!--T:54-->
<nowiki>
{
    "block": 32040
}</nowiki>

<!--T:55-->
By not specifying a block number the most recent VeriBlock block will be endorsed. An empty JSON object must be sent in the body:

 <!--T:56-->
<nowiki>{}</nowiki>

==== Response ==== <!--T:57-->

<!--T:58-->
If the miner is able to successfully begin a new operation a 200 OK response will be return with the following body:

 <!--T:59-->
<nowiki>{
    "operationId": "c692ed9e",
    "failed": false,
    "messages": [
        {
            "code": "V201",
            "message": "Mining operation started",
            "details": [
                "To view details, run command: getoperation c692ed9e"
            ],
            "error": false
        }
    ]
}</nowiki>

<!--T:60-->
If the miner is unable to begin a 200 OK response will be returned, but will contain the following body:

 <!--T:61-->
<nowiki>{
    "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
        }
    ]
}</nowiki>

</translate>