Skip to content

API

Jump to bottom
Chris Shepherd edited this page Oct 6, 2021 · 2 revisions

HOME | INSTALL | API | POOL CONFIG | SERVER CONFIG | STRATUM

Carrot-Pool's backend REST API (v1) is relatively simple. The base URL for all requests is https://www.example.com/api/v1.

Each of its endpoints was designed to be self-explanatory while still providing users with standardized JSON-formatted responses, making it easy to search, filter and use our data.

The complete URL varies depending on the endpoint of the resource being accessed. For instance, you can view the statistics for each of our supported pools via a GET request to this URL: https://www.example.com/api/v1/statistics.

Each of the following endpoints follows a simple structure, to promote ease of use. The status codes and JSON-formatted responses are standardized throughout. Regarding authentication, we’ve decided not to include any, in order to retain transparency and help our users remain anonymous. The endpoints themselves are also cached for two minutes, and consist of the following:

{
    endpoint: "example",
    errors: "",
    data: [Object],
}

The Endpoint field indicates the current endpoint, while the Errors field highlights any errors that may have arisen during the request. The Data field, on the other hand, contains the user’s requested data. In order to add parameters, append them to the end using the following syntax: /endpoint?parameter=parameter. If you need to add more than one parameter, you can separate them using the & symbol.

📦 Blocks

The Blocks endpoint returns every block found by Carrot-Pool users, separated into the individual pools supported and sorted by block height.

pool=[pool]
worker=[worker]
  • Object (200):
{
    blocks: [
        {
            "pool": "carrotpool",
            "symbol": "BSV",
            "algorithm": "sha-256",
            "time": 1596089323305,
            "height": 1416,
            "blockHash": "ad8832bce1717f2e75da1104d3db929ca7f27cac0d98b325e0b512242d61a68d",
            "blockReward": 50,
            "txHash": "291578aa7b9c7a0f254074b1b52df229fc493077abe9e3ea505c2e755529e648",
            "worker": "M8aXXv5gC2bj7XKnP5mmBgjGg6if6k2QTi",
            "soloMined": false,
            "confirmed": false,
            "confirmations": "1"
        },
        {
            "pool": "carrotpool",
            "symbol": "BTC",
            "algorithm": "sha-256",
            "time": 1596085696521,
            "height": 1415,
            "blockHash": "951c0fbcc035a27da35bb400f056be4030abc77d2d7b855761a17f2fedefddf4",
            "blockReward": 50,
            "txHash": "09d2b74894d6b314ce955a741394cdb1097c20bda94ac1ac5376b236bf4b180d",
            "worker": "M8aXXv5gC2bj7XKnP5mmBgjGg6if6k2QTi",
            "soloMined": false,
            "confirmed": false,
            "confirmations": "2"
        },
        ...
    ],
    statistics: { lastHour: 1, last24Hours: 1, last7Days: 1 }
    ...
}

📜 History

The History endpoint returns all historical data currently stored on Carrot-Pool, separated into the individual pools supported. As this endpoint’s main usage is for charting, each individual point of data is only stored for twelve hours (43200s) before being deleted.

pool=[pool]
  • Object (200):
{
    history: [
        {
            "time": 1596069584,
            "hashrateSolo": 0,
            "hashrateShared": 0,
            "workersSolo": 0,
            "workersShared": 0
        },
        {
            "time": 1596070242,
            "hashrateSolo": 1747.6266666666668,
            "hashrateShared": 1747.6266666666668,
            "workersSolo": 1,
            "workersShared": 1,
        },
        ...
    ]
    ...
}

🧾 Payments

The Payments endpoint displays information on any payments sent out to Carrot-Pool users, sorted by the time that they were sent out.

pool=[pool]
worker=[worker]
  • Object (200):
{
    "payments": [
        {
            "time": 1596105713506,
            "txid": "3a0e1a0383eb464dbe4d44a9c15fe2b714844b27b1fec124f95fae6b7c7d1962",
            "shares": 176,
            "workers": 3,
            "paid": 643.4948,
            "unpaid": {},
            "records": [
                {
                    "height": 1317,
                    "amounts": {
                        "M8aXXv5gC2bj7XKnP5mmBgjGg6if6k2QTi": 49.4996
                    },
                    "shares": {
                        "M8aXXv5gC2bj7XKnP5mmBgjGg6if6k2QTi": 16
                    },
                    "times": {
                        "M8aXXv5gC2bj7XKnP5mmBgjGg6if6k2QTi": 1
                    }
                },
                {
                    "height": 1318,
                    "amounts": {
                        "M8aXXv5gC2bj7XKnP5mmBgjGg6if6k2QTi": 16.49986667,
                        "MRAF5XR5cpdtff7w5R6tymHzBqAjszb3wm": 32.99973333
                    },
                    "shares": {
                        "M8aXXv5gC2bj7XKnP5mmBgjGg6if6k2QTi": 8,
                        "MRAF5XR5cpdtff7w5R6tymHzBqAjszb3wm": 16
                    },
                    "times": {
                        "M8aXXv5gC2bj7XKnP5mmBgjGg6if6k2QTi": 0,
                        "MRAF5XR5cpdtff7w5R6tymHzBqAjszb3wm": 1
                    }
                },
                ...
            ],
            "totals": {
                "amounts": {
                    "M8aXXv5gC2bj7XKnP5mmBgjGg6if6k2QTi": 428.99653334,
                    "MRAF5XR5cpdtff7w5R6tymHzBqAjszb3wm": 164.99866666,
                    "bhtc1qdf3ant3rvw4szsvum4fefu5mr8k83y7nd5g39y": 49.4996
                },
                "shares": {
                    "M8aXXv5gC2bj7XKnP5mmBgjGg6if6k2QTi": 112,
                    "MRAF5XR5cpdtff7w5R6tymHzBqAjszb3wm": 56,
                    "bhtc1qdf3ant3rvw4szsvum4fefu5mr8k83y7nd5g39y": 8
                }
            }
        },
        ...
    ]
    ...
}

📈 Statistics

The Statistics endpoint displays basic information on each of Carrot-Pool’s supported pools, including hashrate, ports, workers, and payments.

pool=[pool]
  • Object (200):
{
    "combined": {
        "pool": "carrotpool",
        "symbol": "BSV",
        "algorithm": "sha-256",
        "featured": true,
        "ports": {
            "3010": {
                "enabled": true,
                "soloMining": false,
                "diff": 8,
                "varDiff": {
                    "minDiff": 8,
                    "maxDiff": 512,
                    "targetTime": 15,
                    "retargetTime": 90,
                    "variancePercent": 30
                }
            },
            "3011": {
                "enabled": true,
                "soloMining": true,
                "diff": 8,
                "varDiff": {
                    "minDiff": 8,
                    "maxDiff": 512,
                    "targetTime": 15,
                    "retargetTime": 90,
                    "variancePercent": 30
                }
            }
        },
        "statistics": {
            "invalidShares": "1",
            "lastPaid": "1596105725196",
            "paymentFees": 1,
            "paymentTime": 7200,
            "paymentMinimum": 0.05,
            "totalPaid": "643.49480000000000002",
            "validShares": "242",
            "validBlocks": "114",
            "blocks": {
                "lastHour": 12,
                "last24Hours": 114,
                "last7Days": 114
            },
            "hashrate": {
                "hashrate": 0,
                "hashrateShared": 0,
                "hashrateSolo": 0
            },
            "workers": {
                "workers": 0,
                "workersShared": 0,
                "workersSolo": 0
            }
        }
    },
    ...
}

🖇 Combined

The Combined endpoint returns a payload of all other API endpoints' return values combined.

pool=[pool]
  • Object (200):
{
    "endpoint": "wallets",
    "wallets": {
        "pool": "",
        "symbol": ,
        "algorithm": ,
        "worker": "",
        "balance": "",
        "immature": "",
        "paid": "",
        "unpaid": "",
        "total": "",
        "blocks": [],
        "payments": [],
        "workers": []
    }
}

🦺 Workers

The Workers endpoint displays information on any of Carrot-Pool’s currently active workers.

pool=[pool]
  • Object (200):
{
    "workers": [
        {
            "address": "bsv1qdf3ant3rvw4szsvum4fefu5mr8k83y7nd5g39y",
            "difficulty": 8,
            "validShares": 8,
            "invalidShares": 0,
            "hashrate": 1747.6266666666668,
            "soloMining": true
        },
        ...
    ],
    ...
}

Clone this wiki locally