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
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 same 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 total 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>
Note: The category field is limited to 60 characters.
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, "downtimes":[{"id":15358684, "dtype":"zend" ,"start":"2018-05-02T23:14:50.000Z", "check":"2018-05-02T23:16:37.000Z", "end":null}], "category":"mynodes"}
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}}
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". . .
Note: The category field is limited to 60 characters.
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
&cat=<category> where <category> is the optional value entered when setting up a node
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
&cat=<category> where <category> is the optional value entered when setting up a node
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 'wait', 'confirm', 'pass' or 'fail'. e.g. &result=fail
&cat=<category> where <category> is the optional value entered when setting up a node
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' 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.