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:

READ - Query non-financial information,
FINANCIALS- Query payout-related information from earnings history,
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.

General
Public API
Authenticated API
- API Key Access Control
External Read APIs
External Financials APIs
External Update APIs
External Collector APIs
Observer Key Access Control

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

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)

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)

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

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}

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}

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

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

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

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

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)

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

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

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

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

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

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}

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

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}

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}

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.

SBI Crypto Pool API

Table of Contents

General

Base URL

Versioning

Media Type

Pagination

Public API

Public Hashrate API

Parameters:

Coin API

Pool Foundblock API

Exchange Rate API

Parameters:

Public Payouts API

Parameters:

Payout Rate API

Parameters:

Historical Luck API

Parameters:

Other Pool Stats API

Authenticated API

API Key Access Control

External Read APIs

Get Account Details

Request

Responses

Get Subaccount Details

Request

Responses

Get Worker Details

Request

Responses

Get Subpool Details

Request

Responses

External Financial APIs

Get Payout Information

Parameters

Responses

Get Earning Payments

Parameters

Paging and Sorting

Filtering

Access Control

Responses

Get Estimated Revenues

Parameters

Responses

Retrieve Tx Payouts

Parameters

Paging and Sorting

Filtering

Access Control

Responses

External Update APIs

Create Normal Subaccount

Request

Responses

Update Payout Address

Request

Responses

Update Mining Coin

Request

Responses

Clear Inactive Workers

Parameters

Responses

External Collector APIs

Create Collector Subaccount

Request

Responses

Add Virtual Subaccount

Request

Responses

Update Virtual Subaccount Allocation

Request

Responses

Get Collector Subaccount

Request