Tracking & Payment System: (mainnet)
API keys are required for the public API service and are used in the 'My Nodes' pages of the tracking server web site.
The main purposes of the API keys are to replace sending email addresses of node operators in the url of API calls and to remove the need for an email address to be entered on a My Nodes page to display nodes associated with that address. It also stops other users or bots from clicking on buttons on the Node Details page to send emails for details and challenges.
The node operator enters the email address associated with his/her nodes on the Settings page.
A new API key is generated and a confirmation email is sent to the email address entered.
When the email link for the new API key is clicked, the key is confirmed and activated.
The node operator is brought back to the Settings page and the API key is displayed.
The API key is required for use with third party applications. Hosting providers (or anyone with many nodes they wish to group together) may also create API Subkeys for each of their customers. An API Subkey is based on the optional Category associated with a node and works similar to an API Key. See the Settings page for details and creating subkeys.
First obtain a key from the tracking server Settings page. The key must be used for any API request that returns node data linked to the email address provided at the time of the node configuration and registration.
Note: The API calls are meant to replace any use of a url with 'grid' in it. The grid urls were intended to be used by the web pages, not as stand-alone API calls. Please do not use them.
Please limit the number of API calls to no more than once every 30 seconds for periodic calls. Rate limiting will be implemented at a later time.
Any use of <sample> in a url example is a value meant to be substituted without the <>. All data is returned as JSON.
If an error is encountered, a JSON object with a key of "error" is returned with a message along with a status code.
These do not require an API key
Nodes
All of the following calls require an API key. The API key must be sent as a query parameter appended to the Path. ?key=<apikey>
Note: The category field is limited to 60 characters.
Path: /api/nodes/my/list?key=<apikey>
Optional parameters:
&status=<status> where <status> can be 'up' or 'down'. e.g. &status=up
&cat=<category> where <category> is the optional value entered when setting up a node
&addr=1 includes the t-address and stake address for mainkeys, and only the stake for subkeys
Return: array of nodes associated with the node email address linked to the API key.
Sample:
{"nodes":[{"id":9,"status":"up","home":"ts1-testnet.na","curserver":"ts1-testnet.na","ip4":"198.58.105.60","ip6":null,"fqdn":"zen1.secnodes.com","createdAt":"2017-10-16T19:24:11.000Z","updatedAt":"2018-06-13T21:44:27.000Z","email":"[email protected]","zenver":2001050,"trkver":"0.2.1","category":"mynodes"}]}
Path: /api/nodes/my/sumearnings?key=<apikey>
Optional parameters:
&cat=<category> where <category> is the optional value entered when setting up a node
Return: array of aggregated monthly earnings in Zen for all nodes associated with the key.
Sample:
{"records":23, "rows":[{"year":2017, "month":12, "mname":"Dec", "zen":"19.69718495"}, {"year":2018, "month":1, "mname":"Jan", "zen":"31.36415625"}, {"year":2018, "month":2, "mname":"Feb", "zen":"27.13743512"}, {"year":2018, "month":3, "mname":"Mar", "zen":"32.29617967"}, {"year":2018, "month":4, "mname":"Apr", "zen":"27.21069243"}, {"year":2018, "month":5, "mname":"May", "zen":"23.72376122"}, {"year":2018, "month":6, "mname":"Jun", "zen":"21.37787080"}, {"year":2018, "month":7, "mname":"Jul", "zen":"42.73267658"}, {"year":2018, "month":8, "mname":"Aug", "zen":"52.19525388"}, {"year":2018, "month":9, "mname":"Sep", "zen":"37.12901019"}, {"year":2018, "month":10, "mname":"Oct", "zen":"40.87171130"}, {"year":2018, "month":11, "mname":"Nov", "zen":"35.62413220"}, {"year":2018, "month":12, "mname":"Dec", "zen":"36.51480768"}, {"year":2019, "month":1, "mname":"Jan", "zen":"39.52086624"}, {"year":2019, "month":2, "mname":"Feb", "zen":"32.98548001"}, {"year":2019, "month":3, "mname":"Mar", "zen":"38.24342200"}, {"year":2019, "month":4, "mname":"Apr", "zen":"41.14300001"}, {"year":2019, "month":5, "mname":"May", "zen":"38.97947542"}, {"year":2019, "month":6, "mname":"Jun", "zen":"29.85974024"}, {"year":2019, "month":7, "mname":"Jul", "zen":"23.42583311"}, {"year":2019, "month":8, "mname":"Aug", "zen":"19.80048155"}, {"year":2019, "month":9, "mname":"Sep", "zen":"17.84940790"}, {"year":2019, "month":10, "mname":"Oct", "zen":"0.60352840"}], "totalzen":710.2861071499998}
Path: /api/nodes/my/earnings?key=<apikey>
Optional parameters:
&nid=<nodeid> return only for specified node. e.g. &nid=435
&cat=<category> where <category> is the optional value entered when setting up a node
Return: array of nodes with their associated earnings to date along with a record count and summary data that include the total zen earned to date and the current price of Zen in USD. Data is associated with the node email address linked to the API key.
Sample:
{"records":2,"rows":[{"nid":9,"fqdn":"zen1.secnodes.com","zen":"484.41397152","added":"2017-10-16T19:24:11.000Z"},{"nid":12,"fqdn":"zen102.secnodes.com","zen":"5.22053245","added":"2017-10-16T19:25:06.000Z"}],"summary":{"totalzen":489.63450397,"zenusd":17.18517909073966}}
Path: /api/nodes/my/payments?key=<apikey>&page=<pagenumber>&rows=<rowcount>
Optional parameters:
&nid=<nodeid> return only for specified node. e.g. &nid=435
&status=<status> where <status> is 'exclude' to only returned excluded e.g. &status=exclude
&type=<type> where <type> is either 'e' for earnings only or 'c' for credits only. e.g. &type=e
&cat=<category> where <category> is the optional value entered when setting up a node
Result: Payments and Credits for all nodes associated with the API key. The type is 'e' for earnings and 'c' for credit. Credits will list the associated Payment Masters in 'creditpmids'
Sample:
{"page":8, "total":271, "rowsperpage":50, "records":13545, "rows":[{"id":31418884, "status":"paid", "startdate":"2019-03-25T11:12:40.000Z", "enddate":"2019-03-26T11:42:11.000Z", "pmid":2260, "type":"e", "uptime":"1.0000", "zen":"0.04059540", "created":"2019-03-26T11:59:24.000Z", "paidat":"2019-04-01T23:12:36.000Z", "txid":"6f230f5553bfcf2ffb408b7302c32eb4bd6b1e94cc4107be95f266c2054c253d", "creditpmids":null, "nid":26201}, {"id":31418878, "status":"paid", "startdate":"2019-03-25T11:12:40.000Z", "enddate":"2019-03-26T11:42:11.000Z", "pmid":2260, "type":"e", "uptime":"1.0000", "zen":"0.04059540", "created":"2019-03-26T11:59:24.000Z", "paidat":"2019-04-01T23:12:36.000Z", "txid":"6f230f5553bfcf2ffb408b7302c32eb4bd6b1e94cc4107be95f266c2054c253d", "creditpmids":null, "nid":26205}, {...
Path: /api/payments/masters?key=<apikey>
Optional parameters:
&id=<id> returns the specific payment period. e.g. &id=73
&count=<number> returns additional summaries after the id. Only valid with '&id' e.g. &id=101&count=7
Result: List of payment period summaries for all nodes.
Sample:
{"records":719, "rows":[{"id":1, "paytype":"e", "startblock":222464,"startTime":"2017-12-15T07:49:05.000Z", "endblock":223040, "endTime":"2017-12-16T07:42:21.000Z", "zen":"272.73600000", "nodecount":2991,"excluded":285, "allocation":"0.09118556", "zenusd":"47.19"}, {"id":4,"paytype":"e", "startblock":223040, "startTime":"2017-12-16T07:42:21.000Z", "endblock":223616, "endTime":"2017-12-17T08:10:07.000Z", "zen":"252.00000000", "nodecount":3185, "excluded":320,"allocation":"0.07912088", "zenusd":null}]}
Rate limiting was added at the end of 2019. Please see Tracking Server API Rate Limits.
Current limit defaults (subject to change at any time):
Path /api: limit 300 max per 30 seconds.
Path /grid: limit 100 max per 30 seconds.