SBI Crypto Pool API

SBI Crypto Pool API provides an a RESTful API for users access to subaccount and worker data, payout data, as well as the ability to switch coins or clear inactive workers.

The API also supports numerous options to filter and sort your query. API Keys are created via the UI on the pool website, and are restricted to what subaccounts they can access. Additionally, each API key has a configurable expiration date and has 3 levels of permissions that are configured when the key is created:

  1. READ - Query non-financial information,
  2. FINANCIALS- Query payout-related information from earnings history,
  3. UPDATE - Make changes to settings, such as change coin/blockchain being mined (Ex: Switch from BTC to BCH), clear inactive workers, etc.

The intended consumers of this API are system users seeking to integrate data from the pool to their own systems. This is not intended to drive a user interface.

We care about your security, and our API has undergone a third-party security audit by Silent Breach. Security is also dependent on you. You must keep your API keys and secrets secure. You can revoke API keys and see "creation date", "last used date", "expiration date" and access permissions from the pool user interface.

Table of Contents


General

The base URL for all endpoints is https://pool-api.sbicrypto.com/

Versioning

Releases will follow the semantic versioning standard. This is represented in the URL as /api/external/v1, /api/external/v2, etc. Any major version changes in the release (not backwards compatible) will result in a new version for the affected endpoints.

Media Type

Unless otherwise noted, the media type of application/json must be specified in all requests' Accept header.

Pagination

These APIs support pagination, and sorting on a single named column.

  • page - 0-based requested page number. Specifying a page number greater than the available will return an empty page.
  • size - (optional) user-specified size. Defaults to 20 if not specified.
  • sort - specifies the sort order by field name and order in the format NAME,ORDER where ORDER is either asc or desc. If not specified, the order is asc. If multiple sorts are specified only one (indeterminate) will be used. If the sort is not supported (for example, an invalid or unknown field) then the default sort will be applied. The sort that was actually used will be returned in the response.

GET /api/external/v1/example?size=20&page=100&sort=name,desc

response:

{
    "content": [
        {
            "name": "foo"
        }
    ],
    "first": false,
    "last": true,
    "totalElements": 2001,
    "totalPages": 101,
    "size": 20,
    "number": 100,
    "numberOfElements": 1,
    "sort": {
        "field": "name",
        "ascending": false
    }
}

API Key Access Control

API clients will need to specify their API key in the X-API-Key header, and the API secret in the X-API-Secret header. Any request to the APIs without a valid API key and secret will be rejected with a 401 - Unauthorized response code.

API keys have associated subaccounts and permissions. Failing an access, or a permission check, will result in a 403 - Forbidden response code. Each endpoint is associated with a certain permissions scheme, and there is no inheritance (e.g. having UPDATE permissions on a key doesn't grant access to endpoints that require READ permissions). As one would expect, every time an endpoint is accessed the API Key that was used will have its lastUsed field updated to reflect that time of use.

Important: If you suspect that your API key has been compromised, you should delete that key immediately, and inform us through our support portal.

Account

Get Account Details

This endpoint retrieves a summary of the account associated with the provided key. Each API key has access controls at the subaccount level. Therefore, depending on the access and permissions granted to the key, you may be getting a subset of available information. Only information the API key has access to will be included in the response from this endpoint.

Request

GET /api/external/v1/account

X-API-secret : your secret goes here
X-API-key : your key goes here

Responses

  • 200 and JSON for successful result
  • 401 if X-API-key or X-API-secret is not filled or is not valid
  • 403 if X-API-key & X-API-secret is correct but does not have access to subaccounts associated with the key

sample response:

{
  "name": "anyone@anywhere.com",
  "timezone": "Asia/Tokyo",
  "hashrate": [
    2.9906012588065426E10,
    2.983630843758277E10,
    3.2469555711894417E10
  ],
  "subaccounts": [
    {
      "subaccountId": 15,
      "subaccountName": "batchtest",
      "currentMiningCurrency": {
        "id": 0,
        "code": "BTC",
        "name": "Bitcoin"
      }
    }
  ],
  "workerStatus": {
    "OFFLINE": 0,
    "DEAD": 5482,
    "ONLINE": 2018
  },
  "numOfWorkers": 7500,
  "numOfSubaccounts": 1
}
  • name - account name/email associated with the key
  • timezone - timezone settings of the account
  • hashrate - list of 10m, 1h, 1d hashrate in MH/s
  • subaccount - list of list of subaccounts associated with the key
  • subaccount.subaccountId - unique identifier corresponding to the subaccount
  • subaccount.subaccountName - name associated to the subaccount (also unique)
  • subaccount.currentMiningCurrency - current coin that subaccount is mining
  • workerStatus - number of online, offline, dead/inactive workers
  • numOfWorkers - total number of workers for the subaccounts associated with the key
  • numOfSubaccounts - total number of subaccounts associated with the key

Workers

GET Worker Details

Required permission: READ
This endpoint provides paginated worker details for all workers under the subaccount associated with the observer key passed.

GET /api/external/v1/workers?page={pageNumber}&size={pageSize}&sort={fieldName},{DIRECTION}&nameFilter={partialWorkerName}&statusFilters={STATES}

Accept : application/vnd.sbi.details.worker+json
X-API-secret : your secret goes here
X-API-key : your key goes here

Parameters

  • nameFilter - (optional) string (min=2,max=20) for filtering by worker name
  • statusFilters - (optional) comma delimited list of acceptable statuses in the set ONLINE,OFFLINE,DEAD
  • sort - see Sorting, below
  • page - the specific page number, zero based (default 0)
  • size - the number of records to return in a page (default 20)

sample request

curl --location --request GET 'https://pool-api.sbicrypto.com/api/external/v1/workers?nameFilter=sim&size=10&sort=name,desc&statusFilters=&page=1' \ --header 'x-api-key: <something>' \ --header 'x-api-secret: <something>

sample response

{
    "content": [
        {
            "name": "simulator123-998953873",
            "state": "DEAD",
            "lastShareTime": "2021-02-25T04:23:23.000+00:00",
            "subaccountId": 16,
            "subaccount": "workeraggregatortest",
            "hashrates": [0.0, 0.0, 242707.01116833184]
        },
        ...{
            "name": "simulator123-9989487",
            "state": "DEAD",
            "lastShareTime": "2021-02-25T04:23:26.000+00:00",
            "subaccountId": 16,
            "subaccount": "workeraggregatortest",
            "hashrates": [0.0, 0.0, 241078.10505310816]
        }
    ],
    "first": false,
    "last": true,
    "totalElements": 30579,
    "totalPages": 3058,
    "size": 10,
    "number": 1,
    "numberOfElements": 30579,
    "sort": {
        "field": "name",
        "ascending": false
    }
}

Subaccounts

Update Mined Coin

Required permission: UPDATE
Updates the coin being mined by the subaccount

PATCH /api/external/v1/subaccount

X-API-secret : your secret goes here
X-API-key : your key goes here

Parameters

  • subaccountName - name of the subaccount
  • coin - coin to be mined by subaccount

sample request:

{
    "subaccountName": "batchtest",
    "coin": "BSV"
}

Response Codes

  • 202 and JSON for successful result
  • 400 subaccount is already mining coin; coin is not supported by the pool
  • 401 if X-API-key or X-API-secret is not filled or is not valid
  • 403 if X-API-key & X-API-secret is correct but does not have access to subaccounts associated with the key
  • 404 if subaccount name from filter does not exist for the subaccounts associated with the key
  • 422 if subaccount does not have a configured payout address for the coin

sample response:

{
    "subaccountName": "usonly",
    "coin": "BSV",
    "payoutaddress": "0e3e2357e806b6cdb1f70b54c3a3a17b6714ee1f0e68bebb44a74b1efd512098"
}
  • subaccountName - name of the subaccount
  • coin - coin mined by subaccount
  • payoutAddress - payoutAddress associated to the coin

Earnings

GET Earnings

Required permission: FINANCIALS
Transaction Earnings: This endpoint provides payout information for all subaccounts under the account associated to the api-key

GET /api/external/v1/earnings?fromDate={yyyy-MM-dd}}&toDate={yyyy-MM-dd}}&page={pageNumber}&size={pageSize}

Accept : application/json
X-API-secret : your secret goes here
X-API-Key : your key goes here

Parameters

  • fromDate - inclusive start date of earnings
  • toDate - inclusive end date of earnings
  • page - (optional) paginated number (0 -based) , defaults to 0
  • size - (optional) number of elements per page , defaults to 100

The output contains a map of payout details

Response Codes

  • 200 and JSON for successful result
  • 400 if a required field is not specified, if end date > start date;
  • 401 if user is not authenticated
  • 403 if user is authenticated but does not have sufficient rights (see Access Control)

sample response:

{
    "content": [
        {
            "id": "d74e6d53-b710-4e4d-bad6-87c3046b5d14",
            "coin": {
                "id": 0,
                "code": "BTC",
                "name": "Bitcoin"
            },
            "created": "2021-08-12T03:00:00.256+00:00",
            "asOf": "2021-08-12T00:00:00.000+00:00",
            "subaccount": {
                "id": 42,
                "name": "usonly",
                "account": {
                    "id": 3,
                    "name": "anyone@anywhere.com",
                    "timeZone": "Asia/Tokyo",
                    "status": "ACTIVE",
                    "properties": {
                        "PAYMENTS": "{\"BSV\":8500296426}",
                        "PPS_SYSTEM_FEE": "0.0"
                    }
                },
                "miningCurrency": {
                    "id": 0,
                    "code": "BTC",
                    "name": "Bitcoin"
                },
                "withdrawAddress": {
                    "id": 63,
                    "address": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
                    "coin": {
                        "id": 0,
                        "code": "BTC",
                        "name": "Bitcoin"
                    }
                },
                "payoutAddresses": [
                    {
                        "id": 63,
                        "address": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
                        "coin": {
                            "id": 0,
                            "code": "BTC",
                            "name": "Bitcoin"
                        }
                    }
                ],
                "properties": {
                    "INACTIVE_WORKER_MARKER": "1626642145679"
                }
            },
            "payoutaddress": "0e3e2357e806b6cdb1f70b54c3a3a17b6714ee1f0e68bebb44a74b1efd512098",
            "paymentMethod": "FPPS",
            "amount": 30923398477,
            "feesPaid": -606341120,
            "systemFeePercentage": -2.0,
            "transactionId": null,
            "status": null,
            "blockchainId": null
        }
    ],
    "first": true,
    "last": false,
    "totalElements": 17,
    "totalPages": 17,
    "size": 1,
    "number": 0,
    "numberOfElements": 17,
    "sort": {
        "field": "created",
        "ascending": false
    }
}

Get Payout Information

Required permission: FINANCIALS
Payout Information: This endpoint provides payout information for all subaccounts under the account associated to the api-key

GET /api/external/v1/earnings?fromDate={yyyy-MM-dd}}&toDate={yyyy-MM-dd}}&page={pageNumber}&size={pageSize}

X-API-secret : your secret goes here
X-API-key : your key goes here

Parameters

  • fromDate - inclusive start date (UTC) of earnings
  • toDate - inclusive end date (UTC) of earnings
  • page - paginated number (0 -based) , defaults to 0
  • size - number of elements per page , defaults to 100

The output contains a map of payout details

Response Codes

  • 200 and JSON for successful result
  • 400 if any required field is not specified; if end date > start date;
  • 401 if X-API-key or X-API-secret is not filled or is not valid
  • 403 if X-API-key & X-API-secret is correct but does not have access to subaccounts associated with the key
  • 404 if subaccount name from filter does not exist for the subaccounts associated with the key

sample response:

{
  "content": [
    {
      "id": "c8cc4bc2-bce2-478b-8fac-e997a14a4f27",
      "coin": {
        "id": 236,
        "code": "BSV",
        "name": "Bitcoin SV"
      },
      "created": "2021-09-14T05:00:00.277+00:00",
      "asOf": "2021-09-14T00:00:00.000+00:00",
      "subaccountName": "usonly",
      "subaccountId": 42,
      "payoutaddress": "0e3e2357e806b6cdb1f70b54c3a3a17b6714ee1f0e68bebb44a74b1efd512098",
      "paymentMethod": "FPPS",
      "amount": 1208,
      "feesPaid": 0,
      "systemFeePercentage": 0.0,
      "transactionId": "e8182992-66ed-4179-8963-99519217d577",
      "status": "CONFIRMED",
      "blockchainId": "12adf27a55a41aa65d4b1042f6325e4baee7df3a29c3adbd8acc9f0001dd5af6"
    }
  ],
  "first": true,
  "last": true,
  "totalElements": 8,
  "totalPages": 8,
  "size": 1,
  "number": 0,
  "numberOfElements": 8,
  "sort": {
    "field": "created",
    "ascending": false
  }
}
  • content - list of payouts
  • content[i].id - pool's unique earning identifier
  • content[i].created - date time when payout was calculated
  • content[i].asOf - 24hr sharelogs as of this date time are considered in the calculation
  • content[i].subaccountId - subaccountId that worker belongs to
  • content[i].subaccountName - subaccount name that worker belongs to
  • content[i].payoutAddress - address where payout has been sent
  • content[i].paymentMethod - method of calculation used to compute the amount in payout
  • content[i].amount - amount paid out to address
  • content[i].feesPaid - amount paid to the pool as a fee
  • content[i].systemFeePercentage - percentage of the earnings that are accounted as a fee
  • content[i].transactionId - pool's unique payout identifier
  • content[i].status - status of the payout
    • NEW - payout is still pending to be sent
    • POSTED - payout has been sent but awaiting confirmation(s) in the blockchain
    • CONFIRMED - payout has been sent and confirmed
    • FAILED - payout was not sent successfully
  • first - true if the listed contents are of the first page (0-based index), false if otherwise
  • last - true if the listed contents are of the last page (0-based index), false if otherwise
  • totalElements - total number of workers/contents that matches the search criteria
  • totalPages - total number of pages given the (content) size requested
  • size - number of contents per page
  • number - current page number
  • numberOfElements - number of elements in this page
  • sort - order of sorting of listed contents

Inactive Workers

Clear Inactive Workers

Required permission: UPDATE
Removes all inactive workers associated to the subaccount

POST /api/external/v1/clear-inactive-workers?subaccountName=<required>

X-API-secret : your secret goes here
X-API-key : your key goes here

Parameters

  • subaccountName - name of the subaccount

Response Codes

  • 204 no content for successful result
  • 400 subaccountName parameter is not populated
  • 401 if X-API-key or X-API-secret is not filled or is not valid
  • 403 if X-API-key & X-API-secret is correct but does not have access to subaccounts associated with the key
  • 404 if subaccount name from filter does not exist for the subaccounts associated with the key