Comment on page
MarketCap API
The purpose of MarketCap API is to provide API endpoints for queries that need responses in bespoke formats required by a particular client or set of clients. The motivation for this software is primarily to provide an API for market cap aggregator sites, who in general do not specialize their queries for each project but instead require the projects conform to their own request standards. Towards that end, the Marketcap API is a simple and concise REST API that supplies data on max and circulating supply and token rich lists, and could be extended to include other queries. Responses are structured to conform to the requirements of each market cap aggregator site that is served. This API is not intended for general public use, nor does it offer a comprehensive set of queries. In particular, it is not suited for use as a block explorer. Rather, it is for automated polling by a limited number of aggregator sites or statistics recording services, or other special purposes for which a custom API format is needed.
Functionally, the MarketCap API is a wrapper or "facade" that sits in front of the Peerplays core public API nodes, and and simply reformats the responses to fit the needs of the clients served.
Installation and setup instructions are detailed in the project's README, but a summary of the steps is as follows:
- 1.Execute the below CLI in the terminal on the machine on which you will run the service:
git clone https://gitlab.com/PBSA/peerplays-1.0/tools-libs/marketcap-api.git
cd marketcap-api
virtualenv env
source env/bin/activate
pip install -r requirements.txt
cd conf
cp -i explorer-conf-sample.yaml explorer-conf.yaml
nano explorer-conf.yaml # Edit configuration
cd ..
- 2.Edit
conf/explorer-conf.yamlThe API needs the URL of a Peerplays core node API with assets API enabled. Note that the assets API is not enabled by default. For instructions on enabling it, see NEX - Blockchain API configuration.
# explorer-conf-sample.yaml
#
# Copy to explorer-conf.yaml and edit.
#
# Where can we find a Peerplay API node with "asset" API open?
peerplays-api-node: wss://testnet.peerplays.download/api
# Where should this API listen?
listen-host: 0.0.0.0
listen-port: 8123
# URL prefix for all endpoints?
# e.g. "/api" or "/api/v1". Can be empty "" if none.
# Note: should match basePath in swagger.yaml
url-prefix: "/api"
The MarketCap API is a simple python3 script. Execute it with the below CLI commands to activate the interface.
source env/bin/activate
python3 ./cmc-api.py
It is a good idea to run the API in some form of persistent session manager, such as a GNU Screen session, or PM2. The latter, if configured correctly, can even enable automated restart on system reboots.
The API is explained via a Swagger-UI interface, which documents each available API call as well as its parameters and return values. Swagger is an interactive API documentation that also lets you "try out" the API calls. It will give you a
curl command that you can run to query the API, and also show you the results of a live query right in the interface.After running the API, point a browser at http://[host]:[port]/api/docs to access the UI.
In the case of the API maintained for Peerplays by the PBSA, the UI can be explored here: http://marketcap.peerplays.download/api/docs
Click the below browser link to access the UI,
API doc
The swagger link to check the query
The below images will showcase the interface for one of the API calls in swagger. The Asset ID is vital to get the output.
Drop down option to execute Supply API Call
Click on the Try it out option to execute the API Call,
Click "Execute" to perform API call
Click the Execute button to run the API call and the output for the respective API call will be listed below. The sample output is provided below,
The response for any API call consists of two methods to get the output,
- 1.Curl command - It uses "GET" command as CLI to retrieve the output in the terminal.
- 2.Requested URL - The URL will be generated for the executed API call. Paste the URL in the browser and click Enter to get the plain text output in the browser.
The output for CURL and plain text URL is attached below (respectively),
CURL output
Plain Text URL output
There are three categories of API calls featured in the swagger,
- 1.Supply
- 2.Plain-text supply
- 3.Rich list
The command retrieve the complete supply data of an asset using the Asset ID in JSON format. The supply data includes total, maximum, and circulating value of an asset.
Curl Command
curl -X 'GET' \
'http://marketcap.peerplays.download:80/api/supply?asset=<Asset ID>' \
-H 'accept: application/json'
Plain text URL
http://marketcap.peerplays.download:80/api/supply?asset=<Asset ID>
Parameters
Return
Results
Asset ID: The Asset ID or token symbol of the account
Return the total, maximum, and circulating value of an asset in JSON format
Response body
{
"id": "1.3.0",
"symbol": "PPY",
"maximum": "14460519.93031",
"total": "14460519.93031",
"circulating": "5901757.32564"
}
Response headers
connection: keep-alive content-length: 120 content-type: application/json date: Fri,30 Jun 2023 10:37:03 GMT server: nginx/1.18.0 (Ubuntu)
Request duration
108 ms
The max_supply API call will return the maximum number of coins or token that has ever been created for any asset. Once the maximum supply is reached there cannot be any new coins/token that can be mined, minted or produced. the output is as a fixed point plain text using Asset ID as parameter.
Curl Command
curl -X 'GET' \
'http://marketcap.peerplays.download:80/api/max_supply?asset=<Asset ID>' \
-H 'accept: application/text'
Plain text URL
http://marketcap.peerplays.download:80/api/max_supply?asset=<Asset ID>
Parameters
Return
Results
Asset ID: The Asset ID or token symbol of the account
Return the maximum number of coins/token created for the asset.
Response body 14460519.93031 Response headers connection: keep-alive content-length: 14 content-type: text/plain; charset=utf-8 date: Fri,30 Jun 2023 10:25:40 GMT server: nginx/1.18.0 (Ubuntu) Request duration 481 ms |
The total_supply API call will return the cumulative supply of coins or tokens of a specific asset that has been created/mined which includes locked/reserved asset. The output is the plain text fixed number using Asset ID as parameter.
Curl Command
curl -X 'GET' \
'http://marketcap.peerplays.download:80/api/total_supply?asset=<ASSET ID>' \
-H 'accept: application/text'
Plain text URL
http://marketcap.peerplays.download:80/api/total_supply?asset=<ASSET ID>
Parameters
Return
Results
Asset ID: The Asset ID or token symbol of the account
Return the total supply of coins or token of a specific asset.
Response body
14460519.93031
Response headers
connection: keep-alive content-length: 14 content-type: text/plain; charset=utf-8 date: Fri,30 Jun 2023 10:32:53 GMT server: nginx/1.18.0 (Ubuntu)
Request duration
248 ms
The circulating_supply API call returns the total number of coins or token actively available for trade. The output is the plain text fixed number using the asset ID as parameter.
Curl Command
curl -X 'GET' \
'http://marketcap.peerplays.download:80/api/circulating_supply?asset=<Asset ID>' \
-H 'accept: application/text'
Plain text URL
http://marketcap.peerplays.download:80/api/circulating_supply?asset=<Asset ID>
Parameters
Return
Results
Asset ID: The Asset ID or token symbol of the account
Return the total number of coins or tokens actively available for an asset.
Response body
5901757.32564
Response headers
connection: keep-alive content-length: 13 content-type: text/plain; charset=utf-8 date: Fri,30 Jun 2023 10:36:52 GMT server: nginx/1.18.0 (Ubuntu)
Request duration
464 ms
The top_balances API call will return the top holders of asset for the asset ID with the given number of counts to return the holders.
Curl Command
curl -X 'GET' \
'http://marketcap.peerplays.download:80/api/top_balances?asset=<Asset ID>&num=<Number>' \
-H 'accept: application/json'
Plain text URL
http://marketcap.peerplays.download:80/api/top_balances?asset=<Asset ID>&num=<Number>
Parameters
Return
Results
Asset ID: The Asset ID or token symbol of the account
Number: Number of top holders to return for the given asset ID
Return the list of top holders of an asset.
Response body
[
{
"name": "q-anon",
"account_id": "1.2.12784",
"balance": "177275.29265",
"symbol": "PPY"
},
{
"name": "livecoin.net",
"account_id": "1.2.10568",
"balance": "142345.32445",
"symbol": "PPY"
},
{
"name": "ppy-holdings",
"account_id": "1.2.12308",
"balance": "110003.22036",
"symbol": "PPY"
},
{
"name": "peerplaysassets1",
"account_id": "1.2.12312",
"balance": "103203.02072",
"symbol": "PPY"
},
{
"name": "rudex-gateway",
"account_id": "1.2.10951",
"balance": "100893.17481",
"symbol": "PPY"
},
{
"name": "williamhill1934",
"account_id": "1.2.8821",
"balance": "85302.57246",
"symbol": "PPY"
},
{
"name": "assetclass92",
"account_id": "1.2.12313",
"balance": "85002.48709",
"symbol": "PPY"
},
{
"name": "asset-block",
"account_id": "1.2.12310",
"balance": "84902.48416",
"symbol": "PPY"
},
{
"name": "azzytota007",
"account_id": "1.2.9802",
"balance": "80527.78974",
"symbol": "PPY"
},
{
"name": "holding-co",
"account_id": "1.2.12314",
"balance": "80002.34074",
"symbol": "PPY"
},
{
"name": "tompool1",
"account_id": "1.2.11897",
"balance": "70629.08105",
"symbol": "PPY"
},
{
"name": "pew-die-pie",
"account_id": "1.2.8817",
"balance": "66902.95941",
"symbol": "PPY"
},
{
"name": "globalholdings1903",
"account_id": "1.2.12316",
"balance": "65901.92775",
"symbol": "PPY"
},
{
"name": "fbingbing81",
"account_id": "1.2.8813",
"balance": "65470.41728",
"symbol": "PPY"
},
{
"name": "boukhyar1",
"account_id": "1.2.9758",
"balance": "57286.92662",
"symbol": "PPY"
},
{
"name": "crypto-boss",
"account_id": "1.2.10496",
"balance": "54194.05184",
"symbol": "PPY"
},
{
"name": "joycho128",
"account_id": "1.2.8815",
"balance": "52103.52277",
"symbol": "PPY"
},
{
"name": "bts-figaro34",
"account_id": "1.2.6868",
"balance": "50401.48402",
"symbol": "PPY"
},
{
"name": "h92r",
"account_id": "1.2.8814",
"balance": "47702.77159",
"symbol": "PPY"
},
{
"name": "idax-deposit",
"account_id": "1.2.13285",
"balance": "46261.38130",
"symbol": "PPY"
}
]
Response headers
connection: keep-alive content-length: 1900 content-type: application/json date: Fri,30 Jun 2023 10:51:43 GMT server: nginx/1.18.0 (Ubuntu)
Request duration
264 ms