SBI Crypto logo

SBI Crypto Pool API

SBI Crypto Pool API provides a RESTful API for users to access public data through Public API and account data through Key Access Controlled API.

The public API gives access to information on pool statistics such as 7 days and 30 days luck, found blocks, and payout history.

Key Access Controlled API gives access to subaccount and worker data, payout data, as well as the ability to switch coins, clear inactive workers. This 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

Base URL

The base URL for all requests is https://pool-api.sbicrypto.com, except where explicitly stated otherwise.

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

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

Public API

Public Hashrate API

This API will return pool hashrate per coin per day for current day-1 with a timestamp. No Authentication needed.

GET /api/external/v1/public/hashrates?resolution={resolution}&coins={coins}

Parameters:

  • resolution - defines the number of lookup days for hashrate.
  • coins - filters the results to only include the coin(s) in a comma separated list. This field is optional and will default to all coins if not given

The output contains a map of equal sized lists, the size of which is determined by either the number of specified ranges, or the length of the specified range in minutes, divided by the interval in minutes. It also contains the computed value of “now” as determined by the server represented in UTC based JSON format. The output hashrate will be in MH/s.

sample response

{
   "now": "2019-12-03T15:52:31.673Z",
   "hashrate": {
      "BTC": [
         91.3,
         21.7,
         30.5,
         45.1,
         61.8,
         40.1,
         72.4
      ],
      "BCH": [
         23.7,
         42,
         57.1,
         45.1,
         61.8,
         40.1,
         21.5
      ],
   }
}

Coin API

List all the coins in the system.

GET /api/external/v1/public/coins

response:

[
  {
    "code": "BCH",
    "name": "bitcoin cash",
    "chain": "bitcoin",
    "algo": "sha256"
  },
  {
    "code": "BTC",
    "name": "bitcoin",
    "chain": "bitcoin",
    "algo": "sha256"
  },
  {
    "code": "ETHW",
    "name": "eth PoW",
    "chain": "ethereum",
    "algo": "ethhash"
  }
]

Pool Foundblock API

Lists the past 20 blocks mined by the pool.

GET /api/external/v1/public/poolstats/blocks/{coinCode}

response:

[
    {
        "dateMined": "2023-01-22T20:16:46.000+00:00",
        "blockNumber": 776572,
        "blockHash": "00000000000000000013bcaf65c5ae9ba9260f026e71850793b97bb78266cf1d",
        "reward": 6.2507198
    },
    {
        "dateMined": "2023-01-22T18:25:37.000+00:00",
        "blockNumber": 776563,
        "blockHash": "0000000000000000021bcb3f29665b474ee68bdda6240980a845789a49fd7450",
        "reward": 6.25279884
    }
]

Exchange Rate API

Get the latest exchange rate to USD($) per coin.

GET /api/external/v1/public/exchangerate

Parameters:

  • coins - filters the results to only include the coin(s) in a comma separated list. This field is optional and will default to all coins if not given.

response:

[
  {
    "timestamp": "2019-12-03T15:52:31.673Z",
    "currencyCode": "BTC",
    "exchangeRate": "17000"
  },
  {
    "timestamp": "2019-12-03T15:52:31.673Z",
    "currencyCode": "BCH",
    "exchangeRate": "60"
  },
  {
    "timestamp": "2019-12-03T15:52:31.673Z",
    "currencyCode": "ETHW",
    "exchangeRate": "1000"
  },
  {
    "timestamp": "2019-12-03T15:52:31.673Z",
    "currencyCode": "LTC",
    "exchangeRate": "60"
  }
]

Public Payouts API

This API will return pool payouts, given in whole coins, starting from {date}-1 day per coin with timestamp. No Authentication needed.

GET /api/external/v1/public/poolstats/payout?range={range}&date={date}&coins={coins}

Parameters:

  • range - specifies range. This is in days and must be integer (i.e 30, 20 or 10).
  • date - specifies the date(YYYY-mm-dd) where it will start the payout query in relation with range. This field is optional and will default to current date if not given.
  • coins - filters the results to only include the coin(s) in a comma separated list. This field is optional and will default to all coins if not given.

The output contains a map of equal sized lists per range.

sample response

{
   "now": "2019-12-03T15:52:31.673Z",
   "payout": {
      "BTC": [
         91.3,
         21.7,
         30.5,
         45.1,
         61.8,
         40.1,
         72.4
      ],
      "BCH": [
         23.7,
         42,
         57.1,
         45.1,
         61.8,
         40.1,
         21.5
      ]
   }
}

Payout Rate API

Retrieves the payout rate (coin per hashrate) for lookup {days}

GET /api/external/v1/public/poolstats/rate?days={days}&coins={coins}

Parameters:

  • coins - filters the results to only include the coin(s) in a comma separated list. This field is optional and will default to all coins if not given
  • days - refers to the lookup days for payout and hashrate. Note that upper boundary date starts with {current date}-1day

response:

{
  "BTC": {
    "date": "2023-01-26T00:00:00.620+00:00",
    "denomination": "TH", 
    "rate": [
      5.968,
      8.883,
      4.491
    ]
  }
}

Historical Luck API

Retrieves the historical luck of coin for the last 7 and 30 days in whole value percentage.

GET /api/external/v1/public/poolstats/luck/{coinCode}

Parameters:

  • coinCode - refers to coin code (i.e BTC, BCH, ETHW, LTC etc.)
  • days - (Optional) refers to the Luck days concatenated by comma to be retrieved relative to the response (i.e 7,15,30,25 - Limited to 10 day parameter). If days parameter is not supplied, this will be defaulted to 7 and 30 days.

response:

{
  "coin": "BTC",
  "7d": "70.0",
  "30d": "70.0"
}

Other Pool Stats API

A legacy endpoint can be found at https://stats.sbicrypto.com/poolstats that 15~30 minute delayed stats for 24h average hashrate, stale share percent, reject share percent.

response

{
"btc_24h_hashrate_th": 2580725, "bch_24h_hashrate_th": 20225, "ethw_24h_hashrate_mh": 3378, "btc_24h_reject_percent":
0.009800306632223777, "bch_24h_reject_percent": 0.00657668566164248, "btc_24h_stale_percent": 0.13315705941280784,
"bch_24h_stale_percent": 0.0613681371891411, "updated_last_at": 1675324808
}

Authenticated API

Requests documentation in this section are required to be authenticated with an API key.

API Key Access Control

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

Each API Key is associated with a list of permissions and list of subaccounts. User can only view subaccounts that are associated with the key. Permissions are associated with the 3 types of external API endpoints which are: READ, FINANCIALS, UPDATES. The API Key can only access the type of endpoint if they have the permission for that type of endpoint.

Whenever an external endpoint is accessed, the API Key's last used field gets updated. Subsequently, a call to the analytics service is made.

External Read APIs

To access the APIs under this section, the API Key must have the READ permission. All APIs under READ are GET methods.

Get Account Details

Get Account Details: This endpoint retrieves the summary of account information. Because each API key is controlled at a subaccount level, it is possible that the results of this endpoint will vary depending on the API Key. Only the information associated with the APIkey's subaccount will be included when calculating for the response.

Request

GET /api/external/v1/account

x-api-secret : aWZXNoK04YUUXy6m6uB5LaCwM3BsL_1S
x-api-key : 5adbf1b4-1ff8-4149-af3c-7cdcd06b8cb3

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": "accountemail@domain.com",
  "timezone": "Asia/Tokyo",
  "hashrate": [
    2.9906012588065426E10,
    2.983630843758277E10,
    3.2469555711894417E10
  ],
  "subaccounts": [
    {
      "subaccountId": 15,
      "subaccountName": "batchtest",
      "currentMiningCurrency": {
        "id": 0,
        "code": "BTC",
        "name": "bitcoin",
        "chain": "BITCOIN",
        "algo": "sha256"
      }
    }
  ],
  "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

Get Subaccount Details

Get Subccount Details: This endpoint retrieves the summary of subaccount information. Because each API key is controlled at a subaccount level, it is possible that the results of this endpoint will vary depending on the API Key. Only the information associated with the APIkey's subaccount will be included when calculating for the response. We can further filter by passing subaccountNames as a parameter.

Request

GET /api/external/v1/subaccounts?subaccountNames=(optional)

x-api-secret : aWZXNoK04YUUXy6m6uB5LaCwM3BsL_1S
x-api-key : 5adbf1b4-1ff8-4149-af3c-7cdcd06b8cb3

  • subaccountNames - optional comma-separated list of subaccountNames that are used to filter out the response (case sensitive)
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
  • 404 if subaccount name from filter does not exist for the subaccounts associated with the key

sample response:

{
  "accountName": "accountemail@domain.com",
  "subaccounts": [
    {
      "subaccountId": 6,
      "subaccountName": "bchtestpayout",
      "currentMiningCurrency": {
        "id": 145,
        "code": "BCH",
        "name": "bitcoin cash"
      },
      "payoutAddress": "bchtest:qr4tnlf3ujkgup2y8unrcw86wrq2zxgh3srtxnc7em",
      "observerLink": "https://mothership-web.tokyo.dev.sbicrypto.com/observers?linkId=bPiWoElruIgd4ooyEGHfMxQotdBzsaOE",
      "hashrate": [
        0.0,
        0.0,
        0.0
      ],
      "workerStatus": {
        "offline": 0,
        "online": 0,
        "dead": 0
      },
      "totalWorkers": 0
    },
    {
      "subaccountId": 15,
      "subaccountName": "batchtest",
      "currentMiningCurrency": {
        "id": 0,
        "code": "BTC",
        "name": "bitcoin"
      },
      "payoutAddress": "mtRg7KvvNKhotPwnAXez6r7svULaWBKdX2",
      "observerLink": null,
      "hashrate": [
        2.991328402496378E10,
        2.9875754028069027E10,
        3.284425787229767E10
      ],
      "workerStatus": {
        "offline": 0,
        "online": 2018,
        "dead": 5482
      },
      "totalWorkers": 7500
    }
  ]
}
  • accountName - account name/email associated with the key
  • subaccounts - list of list of subaccounts associated with the key and filtered by subaccountNames parameter
  • subaccounts[i].observerLink - subaccount's observer link (if existing)
  • subaccounts[i].hashrate - subaccount's list of 10m, 1h, 1d hashrate in MH/s
  • subaccounts[i].subaccountId - unique identifier corresponding to the subaccount
  • subaccounts[i].subaccountName - name associated to the subaccount (also unique)
  • subaccounts[i].currentMiningCurrency - current coin that subaccount is mining
  • subaccounts[i].workerStatus - number of online, offline, dead/inactive workers for the given subaccount
  • subaccounts[i].numOfWorkers - total number of workers for the given subaccount
  • subaccounts[i].payoutAddress - subaccount's payout address where rewards will be sent

Get Worker Details

Get Worker Details: This endpoint retrieves the summary of worker information. Worker information can be filtered by status (ONLINE,OFFLINE,DEAD), worker name or subaccount. The subaccount must be belonging to the API Key's list of subaccounts.

Request

GET /api/external/v1/workers?subaccountNames=(optional)&statusFilters=(optional)&size=(optional) &workerName=(optional)&pageNumber=(optional)

x-api-secret : aWZXNoK04YUUXy6m6uB5LaCwM3BsL_1S
x-api-key : 5adbf1b4-1ff8-4149-af3c-7cdcd06b8cb3

  • subaccountNames - optional comma-separated list of subaccountNames that are used to filter out the response
  • statusFilters - optional comma-separated list of status filters [ONLINE,OFFLINE,DEAD]
  • workerName - worker names are filtered to the value that contains or is equal this string
  • pageNumber - 0-based indexed page of the result
  • size - number of contents per page
Responses
  • 200 and JSON for successful result
  • 400 if statusFilter is not of value [ONLINE,OFFLINE or DEAD], pageNumber is String, etc.
  • 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": [
    {
      "name": "simulator123-1003397789",
      "state": "ONLINE",
      "lastShareTime": "2021-09-17T10:04:49.000+00:00",
      "subaccountId": 15,
      "subaccount": "batchtest",
      "hashrates": [
        1.3839186354940586E7,
        1.3487342634052267E7,
        2378202.9282266074
      ]
    }
  ],
  "first": true,
  "last": true,
  "totalElements": 1,
  "totalPages": 1,
  "size": 20,
  "number": 0,
  "numberOfElements": 1,
  "sort": {
    "field": "name",
    "ascending": true
  }
}
  • content - list of worker information
  • content[i].name - worker name
  • content[i].state - ONLINE,OFFLINE or DEAD. Status depends on last sharelog time pool has received from the worker.
    • ONLINE - last sharelog received from miner is within last 2mins;
    • OFFLINE - last sharelog received from miner is after 2mins but is within last 10mins;
    • DEAD - last sharelog received is after 10mins;
  • content[i].lastShareTime - date time last sharelog was received from miner
  • content[i].subaccountId - subaccountId that worker belongs to
  • content[i].subaccount - subaccount name that worker belongs to
  • content[i].hashrate - worker's list of 10m, 1h, 1d hashrate in MH/s
  • 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

Get Subpool Details

Get Subpool Details: This endpoint retrieves the stratum server details for each subpool available

Request

GET /api/external/v1/subpools

x-api-secret : aWZXNoK04YUUXy6m6uB5LaCwM3BsL_1S
x-api-key : 5adbf1b4-1ff8-4149-af3c-7cdcd06b8cb3

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
  • 404 if subaccount name from filter does not exist for the subaccounts associated with the key

sample response:

[
  {
    "name": "US Subpool",
    "coins": [
      "BTC",
      "BCH",
      "LTC"
    ],
    "stratumServers": [
      {
        "id": 2,
        "host": "us1.sbicrypto.com",
        "port": 3333
      },
      {
        "id": 5,
        "host": "eth.us1.sbicrypto.com",
        "port": 3333
      }
    ],
    "region": 2
  }
]
  • content - list of subpool details
  • content[i].name - subpool name
  • content[i].coins - provides all coins supported by the subpool
  • content[i].stratumServers - list of stratum servers details available for the subpool
  • content[i].stratumServers[j].id - stratum server's id
  • content[i].stratumServers[j].host - host of the stratum server for this subpool
  • content[i].stratumServers[j].port - port of the stratum server for this subpool

Note: Worker connection is defined as stratum+tcp://<host>:<port>

External Financial APIs

To access the APIs under this section, the API Key must have the FINANCIALS permission. All APIs under FINANCIALS are GET methods.

Get Payout Information

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 : aWZXNoK04YUUXy6m6uB5LaCwM3BsL_1S
x-api-key : 5adbf1b4-1ff8-4149-af3c-7cdcd06b8cb3

Parameters
  • fromDate - (required) inclusive start date (UTC) of earnings
  • toDate - (required) 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

Responses
  • 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": "bitcoinsv"
      },
      "created": "2021-09-14T05:00:00.277+00:00",
      "asOf": "2021-09-14T00:00:00.000+00:00",
      "subaccountName": "usonly",
      "subaccountId": 42,
      "payoutAddress": "mkxSFCsiPyLYej1jxsyXHBj3L91Ze8qdk2",
      "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

Get Earning Payments

Earning Payments: This endpoint provides earning and payout information for all subaccounts under the account associated to the api-key. Earnings are generated per UTC day. Pool payouts are generally per day, however depending on the pool or user's threshold value, the earning's payment may be withheld until the accumulated earning amount reaches the threshold.

GET /api/external/v2/earnings?endDate=${yyyy-MM-dd endDate}&page=0&size=10&startDate=${yyyy-MM-dd startDate}

  • Accept : application/json
Parameters
  • vSubaccounts - (optional) filters the results to only include the virtual subaccount(s) in a comma separated list. Invalid virtual subaccount ids will be ignored
  • startDate - (optional) start date (inclusive) in the account's locale formatted as yyyy-MM-dd; if not given, will default to first day of current month
  • endDate - (optional) end date (inclusive) in the account's locale formatted as yyyy-MM-dd; if not given, will default to last day of current month
  • filter - (optional) filter the resultset to only rows where either the coin, blockchainhash/transactionId OR the address contains the filter string
  • page - required (see paging and sorting below)
  • size - required (see paging and sorting below)
Paging and Sorting

The results may be sorted by specifying a sort field which may be one of the json keys found in the content response.

and (optionally) a comma-delimited direction of either asc or desc. If direction is not specified then the default order is descending. If field is not specified it will default to earningsFor desc.

State will be ordered as it is declared ASC={CONFIRMED, PENDING, POSTED, NEW}. In cases where a sort field has duplicates the secondary sort field will be earningsFor,DESC.

Note on states:

  • PENDING means that transaction-earning link has not been created.
  • NEW means that transaction-earning link has been created but payment request has not been sent to payment processor or that response from pp is not yet received.
  • POSTED means that payment has been posted, is in the mem-pool and/or waiting for confirmation from at least 6 nodes.
  • CONFIRMED means that payment has been confirmed by at least 6 nodes and tx is in the blockchain.
Filtering

If a filter of more than 2 characters is specified then the results will be filtered to include only rows where either the amount, transactionId or the address contains the filter. Leading and trailing whitespace characters are ignored.

Access Control

This is restricted to either account users, or users with the ROLE_ACCOUNT_READER permission.

Responses
  • 200 and JSON for successful result

  • 400 and a terse message if the startDate parameter is invalid

  • 400 and a terse message if the endDate parameter is invalid

  • 400 and a terse message if the startDate is after the endDate

  • 422 and a terse message if the sort parameter is invalid

  • 401 if user is not authenticated

  • 403 if user is authenticated but does not have sufficient rights (see Access Control)

GET /api/external/v2/earnings?endDate=2022-04-12&page=0&size=10&startDate=2021-03-25&filter=
Accept: application/json

response:

{
  "content": [
    {
      "earningsId": "994238cd-238d-4409-9141-78fb09cbf58c", // uuid
      "subaccountId": 3, // integer/long
      "subaccountName": "agentbsv", // string
      "vSubaccountId": 1, // only populated if subaccountId is of collector type
      "vSubaccountName": "vsub1", // only populated if subaccountId is of collector type
      "earningsFor": "2022-03-23T00:00:00.000+00:00", //date
      "earningScheme": "FPPS", // String - PPLNS,FPPS
      "coin": "BTC", // String - BTC,BSV,BCH,ETH
      "address": "mtRg7KvvNKhotPwnAXez6r7svULaWBKdX2", // String
      "hashrate": 5548393.040923901, // Double;hashrate in MH/s
      "grossOwed": 12.99937, // Double - (whole coin)
      "fee": 5.0, // Float (-5,100)
      "feesPaid": 12.34940, // Double - (whole coin)
      "netOwed": 0.64997, // Double - (whole coin)
      "state": "CONFIRMED", // String - CONFIRMED, PENDING, POSTED, NEW
      "txId": "000a3bee2f764cfe2da91c721584f3259dc9f4c82d627f6d26c4d5c7415a0dbe", // String; may be nullable
      "internalTxId": "00000000-0000-0000-0000-000000000001", //UUID; may be nullable
      "paidOn": "2022-03-23T20:30:04.107+00:00", // Date; may be nullable
      "generatedAmount": 6.25 // not shown if non-admin, amount generated by subaccount for coin for the given mined date in whole coin unit
    }
  ],
  "first": true,
  "last": true,
  "totalElements": 1,
  "totalPages": 1,
  "size": 10,
  "number": 0,
  "numberOfElements": 1,
  "sort": {
    "field": "earningsId", // default sort
    "ascending": false // default order
  }
}

Get Estimated Revenues

Payout Information: This endpoint provides yesterday's and today's estimated revenues ONLY for all subaccounts under the account associated to the api-key

GET _/api/external/v1/revenue?subaccountNames={subaccountNames}

x-api-secret : aWZXNoK04YUUXy6m6uB5LaCwM3BsL_1S
x-api-key : 5adbf1b4-1ff8-4149-af3c-7cdcd06b8cb3

Parameters
  • subaccountNames - (optional) additional filtering for specific subaccounts

The output contains a map of revenue

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
  • 404 if subaccount name from filter does not exist for the subaccounts associated with the key

sample response:

{
  "estimatedRevenues": {
    "2022-01-20T00:00:00.000+00:00": [
      {
        "subaccountName": "eth1",
        "coin": "ETH",
        "amount": 81470.53078003156
      }
    ],
    "2022-01-19T00:00:00.000+00:00": [
      {
        "subaccountName": "eth1",
        "coin": "ETH",
        "amount": 301979.40471687075
      }
    ]
  }
}
  • content - list of payouts
  • content[i].[utc_date] - list of revenue for this given date. There will always be 2 dates (yesterday's or today's utc day)
  • content[i].[utc_date][i].subaccountName - subaccount name with the revenue
  • content[i].[utc_date][i].coin - coin associated to the date of earning. Also represents unit of amount
  • content[i].[utc_date][i].amount - value of the estimated revenue

Retrieve Tx Payouts

This endpoint is only accessible for admins or for owner of the account

GET /api/external/v1/payouts?endDate=${yyyy-MM-dd}&page=0&size=10&startDate=${yyyy-MM-dd}&coinFilters=${comma separated coin codes}&vSubaccountIds=${comma separated virtual subaccount ids}

  • Accept : application/json

x-api-secret : aWZXNoK04YUUXy6m6uB5LaCwM3BsL_1S
x-api-key : 5adbf1b4-1ff8-4149-af3c-7cdcd06b8cb3

Parameters
  • coinFilters - (optional) filters the results to only include specific coins.

  • startDate - (optional) start date (inclusive) in the account's locale formatted as yyyy-MM-dd; if not given, will default to first day of current month

  • endDate - (optional) end date (inclusive) in the account's locale formatted as yyyy-MM-dd; if not given, will default to last day of current month

  • filter - (optional) filter the resultset to only rows where either the txId OR the address contains the filter string

  • vSubaccountIds - (optional) filter the resultset to only rows where the virtual subaccount id is in the list

Paging and Sorting

The results may be sorted by specifying a sort field which may be one of the json keys found in the content response.

and (optionally) a comma-delimited direction of either asc or desc. If direction is not specified then the default order is ascending. If field is not specified it will default to paidOn desc.

State will be ordered as it is declared ASC={CONFIRMED, POSTED, NEW}. In cases where a sort field has duplicates the secondary sort field will be paidOn,DESC.

Note on states:

  • NEW means that transaction-earning link has been created but payment request has not been sent to payment processor or that response from pp is not yet received.
  • POSTED means that payment has been posted, is in the mem-pool and/or waiting for confirmation from at least 6 nodes.
  • CONFIRMED means that payment has been confirmed by at least 6 nodes and tx is in the blockchain.
Filtering

If a filter of more than 2 characters is specified then the results will be filtered to include only rows where either the txId or the address or the amount contains the filter. Leading and trailing whitespace characters are ignored.

Access Control

This is restricted to either account users, or users with the ROLE_ACCOUNT_READER permission.

Responses
  • 200 and JSON for successful result

  • 400 and a terse message if the startDate parameter is invalid

  • 400 and a terse message if the endDate parameter is invalid

  • 400 and a terse message if the startDate is after the endDate

  • 400 and a terse message if the coinFilters is after the endDate

  • 422 and a terse message if the sort parameter is invalid

  • 401 if user is not authenticated

  • 403 if user is authenticated but does not have sufficient rights (see Access Control)

GET /api/internal/v1/payouts?endDate=2022-04-12&page=0&size=10&startDate=2021-03-25&filter=
Accept: application/json

response:

{
  "content": [
    {
      "internalTxId": "c80ea9c5-0aca-4c5c-adb9-329f89928552", // uuid
      "coin": "BTC",  // String - BTC,BSV,BCH,ETH
      "amount": 7.1236821638612E13, // Double, value in whole coin
      "txFee": 82371.0, // Double, value in whole coin
      "state": "CONFIRMED", // String - CONFIRMED, POSTED, NEW
      "txId": "5fc6928835913f8b96a7b5ace25a296ad642e72150ce1368eb06eebce2133b98", // String - may be nullable
      "paidOn": "2022-04-15T02:30:00.000+00:00"  // Date 
      "details": [
        {
          "amount": 7.1236821638612E13, // Double - value in whole coin
          "subaccount": "stg-test-4", // String - Subaccount name 
          "address": "bc1qm0r99me8s6zuscskfgm9a7x8hc27kjjtxea838", // String - address 
          "vsubaccountName": "vsub1" // String; may be nullable - Virtual subaccount name;
        }
      ]
    }
  ],
  "first": true,
  "last": true,
  "totalElements": 1,
  "totalPages": 1,
  "size": 10,
  "number": 0,
  "numberOfElements": 1,
  "sort": {
    "field": "paidOn", // default sort
    "ascending": false // default order
  }
}

External Update APIs

To access the APIs under this section, the API Key must have the UPDATE permission. All APIs under FINANCIALS are post or patch methods.

Create Normal Subaccount

Create Normal Subaccount: creates a subaccount via the external api.

POST _/api/external/v1/subaccount

x-api-secret : aWZXNoK04YUUXy6m6uB5LaCwM3BsL_1S
x-api-key : 5adbf1b4-1ff8-4149-af3c-7cdcd06b8cb3

Request

sample request:

{
  "name": "normal-sub-1",
  "miningCurrency": "BTC",
  "withdrawAddress": "34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo",
  "type": 1
}

  • name - (required) name of the subaccount; must be a unique name throughout the whole pool; can only contain alphanumeric characters, dash, underscore.
  • miningCurrency - (required) coin to be mined by subaccount; must be a coin supported by the pool; switch coin is not allowed for collector subaccounts
  • withdrawAddress - (required) should be a valid withdraw/payout address for the given mining currency; this will be the overflow subaccount's withdraw address
  • type - (required) type=1 means that this is a NORMAL subaccount.
Responses
  • 201 collector subaccount is successfully created. The newly created subaccount is added to the subaccount list that the x-api-key can access
  • 400 if there is a missing required value in the request if name contains an invalid character or reaches greater than 35 characters
  • 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
  • 409 if the subaccount name is already existing in the system.
  • 422 if coin is not supported if withdrawAddress is not a valid address for the given coin

sample response:

{
  "id": 673,
  "name": "normal-sub-1",
  "miningCurrency": "BTC",
  "withdrawAddress": "34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo",
  "type": 1,
  "paymentMethod": "FPPS",
  "pendingPayouts": null,
  "schemeFee": {
    "id": 673,
    "name": "normal-sub-1",
    "fees": [
      {
        "coin": "BTC",
        "chain": "BITCOIN",
        "scheme": "PPLNS",
        "rate": 0.75,
        "isInherited": true
      },
      {
        "coin": "BTC",
        "chain": "BITCOIN",
        "scheme": "FPPS",
        "rate": 1.5,
        "isInherited": true
      },
      {
        "coin": "BCH",
        "chain": "BITCOIN",
        "scheme": "PPLNS",
        "rate": 0.75,
        "isInherited": true
      },
      {
        "coin": "BCH",
        "chain": "BITCOIN",
        "scheme": "FPPS",
        "rate": 1.5,
        "isInherited": true
      }
    ],
    "current": {
      "coin": "BTC",
      "chain": "BITCOIN",
      "scheme": "FPPS",
      "rate": 1.5,
      "isInherited": false
    },
    "pending": null
  },
  "virtualSubaccounts": null
}
  • id - unique id given to the collector; often referred to as the subaccount
  • name - the name of the subaccount
  • miningCurrency - coin to be mined by subaccount
  • type type of subaccount; 1= NORMAL Subaccount
  • schemeFee.coin - coin of the current scheme-fee
  • schemeFee.chain - coin chain of the current scheme-fee
  • schemeFee.scheme - earning scheme applied to the subaccount
  • schemeFee.rate - fee rate deducted from the earnings of the subaccount/virtual subaccount as pool fee
  • schemeFee.isInherited - true means that the current scheme fee has been overridden at an account or subaccount level
  • false means that the current scheme fee is inherited from the default system set fee/scheme

Update Payout Address

Update Payout Address: Sends a request to change the payout address of the subaccount. Changes to your payout information will go through an additional user verification process. Upon approval, the system will take 24 hours to update, during which your payout will continue to be sent to your current address. Submitting a new request will override any previous requests.

PATCH _/api/external/v1/subaccount/address

x-api-secret : aWZXNoK04YUUXy6m6uB5LaCwM3BsL_1S
x-api-key : 5adbf1b4-1ff8-4149-af3c-7cdcd06b8cb3

Request

sample request:

{
  "coin": "BTC",
  "name": "1450-test-api-10",
  "address": "tb1qpc5fcnrqxzhu8lh53w2t7n4a7ksjueafmvj7px"
}
  • name - (required) name of the subaccount
  • coin - coin mined by subaccount
  • address - new address for subaccount
Responses
  • 202 if change has been accepted
  • 400 target 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

sample response:

{
    "id": 122,
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "coin": "BTC"
}

Update Mining Coin

Update Mining Coin: Updates the coin being mined by the subaccount

PATCH _/api/external/v1/subaccount

x-api-secret : aWZXNoK04YUUXy6m6uB5LaCwM3BsL_1S
x-api-key : 5adbf1b4-1ff8-4149-af3c-7cdcd06b8cb3

Request

sample request:

{
    "subaccountName": "batchtest",
    "coin": "BCH"
}
  • subaccountName - (required) name of the subaccount

  • coin - coin to be mined by subaccount

Responses
  • 200 subaccount is already mining coin;
  • 202 and JSON for successful result
  • 400 target 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": "BCH",
  "payoutAddress": "mkxSFCsiPyLYej1jxsyXHBj3L91Ze8qdk2"
}
  • subaccountName - name of the subaccount
  • coin - coin mined by subaccount
  • payoutAddress - payoutAddress associated to the coin

Clear Inactive Workers

Clear Inactive Workers: Removes all inactive workers associated to the subaccount

POST _/api/external/v1/clear-inactive-workers?subaccountName=(required)

x-api-secret : aWZXNoK04YUUXy6m6uB5LaCwM3BsL_1S
x-api-key : 5adbf1b4-1ff8-4149-af3c-7cdcd06b8cb3

Parameters
  • subaccountName - (required) name of the subaccount
Responses
  • 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

External Collector APIs

The APIs under this section relate to collector and virtual subaccount hashrate allocation. Depending on the nature of the API, the permission required to access the resource will vary.

Create Collector Subaccount

Create Collector Subaccount: creates a collector subaccount via the external api. Similar to the internal api, the request provided must contain at least 1 virtual subaccount. The virtual subaccount(s) passed on the initial creation will have their allocation set on the same UTC day. Any succeeding changes to the virtual subaccount allocation (such as additional virtual subaccounts, or updating allocation value) will be reflected in the next UTC day.

POST _/api/external/v1/subaccount

x-api-secret : aWZXNoK04YUUXy6m6uB5LaCwM3BsL_1S
x-api-key : 5adbf1b4-1ff8-4149-af3c-7cdcd06b8cb3

Request

sample request:

{
  "name": "collector1",
  "miningCurrency": "BTC",
  "withdrawAddress": "34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo",
  "virtualSubaccounts":[
    {
      "name": "vsub1",
      "withdrawAddress": "34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo",
      "allocation": 50,
      "tier": 1,
      "isPaymentEnabled": false
    },
    {
      "name": "vsub2",
      "withdrawAddress": "1LQoWist8KkaUXSPKZHNvEyfrEkPHzSsCd",
      "allocation": 25,
      "tier": 2,
      "isPaymentEnabled": true
    }
  ],
  "isPaymentEnabled": true,
  "createObserverLink": true

}
  • name - (required) name of the subaccount; must be a unique name throughout the whole pool; can only contain alphanumeric characters, dash, underscore.
  • miningCurrency - (required) coin to be mined by subaccount; must be a coin supported by the pool; switch coin is not allowed for collector subaccounts
  • withdrawAddress - (required) should be a valid withdraw/payout address for the given mining currency; this will be the overflow subaccount's withdraw address
  • isPaymentEnabled - if not given, default is true; flag to enable or disable daily payouts of the overflow subaccount
  • createObserverLink - optional; if set to true, a subaccount level observer link is created
  • virtualSubaccounts (required) should have a size of at least 1; all objects must pass validation; can only create 100 virtual subaccounts at a time
  • virtualSubaccounts[i].name - (required) should be a unique name within a collector subaccount; can only contain alphanumeric characters, dash, underscore.
  • virtualSubaccounts[i].withdrawAddress - (required) should be a valid withdraw/payout address for the given mining currency
  • virtualSubaccounts[i].allocation - (required) value accepted is assumed to be in MH/s; must be a whole number that is >=0.
  • virtualSubaccounts[i].isPaymentEnabled - if not given, default is true; flag to enable or disable daily payouts of the virtual subaccount
  • virtualSubaccounts[i].tier - if not given, default is 1; priority order of filling the allocation
Responses
  • 201 collector subaccount is successfully created. The newly created subaccount is added to the subaccount list that the x-api-key can access
  • 400 if there is a missing required value in the request if name or virtualSubaccounts[i].name contains an invalid character or reaches greater than 35 characters if virtualSubaccounts[i].allocation is not a whole number or is not >=0 if virtualSubaccounts.size is less than 1
  • 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
  • 409 if the collector/subaccount name is already existing in the system. if there are duplicate virtual subaccount names in the request.
  • 422 if coin is not supported if virtualSubaccounts[i].withdrawAddress is not a valid address for the given coin

sample response:

{
  "id": 542,
  "name": "collector5",
  "miningCurrency": "BTC",
  "withdrawAddress": null,
  "type": 2,
  "paymentMethod": "FPPS",
  "pendingPayouts": null,
  "schemeFee": {
    "id": 542,
    "name": "collector5",
    "fees": [
      {
        "coin": "BTC",
        "chain": "BITCOIN",
        "scheme": "PPLNS",
        "rate": 0.5,
        "isInherited": true
      },
      {
        "coin": "BTC",
        "chain": "BITCOIN",
        "scheme": "FPPS",
        "rate": 1.0,
        "isInherited": true
      },
      {
        "coin": "BCH",
        "chain": "BITCOIN",
        "scheme": "PPLNS",
        "rate": 0.5,
        "isInherited": true
      },
      {
        "coin": "BCH",
        "chain": "BITCOIN",
        "scheme": "FPPS",
        "rate": 1.0,
        "isInherited": true
      }
    ],
    "current": {
      "coin": "BTC",
      "chain": "BITCOIN",
      "scheme": "FPPS",
      "rate": 1.0,
      "isInherited": false
    },
    "pending": null
  },
  "virtualSubaccounts": [
    {
      "id": 422,
      "collectorId": 542,
      "tier": 11,
      "name": "overflow",
      "allocation": 0,
      "withdrawAddress": "2N3oefVeg6stiTb5Kh3ozCSkaqmx91FDbsm",
      "magnitude": "MH/s",
      "observerLink": "https://mothership-web.tokyo.dev.sbicrypto.com/observers?linkId=jprL2RCs1T3Ls37mqTUrrwIxT_jkYXFK",
      "created": "2023-03-21T22:51:25.713+00:00",
      "updated": "2023-03-21T22:51:25.713+00:00",
      "isOverflow": true,
      "isPaymentEnabled": true
    },
    {
      "id": 423,
      "collectorId": 542,
      "tier": 2,
      "name": "vsub1",
      "allocation": 99,
      "withdrawAddress": "2N3oefVeg6stiTb5Kh3ozCSkaqmx91FDbsm",
      "magnitude": "MH/s",
      "observerLink": "https://mothership-web.tokyo.dev.sbicrypto.com/observers?linkId=ehgK8KAAL3Qk1XhdT9r1ESrHLfMIMZD5",
      "created": "2023-03-21T22:51:25.713+00:00",
      "updated": "2023-03-21T22:51:25.713+00:00",
      "isOverflow": false,
      "isPaymentEnabled": true
    }
  ],
  "observerLink": "https://mothership-web.tokyo.dev.sbicrypto.com/observers?linkId=bPiWoElruIgd4ooyEGHfMxQotdBzsaOE"
}
  • id - unique id given to the collector; often referred to as the subaccount/collector id

  • name - the name of the subaccount

  • miningCurrency - coin to be mined by subaccount and subsequently the virtual subaccounts.

  • type type of subaccount

  • observerLink - observer link in the subaccount level

  • schemeFee.coin - coin of the current scheme-fee

  • schemeFee.chain - coin chain of the current scheme-fee

  • schemeFee.scheme - earning scheme applied to the subaccount

  • schemeFee.rate - fee rate deducted to the earnings of the subaccount/virtual subaccount as pool fee

  • schemeFee.isInherited - true means that the current scheme fee has been overridden at an account or subaccount level - false means that the current scheme fee is inherited from the default system set fee/scheme

  • virtualSubaccounts[i].id - unique id given to the virtual subaccount

  • virtualSubaccounts[i].allocation - hashrate value allocated to the virtual subaccount

  • virtualSubaccounts[i].magnitude - the magnitude of the allocation

  • virtualSubaccounts[i].name - the name of the virtual subaccount

  • virtualSubaccounts[i].collectorId - same value as id

  • virtualSubaccounts[i].observerLink - the unique URL to access information about the virtual subaccount

  • virtualSubaccounts[i].created - datetime when resource was created

  • virtualSubaccounts[i].updated - datetime when resource was last updated

  • virtualSubaccounts[i].isPaymentEnabled - flag to show if daily payouts of the virtual subaccount is enabled/disabled

  • virtualSubaccounts[i].overflow - flag to show if the virtual subaccount is an overflow or not

  • virtualSubaccounts[i].tier - priority order of allocation of the virtual subaccount

Add Virtual Subaccount

Add Virtual Subaccount: adds an additional virtual subaccount to an existing collector subaccount via the external api. Similar to the internal api, the request provided must contain at least 1 virtual subaccount. The virtual subaccount(s) passed in this request, as well as the effect (if any) of this allocation with the other virtual subaccounts, will be reflected on the next UTC day.

POST _/api/external/v1/subaccount/virtual

x-api-secret : aWZXNoK04YUUXy6m6uB5LaCwM3BsL_1S
x-api-key : 5adbf1b4-1ff8-4149-af3c-7cdcd06b8cb3

Request

sample request:

{
  "id": 99,
  "name": "collector1",
  "virtualSubaccounts": [
    {
      "name": "vsub3",
      "withdrawAddress": "bc1qa5wkgaew2dkv56kfvj49j0av5nml45x9ek9hz6",
      "allocation": 820,
      "tier": 1 
    }
  ]
}
  • id - id of the collector subaccount. Must be a subaccount owned by the api-key and must be a COLLECTOR type subaccount.

  • name - name of the collector subaccount. Must be a subaccount owned by the api-key and must be a COLLECTOR type subaccount.

  • virtualSubaccounts (required) should have a size of at least 1; all objects must pass validation; can only create 100 virtual subaccounts at a time

  • virtualSubaccounts[i].name - (required) should be a unique name within a collector subaccount; can only contain alphanumeric characters, dash, underscore.

  • virtualSubaccounts[i].withdrawAddress - (required) should be a valid withdraw/payout address for the given mining currency

  • virtualSubaccounts[i].allocation - (required) value accepted is assumed to be in MH/s; must be a whole number that is >=0

  • virtualSubaccounts[i].tier - (required) priority order of filling the allocation

  • virtualSubaccounts[i].isPaymentEnabled - if not given, default is true; flag to enable or disable daily payouts of the virtual subaccount

Responses
  • 201 virtual subaccount is successfully created
  • 400 if there is a missing required value in the request if name is not a collector subaccount if virtualSubaccounts[i].name contains an invalid character or reaches greater than 35 characters if virtualSubaccounts[i].allocation is not a whole number or is not >=0 if virtualSubaccounts.size is less than 1
  • 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 subaccount name from the request
  • 409 if there are duplicate virtual subaccount names in the request if there are duplicate virtual subaccount names in the request that already exist in the db for the given collector
  • 422 if virtualSubaccounts[i].withdrawAddress is not a valid address for the given coin if name and id are given but do not match a certain subaccount

sample response:

{
  "id": 101,
  "name": "collector1",
  "miningCurrency": "BTC",
  "type": "COLLECTOR",
  "schemeFee": {
    "coin": "BTC",
    "chain": "BITCOIN",
    "scheme": "PPLNS",
    "rate": 1.0,
    "isInherited": false
  },
  "isPaymentEnabled": true,
  "withdrawAddress": "bc1qa5wkgaew2dkv56kfvj49j0av5nml45x9ek9hz6",
  "virtualSubaccounts": [
    {
      "id": 3,
      "collectorId": 101,
      "name": "vsub3",
      "allocation": 820,
      "withdrawAddress": "bc1qa5wkgaew2dkv56kfvj49j0av5nml45x9ek9hz6",
      "magnitude": "MH/s",
      "observerLink": "https://pool.sbicrypto.com/observers?linkId=QzDqmrREPBRyjLKR2-mued8cFJCdQjXm",
      "created": "2022-10-18T10:23:47.436+00:00",
      "updated": "2022-10-18T10:23:47.436+00:00",
      "tier": 1,
      "isPaymentEnabled": true
    }
  ]
}
  • id - unique id given to the collector; often referred to as the subaccount/collector id
  • name - the name of the subaccount
  • miningCurrency - coin to be mined by subaccount and subsequently the virtual subaccounts.
  • type type of subaccount
  • schemeFee.coin - coin of the current scheme-fee
  • schemeFee.chain - coin chain of the current scheme-fee
  • schemeFee.scheme - earning scheme applied to the subaccount
  • schemeFee.rate - fee rate deducted to the earnings of the subaccount/virtual subaccount as pool fee
  • schemeFee.isInherited - true means that the current scheme fee has been overridden at an account or subaccount level
    • false means that the current scheme fee is inherited from the default system set fee/scheme
  • virtualSubaccounts - only contains the newly added virtual subaccount from the request
  • virtualSubaccounts[i].id - unique id given to the virtual subaccount
  • virtualSubaccounts[i].allocation - hashrate value allocated to the virtual subaccount
  • virtualSubaccounts[i].magnitude - the magnitude of the allocation
  • virtualSubaccounts[i].name - the name of the virtual subaccount
  • virtualSubaccounts[i].collectorId - same value as id
  • virtualSubaccounts[i].observerLink - the unique URL to access information about the virtual subaccount
  • virtualSubaccounts[i].created - datetime when resource was created
  • virtualSubaccounts[i].updated - datetime when resource was last updated
  • virtualSubaccounts[i].isPaymentEnabled - if not given, default is true; flag to enable or disable daily payouts of the virtual subaccount
  • virtualSubaccounts[i].tier - if not given, default is 1; priority order of filling the allocation

Update Virtual Subaccount Allocation

Update Virtual Subaccount Allocation: updates a virtual subaccount's hashrate allocation. If the virtual subaccount's allocation is set to 0 (from a previous non-zero value), the virtual subaccount's balance will get paid out. The virtual subaccount adjustment passed in this request, as well as the effect (if any) of this allocation with the other virtual subaccounts, will be reflected on the next UTC day.

PATCH _/api/external/v1/subaccount/virtual

x-api-secret : aWZXNoK04YUUXy6m6uB5LaCwM3BsL_1S
x-api-key : 5adbf1b4-1ff8-4149-af3c-7cdcd06b8cb3

Request

sample request:

{
  "collector": "collector1",
  "collectorId": 99,
  "virtual": "vsub3",
  "virtualId": 1,
  "allocation": 220,
  "withdrawAddress": "bc1qa5wkgaew2dkv56kfvj49j0av5nml45x9ek9hz6",
  "tier": 1,
  "isPaymentEnabled": true
}
  • collectorId - id of the collector subaccount. Must be a subaccount owned by the api-key and must be a COLLECTOR type subaccount.

  • collector - name of the collector subaccount. Must be a subaccount owned by the api-key and must be a COLLECTOR type subaccount.

  • virtualId - id of the virtual subaccount. Must be a virtual subaccount owned by the collector.

  • virtual - name of the virtual subaccount. Must be a virtual subaccount owned by the collector.

  • allocation - (required) value accepted is assumed to be in MH/s; must be a whole number that is >=0. If value is 0, next UTC day payments will go out.

Responses
  • 200 virtual subaccount is successfully updated and the response object
  • 400 if there is a missing required value in the request if collector is not a collector subaccount if allocation is not a whole number or is not >=0
  • 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 subaccount name from the request
  • 404 if the virtual subaccount is not found for the given collector
  • 422 if collector and collectorId are given but do not match a certain subaccount if virtual and virtualId are given but do not match a certain virtual subaccount

sample response:

{
  "collector": "collector1",
  "collectorId": 99,
  "virtual": "vsub3",
  "virtualId": 1,
  "allocation": 220,
  "withdrawAddress": "bc1qa5wkgaew2dkv56kfvj49j0av5nml45x9ek9hz6",
  "tier": 1,
  "isPaymentEnabled": true
}

Get Collector Subaccount

Get Collector: retrieves details about the virtual subaccounts under a collector.

GET _/api/external/v1/subaccount/{collectorId}/virtual?vSubaccountIds={optional list of virtualSubaccountId}&size=20&page=100&sort=percentage,desc

x-api-secret : aWZXNoK04YUUXy6m6uB5LaCwM3BsL_1S
x-api-key : 5adbf1b4-1ff8-4149-af3c-7cdcd06b8cb3

Request
  • collectorId - (required) should be a subaccount that is of collector type and is owned by the api-key
  • vSubaccountIds (optional) comma separated list of virtual subaccount ids that can be used as filter
  • size (optional) page size; default = 20
  • page (optional) 0-index-based page number; default = 0
  • sort (optional) json key to sort and sort order; default=percentage,desc
Responses
  • 200 virtual subaccount list
  • 400 if the colletor id passed is not a valid subaccount or not a collector subaccount
  • 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 subaccount name from the request

sample response:

{
  "content": [
    {
      "collectorId": 101,
      "collectorName": "collector2",
      "coin": "BTC",
      "scheme": "PPLNS",
      "feeRate": 1.0,
      "allocation": 50,
      "magnitude": "MH/s",
      "hashrate": [
        4.866936909807834E9,
        4.875928471563869E9,
        1.0300492884061522E10
      ],
      "revenue": [
        2.0947369,
        2.09198749
      ],
      "balance": 1.237E-5,
      "observerLink": "https://pool.sbicrypto.com/observers?linkId=Q-sfJ-svLAyznGYVGzBCY5U6Fc7ecfGp",
      "percentage": 0.5,
      "address": "2N3oefVeg6stiTb5Kh3ozCSkaqmx91FDbsm",
      "note": "NO_CHANGE",
      "newAllocation": 50,
      "tier": 1,
      "newTier": 1,
      "vsubaccountName": "vsub2",
      "vsubaccountId": 1,
      "isOverflow": true
    }
  ],
  "first": true,
  "last": true,
  "totalElements": 1,
  "totalPages": 1,
  "size": 10,
  "number": 0,
  "numberOfElements": 1,
  "sort": {
    "field": "percentage",
    "ascending": true
  }
}
  • collectorId - subaccount/collector id of the virtual subaccount id

  • collectorName - subaccount/collector name of the virtual subaccount name

  • coin - coin to be mined by the virtual subaccounts.

  • scheme - earning scheme of the virtual subaccount's earnings (comes from subaccount)

  • feeRate - fee rate of the virtual subaccount's earnings (comes from subaccount)

  • allocation - current UTC day's hashrate allocation

  • magnitude - magnitude of the allocation

  • hashrate[] - current 10m[0],1h[1],1d[2] hashrate

  • revenue[] - yesterday[0] and today's[1] estimated revenue

  • balance - unpaid amount to the virtual subaccount in whole coin unit

  • observerLink - the unique URL to access information about the virtual subaccount

  • percentage - current UTC day's percentage of the hashrate allocation for the virtual subaccount

  • address - payout address of the virtual subaccount

  • note - NO_CHANGE (no upcoming change for the virtual subaccount's allocation),

CHANGE_PENDING (expected hashrate allocation change for the next utc day), PAYMENT_PENDING (payment pending for the virtual subaccount)

  • newAllocation - next UTC day's hashrate allocation
  • vsubaccountName - name of the virtual subaccount
  • vsubaccountId - id of the virtual subaccount
  • isPaymentEnabled - if not given, default is true; flag to enable or disable daily payouts of the virtual subaccount
  • tier - if not given, default is 1; priority order of filling the allocation

Get Virtual Subaccount Details

Get Virtual Subaccount Details: retrieves details about the virtual subaccounts.

GET _/api/external/v1/subaccount/virtual?collectorIds={list of collectorIds}&vSubaccountIds={list of virtualSubaccountIds}&size=20&page=100&sort=percentage,desc

x-api-secret : aWZXNoK04YUUXy6m6uB5LaCwM3BsL_1S
x-api-key : 5adbf1b4-1ff8-4149-af3c-7cdcd06b8cb3

Request
  • collectorIds (required) comma separated list of collectors ids; should be owned by the api-key
  • vSubaccountIds (required) comma separated list of virtual subaccount ids; should be owned by the api-key
  • filter (optional) filter by name of virtual subaccount
  • size (optional) page size; default = 20
  • page (optional) 0-index-based page number; default = 0
  • sort (optional) json key to sort and sort order; default=percentage,desc
Responses
  • 200 virtual subaccount list
  • 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 subaccount name from the request

sample response:

{
  "content": [
    {
      "collectorId": 101,
      "collectorName": "collector2",
      "coin": "BTC",
      "scheme": "PPLNS",
      "feeRate": 1.0,
      "allocation": 50,
      "magnitude": "MH/s",
      "hashrate": [
        4.866936909807834E9,
        4.875928471563869E9,
        1.0300492884061522E10
      ],
      "revenue": [
        2.0947369,
        2.09198749
      ],
      "balance": 1.237E-5,
      "observerLink": "https://pool.sbicrypto.com/observers?linkId=Q-sfJ-svLAyznGYVGzBCY5U6Fc7ecfGp",
      "percentage": 0.5,
      "address": "2N3oefVeg6stiTb5Kh3ozCSkaqmx91FDbsm",
      "note": "NO_CHANGE",
      "newAllocation": 50,
      "tier": 1,
      "newTier": 1,
      "vsubaccountName": "vsub2",
      "vsubaccountId": 1,
      "isOverflow": true
    }
  ],
  "first": true,
  "last": true,
  "totalElements": 1,
  "totalPages": 1,
  "size": 10,
  "number": 0,
  "numberOfElements": 1,
  "sort": {
    "field": "percentage",
    "ascending": true
  }
}
  • collectorId - subaccount/collector id of the virtual subaccount id
  • collectorName - subaccount/collector name of the virtual subaccount name
  • coin - coin to be mined by the virtual subaccounts.
  • scheme - earning scheme of the virtual subaccount's earnings (comes from subaccount)
  • feeRate - fee rate of the virtual subaccount's earnings (comes from subaccount)
  • allocation - current UTC day's hashrate allocation
  • magnitude - magnitude of the allocation
  • hashrate[] - current 10m[0],1h[1],1d[2] hashrate
  • revenue[] - yesterday[0] and today's[1] estimated revenue
  • balance - unpaid amount to the virtual subaccount in whole coin unit
  • observerLink - the unique URL to access information about the virtual subaccount
  • percentage - current UTC day's percentage of the hashrate allocation for the virtual subaccount
  • address - payout address of the virtual subaccount
  • note - NO_CHANGE (no upcoming change for the virtual subaccount's allocation), CHANGE_PENDING (expected hashrate allocation change for the next utc day), PAYMENT_PENDING (payment pending for the virtual subaccount)
  • newAllocation - next UTC day's hashrate allocation
  • vsubaccountName - name of the virtual subaccount
  • vsubaccountId - id of the virtual subaccount
  • isPaymentEnabled - if not given, default is true; flag to enable or disable daily payouts of the virtual subaccount
  • tier - if not given, default is 1; priority order of filling the allocation

Observer Key Access Control

UI clients will need to specify their Observer key in the X-observer-key header. Any request to the APIs without a valid Observer key will be rejected with a 401 - Unauthorized response code. If a valid bearer token is passed, the endpoint can also be accessed.

sample error response when invalid observer key is given

{
    "error": "invalid_token",
    "error_description": "Observer Key is invalid."
}

Get Worker Details

Worker Details: This endpoint provides paginated worker details for all workers under the subaccount associated with the observer key passed. This endpoint uses the same response object and backend logic as internal Get Worker Details.

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

Accept : application/vnd.sbi.details.worker+json X-observer-key : 348UpQjhPMRPxTK8QVDqY9RavwGrMVebox

Parameters
  • hashrateRanges - (optional) comma-delimited list of integers representing minutes from now

  • 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.sbicrypto.com/api/observer/v1/workers/details?hashrateRanges=10,60,1440&nameFilter=&size=10&sort=name,desc&statusFilters=&page=1' \
--header 'X-observer-key: G-kvIxAg-koQSNZmQwMcDE3tagO6Ed-S' \
--data-raw ''

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
    }
}

Get Worker Hashrates (Graph)

Worker Hashrates: This endpoint provides average worker hashrates for the subaccount associated with the observer key passed, grouped by coin. This endpoint uses the same response object and backend logic as internal Get Worker Hashrate.

Parameters
  • range - specifies ranges by a start and end time (in minutes before now) and depends on resolution to determine the number of equally spaced ranges. Data is returned in intervals from oldest to most recent.

  • resolution - defines the number of sub-ranges to break the specified range up into. This needs to be realistic so that the subranges are at least 20 seconds or else the data is meaningless.

  • coins - filters the results to only include the coin(s) in a comma separated list. This field is optional and will default to all coins if not given

The output contains a map of equal sized lists, the size of which is determined by either the number of specified ranges, or the length of the specified range in minutes, divided by the interval in minutes. It also contains the computed value of “now” as determined by the server represented in UTC based JSON format. The output hashrate will be in MH/s.

For range the results are a set of average hashrates of discrete time ranges. For example, if range is 0,10 and resolution is 5 then there will be two rows returned: the first for the time period of 10 minutes ago to 5 minutes ago, the second for the data from 5 minutes ago to now.

GET /api/observer/v1/hashrates/coin?range={range}:{range}&resolution={resolution}&coins={coins}

_Accept : _/__
X-observer-key : 348UpQjhPMRPxTK8QVDqY9RavwGrMVebox

sample request

curl --location --request GET 'https://pool.sbicrypto.com/api/observer/v1/workers/hashrates/coin?range=0:60&resolution=13' \
--header 'X-observer-key: G-kvIxAg-koQSNZmQwMcDE3tagO6Ed-S' \
--data-raw ''

sample response

{
   "now": "2019-12-03T15:52:31.673Z",
   "hashrate": {
      "BTC": [
         91.3,
         21.7,
         30.5,
         45.1,
         61.8,
         40.1,
         72.4
      ],
      "BCH": [
         23.7,
         42,
         57.1,
         45.1,
         61.8,
         40.1,
         21.5
      ],
      "BSV": [
         23.7,
         42,
         57.1,
         45.1,
         61.8,
         40.1,
         1.7
      ]
   }
}

Get Worker Hashrates (By Subaccount)

Subaccount Hashrates: This endpoint provides average worker hashrate over time ranges for the subaccount associated with the observer key.

GET /api/observer/v1/workers/hashrates?ranges={range},{range},{range}

  • Accept : application/vnd.sbi.hashrate.subaccount+json
Parameters
  • ranges - specifies one or more time ranges of interest, in minutes from “now”. Data is returned in the order of the specified ranges.

  • range - specifies ranges by a start and end time (in minutes before now) and depends on resolution to determine the number of equally spaced ranges. Data is returned in intervals from oldest to most recent. (mutually exclusive with ranges)

sample request

curl --location --request GET 'https://pool.sbicrypto.com/api/observer/v1/workers/hashrates?ranges=10,60,1440' \
--header 'X-observer-key: G-kvIxAg-koQSNZmQwMcDE3tagO6Ed-S' \
--data-raw ''

sample response

{
    "now": "2021-02-25T04:49:00.000+00:00",
    "subaccounts": {
        "workeraggregatortest": 16
    },
    "hashrate": {
        "workeraggregatortest": [
            0.0,
            0.0,
            0.0
        ]
    }
}

Worker Status

Worker Status: This endpoint provides current worker status (online/offline/dead) grouped for the subaccount associate with the observer key. This endpoint uses the same response object and backend logic as internal Get Worker Status.

GET /api/observer/v1/workers/status Accept: application/vnd.sbi.workerstatus.subaccount+json

sample response

{
    "status": {
        "16": {
            "name": "workeraggregatortest",
            "online": 2500,
            "offline": 1648,
            "dead": 26431
        }
    }
}

Get Worker Details (CSV)

Worker Details: This endpoint provides csv worker details for all workers under the subaccount associated with the observer key passed. This endpoint uses the same response object and backend logic as internal Get Worker Details (CSV).

GET /api/observer/v1/workers/details?hashrateRanges={hashrangeRanges}&startDate={startDate}&endDate={endDate}&nameFilter={nameFilter}&statusFilters={statusFilters}

Accept : text/csv X-observer-key : 348UpQjhPMRPxTK8QVDqY9RavwGrMVebox

Parameters
  • hashrateRanges - (optional) comma-delimited list of integers representing minutes from now
  • startDate - retrieve miners with last sharelog time greater than startDate
  • endDate - retrieve miners with last sharelog time less than endDate
  • nameFilter - (optional) string greater than 2 characters for filtering by worker name
  • statusFilters - (optional) comma delimited list of acceptable statuses in the set ONLINE,OFFLINE,DEAD

sample request

curl --location --request GET 'https://pool.sbicrypto.com/api/observer/v1/workers/details?hashrateRanges=10,60,1440&startDate=2021-02-01&endDate=2021-03-03&nameFilter=&statusFilters=' \
--header 'X-observer-key: G-kvIxAg-koQSNZmQwMcDE3tagO6Ed-S' \
--header 'Accept: text/csv' \
--data-raw ''

sample response

worker,subaccount,status,lastShareDate,hashrate10m,hashrate60m,hashrate1440m
simulator123-1000041359,workeraggregatortest,DEAD,2021-03-03T11:07:38+09:00,0.0,0.0,1280320.206565831
simulator123-1000078799,workeraggregatortest,DEAD,2021-03-02T17:42:16+09:00,0.0,0.0,2736562.2735758224

Validate Observer Key

Determines if observer key is valid or not.

GET /api/observer/v1/workers/validate

Responses
  • 204 if observer key is valid.
  • 401 if observer key is not valid.