Tracking & Payment System: Beta(testnet)
API keys are required for the public API service and are now used in the 'My Nodes' pages of the tracking server web site.
The main purpose of the API key is replace sending email addresses of node operators in the url of API calls and removing the ability for any email address to be entered on a My Nodes page to display nodes associated with that address. It will also stop 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.
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 email address (provided at the time of the node configuration).
Note: The API calls are meant to replace any use of a url '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 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.
These do not require an API key
Path: /api/srvstats
Return: the current server, region and global node counts and estimated earnings.
Sample:
{"server":"ts1.na","region":"na","state":"up","nodes":1050,"up":967,"down":41,"inactive":42,"regional":{"total":4293,"up":3948,"down":180,"inactive":161},"global":{"total":12179,"up":11443,"down":404,"inactive":326},"estearn":"0.0213"}
Path: /api/srvlist
Return: regions and servers.
Sample:
{"region":"na","regions":[["na","North America"],["eu","Europe"]],"servers":["ts2.na","ts1.na","ts3.na","ts4.na","ts1.eu","ts2.eu","ts3.eu","ts4.eu"]}Note: Nodes use this list to register and for failover. The tracking servers also pushes a server list update when a node connects.
Path: /api/earnings
Return: amount of stake, current worth of ZEN, BTC in USD, Price of ZEN in USD, total ZEN earned by all nodes to date, worth of toal ZEN paid in USD.
Sample:
{"stake":42,"zenbtc":0.00402976,"btcusd":7519,"zenusd":30.29976544,"zenearned":41231.42601336,"zenpaidusd":"1249302.54"}
Path: /api/chal/open
Return: the open challenge count for each server
Sample:
{"chalOpenCount":[{"server":"ts1.eu","count":3},{"server":"ts1.na","count":18},{"server":"ts2.eu","count":16},{"server":"ts2.na","count":17},{"server":"ts3.eu","count":1},{"server":"ts3.na","count":9},{"server":"ts4.eu","count":2},{"server":"ts4.na","count":6}]}
Path: /api/node/<node_id>/certstatus
Return: validity of the node's certificate, msg to display, certificate information, when the tracking server last checked it, and an internal flag for whether to check peers for TLS connections if the primary DNS method fails.
Sample:
{"valid":true,"msg":"Hostname zzz.f4240.in matches CN zzz.f4240.in","certinfo":{"subject":{"CN":"zzz.f4240.in"},"issuer":{"C":"US","O":"Let's Encrypt","CN":"Let's Encrypt Authority X3"}},"checked":"2018-05-31T21:21:56.987Z","trynext":false}Note: This is used on the Node Detail web page for the certificate status. Since this information is not in the database, this call will only work against the tracking server the node is currently connected to ('curserver' property of a node)
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>
Path: /api/nodes/<nodeid>/detail?key=<apikey>
Return: returns node details for given nodeid. If the email of the API key matches the email of the node, the node t-address and stake t-address are also returned as 'taddr' and 'stkaddr'. Any open Exceptions and Downtimes are also returned.
Sample:
{"id":9,"status":"up","home":"ts1-testnet.na","curserver":"ts1-testnet.na","ip4":"198.58.105.60","ip6":null,"fqdn":"zen1.secnodes.com","config":{"hw":{"CPU":"Intel(R) Xeon(R) CPU E5-2697 v4 @ 2.30GHz","cores":1,"speed":2299},"node":{"version":2001050,"wallet.version":60000,"protocolversion":170002},"trkver":"0.2.1"},"createdAt":"2017-10-16T19:24:11.000Z","updatedAt":"2018-06-13T22:38:25.000Z","taddr":"ztTYagRWzHZuiZxFTuhTgUZigFyoHNBe65s","stkaddr":"ztaj8xNwDjkLxMYWHnWLCvaxHYLmDQzwcxZ","email":"[email protected]","exceptions":[{"id":40184,"etype":"chalmax","start":"2018-05-02T17:06:40.000Z","check":"2018-06-13T22:40:22.000Z","end":null}],"hasException":true}
Path: /api/nodes/my/list?key=<apikey>
Optional parameters: &status=<status> where <status> can be 'up' or 'down'. e.g. &status=up
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"}]}
Path: /api/nodes/my/earnings?key=<apikey>
Optional parameters: &nid=<nodeid> return only for specified node. e.g. &nid=435
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}}
The following API calls return paged results. The page number and row count must be passed in the search parameters of the request.
Example: api/nodes/my/exceptions?key=6201c79b86e4ec54048344512f1498c2ed5ba2c0&page=1&rows=10
The result elements with data about the number of records, total pages and the current page number along with the items requested in the 'rows' array. The number of rows requested is returned as 'rowsperpage'.
{"page":1,"total":79,"rowsperpage":10,"records":781,"rows":[{"id":120679,"fqdn". . .Path: /api/nodes/my/downtimes?key=<apikey>&page=<pagenumber>&rows=<rowcount>
Optional parameters:
&nid=<nodeid> return only for specified node. e.g. &nid=435
&status=<status> where <status> is 'o' for open or 'c' for closed. e.g. &status=o
Result: Downtimes for all nodes associated with the API key.
Sample:
{"page":1,"total":79,"rowsperpage":"10","records":781,"rows":[{"id":120679,"fqdn":"zen1.secnodes.com","home":"ts1-testnet.na","curserver":"ts1-testnet.na","start":"2018-06-12T06:06:20.000Z","check":"2018-06-12T06:19:14.000Z","end":"2018-06-12T06:19:29.000Z","duration":789000,"dtype":"sys","nid":9},{...
Path: /api/nodes/my/exceptions?key=<apikey>&page=<pagenumber>&rows=<rowcount>
Optional parameters:
&nid=<nodeid> return only for specified node. e.g. &nid=435
&status=<status> where <status> is 'o' for open or 'c' for closed. e.g. &status=o
Result: Exceptions for all nodes associated with the API key.
Sample:
{"page":1,"total":1,"rowsperpage":"10","records":8,"rows":[{"id":40184,"fqdn":"zen1.secnodes.com","home":"ts1-testnet.na","start":"2018-05-02T17:06:40.000Z","check":"2018-06-13T22:03:22.000Z","end":null,"duration":3646602000,"etype":"chalmax","nid":9},{"id":38572,...
Path: /api/nodes/my/challenges?key=<apikey>&page=<pagenumber>&rows=<rowcount>
Optional parameters:
&nid=<nodeid> return only for specified node. e.g. &nid=435
&result=<result> where <result> is 'pass' or 'fail'. e.g. &result=fail
Result: Challenge results for all nodes associated with the API key.
Sample:
"page":1,"total":320,"rowsperpage":"10","records":3199,"rows":[{"id":333694,"fqdn":"zen1.secnodes.com","home":"ts1-testnet.na","nid":9,"start":"2018-06-13T21:53:23.000Z","received":null,"reply":null,"run":null,"result":"wait","reason":null},{...
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' e.g. &status=exclude
Result: Payments and Credits for all nodes associated with the API key. The type is 'e' for earnings and 'c' for credit
Sample:
{"page":61,"total":91,"rowsperpage":"10","records":903,"rows":[{"id":243031,"status":"exclude","startdate":"2017-12-13T12:32:32.000Z","enddate":"2017-12-13T18:55:17.000Z","pmid":496,"type":"e","uptime":"0.7774","zen":"0.00000000","created":"2017-12-13T19:24:24.000Z","paidat":null,"txid":null},{"id":241495,"status":"paid","startdate":"2017-12-13T12:32:32.000Z","enddate":"2017-12-13T18:55:17.000Z","pmid":496,"type":"e","uptime":"1.0000","zen":"0.12304688","created":"2017-12-13T19:23:38.000Z","paidat":"2017-12-24T04:05:22.000Z","txid":"8b5c47a8076add8b510ec3a4bd2af480614b9d1c488475594b406ec9ad199b5a"},{...