Pool API Standard

[Inaba]

SMF won't format tables properly (surprise!) ... I will reformat it if it's too confusing.

Here is a first draft proposal for a JSON API standards for Bitcoin Pools:

Generic keys:

JSON Key	Description
version	Version of the API in use

Pool keys:

JSON Key	Description
round_duration	Duration of the current round
round_shares	Number of shares submitted in current round
hashrate	Total hashrate of the pool

User keys:

JSON Key	Description
round_shares

Total shares submitted by user for current round

estimated_reward

Estimated reward the user will receive on next payout in BTC

hashrate	Total hashrate of the user
last_activity

Last miner activity in GMT

btc_balance	Current available balance for the user in BTC
btc_unconfirmed	Unconfirmed/unavailable balance for the user in BTC
btc_paid	Total amount paid to the user in BTC
last_payout_amount	Last amount paid to the user in BTC
last_payout_time	Time user was paid in GTM

[1715030167]

1715030167

[1715030167]

1715030167

[1715030167]

1715030167

[1715030167]

1715030167

[1715030167]

1715030167

[flower1024]

what do you think about adding a field about the payout-method used?
and i would love to see standardized uris too.

[Inaba]

Uris? 

What do you mean by payout method exactly?

[Clipse]

I really like these suggestions, I will soon be adding proper json and may aswell make use of the suggested options once "finalised" in this thread I assume.

[DeathAndTaxes]

I assume he mean reward method (PPS, SMPSS, DGM, etc)?

Including things like fee %, payout tx fees, merge mining would make it possible to keep something like this actually up to date.
https://en.bitcoin.it/wiki/Comparison_of_mining_pools

[flower1024]

I assume he mean reward method (PPS, SMPSS, DGM, etc)?

yes, thanks
would be easy to develop an app to monitor multiple pools then

[Luke-Jr]

https://en.bitcoin.it/wiki/BIP_PoolAPI WIP

[P_Shep]

p_shep approves this message

[organofcorti]

A standardised api for pool stat history would be nice.

[P_Shep]

https://en.bitcoin.it/wiki/BIP_PoolAPI WIP

"rewardalgo" may have to go per worker. Some pools you can select what worker does what... EMC & Ozcoin allows this. Perhaps this field can be used to list available algorithms.
I quite liked my idea for a round/block structure. Allows for block history to use the same structure repeated. And everyone likes re-using code

[organofcorti]

For a pool history API, for pools like deepbit where pool history will be thousands of blocks there might need to be a protocol limiting the number of blocks to 100 recent blocks, and then have a slightly different url for blocks further back.

I'd like to see a JSON or other API present a pool history table like this:

Code:

Block height/hash | Block timestamp | Round duration | Total submitted shares | Current difficulty | <Payout method specific field>

Data should be standardised too. 'Round duration' should be in seconds and the timestamp should be in the standard unix  %Y-%m-%d %H:%M:%S. Current difficulty is important to include. It's easily available elsewhere, but this being a block history API it's a pain for a miner to search the difficulty history for each and every block.

The field for <Payout method specific field> can be used for any results specific to a payout method. I had SMPPS in mind (a field for buffer), but I'm sure other payout methods would find a use for it.

[Graet]

A standardised api for pool stat history would be nice.

standardisation is slowly creeping into bitcoin - which is good

Ozcoin shows per worker hashrate as well as total, this was on user request - I think it needs to be included for people that use API to monitor rigs up/down. e.g. our desktop widget will not work without separated worker hashrates.
At Ozcoin payout method is by user not worker (this might change in the future)
Currently we are doing some heavy development on the backend and site - whilst a great idea a standardised API is not high on our priorities.

[DeathAndTaxes]

Data should be standardised too.

Agree

'Round duration' should be in seconds

Agreed (as in integer unformated # of seconds)

and the timestamp should be in the standard unix  %Y-%m-%d %H:%M:%S.

In my opinon formatting has no place in an API that is a presentation layer task.  Unix/Posix time is better since it is an integer and every language has tools to format it.

For example as of writing Unix/Posix time is 1337632227

Still the larger point is that data format should be part of the spec.

Current difficulty is important to include.

Agreed.

[organofcorti]

and the timestamp should be in the standard unix  %Y-%m-%d %H:%M:%S.

In my opinon formatting has no place in an API that is a presentation layer task.  Unix/Posix time is better since it is an integer and every language has tools to format it.

For example as of writing Unix/Posix time is 1337632227

I would definitely prefer it to be unixtime for my own purposes, although I get a seamless conversion when I need it. However I proposed the above format because I thought that the average miner might not be able to use unixtime so easily.

Still the larger point is that data format should be part of the spec.

Yes, that's the main thing. Anyone wanting to - for example - create a website to list miner api results or pool history will need all data standardised if she or he's going to list all pools equally easily. Btc-poolwatch.com was a constant job for koo (the owner/writer) since adding an api meant writing a new code to interpret the api, and any api changes broke the service.

[Inaba]

I think UNIX timestamp is the way to go.  If a pool wants to add extra "human" time, then that's easily done.  I think the standard as UNIX time is the right choice.  Really, all time should be given in unix time stamps and extra fields added for human time if desired.

So my proposal for the standard:

All time displays presented as UNIX epoc.  This will also do away with the need for timezoning questions/issues.
All hash rates presented as hashes per second.
All BTC's presented as Satoshis

[P_Shep]

I think UNIX timestamp is the way to go.  If a pool wants to add extra "human" time, then that's easily done.  I think the standard as UNIX time is the right choice.  Really, all time should be given in unix time stamps and extra fields added for human time if desired.

So my proposal for the standard:

All time displays presented as UNIX epoc.  This will also do away with the need for timezoning questions/issues.
All hash rates presented as hashes per second.
All BTC's presented as Satoshis

Sounds good to me

[organofcorti]

I think UNIX timestamp is the way to go.  If a pool wants to add extra "human" time, then that's easily done.  I think the standard as UNIX time is the right choice.  Really, all time should be given in unix time stamps and extra fields added for human time if desired.

So my proposal for the standard:

All time displays presented as UNIX epoc.  This will also do away with the need for timezoning questions/issues.
All hash rates presented as hashes per second.
All BTC's presented as Satoshis

Good proposal Inaba, and thanks to Inaba and P_Shep for getting this going.

Can I add:

• All fields to be integer (no char, no added commas etc, no double)
• Apis should all be the same format (preferably JSON).
  
• The number and order of fields in each api should be standardised.
• The api call should be standardised -
  eg the following could call worker stats:

Code:

poolname.com/api/workername

• Any api call that includes historical data should include an option for selection of amount of data. Eg if X is the last X rounds of historical data:[\li]
  
  Code:

  poolname.com/api/username/history?X

  
  

[organofcorti]

One more thing - a pool history request shouldn't require a key (Ahem maxbtc, I'm looking at you )

[slush]

estimated_reward

Estimated reward the user will receive on next payout in BTC

What if user (or few of his workers) are PPS? null value?

last_activity

Last miner activity in GMT

UTC, not GMT! GMT has summer/winter time, which is always pain in applications.

btc_balance	Current available balance for the user in BTC
btc_unconfirmed	Unconfirmed/unavailable balance for the user in BTC
btc_paid	Total amount paid to the user in BTC

Let's rename it to balance, balance_unconfirmed, balance_paid. Otherwise we'll rename those fields for NMC? :-)

[slush]

I'm not against this initiative if it will need just to rename columns and URLs in my own API (which was - as Tycho mentioned - the first API, and there's no general issue with that). That means - I don't see any reason to change token management etc.

Also, we should define some standard on ask rate from clients. I'm caching API calls for 30 seconds, but still I see some stupid users fetching JSON data every second. That's not only annoying, that also needs much more transfers than mining itself of those users (especially when they're CPU miners).