Cosmos SDK offers APIs for built-in modules using gRPC, REST, and Tendermint RPC. This project aims to provide simple REST APIs for data that default Cosmos SDK APIs can't provide.
This collection of custom APIs can be deployed as a Cloudflare Worker or compatible serverless platforms.
data-api.cheqd.io/supply/total (also has an API endpoint alias on /)
Just total supply of tokens, in main token denomination (CHEQ instead of ncheq in our case)
Cryptocurrency tracking websites such as CoinMarketCap and CoinGecko require an API endpoint for reporting the total supply of tokens in the main/primary token denomination.
While this figure is available from Cosmos SDK's built-in /cosmos/bank/v1beta1/supply/ncheq REST endpoint, this returns a JSON object in the lowest token denomination, which cannot be parsed by CoinMarketCap / CoinGecko.
data-api.cheqd.io/supply/circulating
Circulating token supply, in main token denomination (CHEQ instead of ncheq in our case)
Cryptocurrency tracking websites such as CoinMarketCap and CoinGecko require an API endpoint for reporting the circulating supply of tokens in the main/primary token denomination.
This figure is not available from any Cosmos SDK API, because the criteria for determining circulating vs "non-circulating" accounts is defined by CoinMarketCap.
This API calculates the circulating supply by subtracting the account balances of a defined list of wallet addresses ("circulating supply watchlist") from the total supply.
data-api.cheqd.io/supply/staked
Overall tokens staked, in CHEQ.
Provides the overall amount staked pulled from the block explorer.
data-api.cheqd.io/balances/vesting/<address>
Tokens that are still vesting for continuous/delayed vesting accounts, in CHEQ.
There is no Cosmos SDK API that returns balances that are yet to be vested for continuous or delayed vesting accounts.
data-api.cheqd.io/balances/vested/<address>
Tokens that have already vested for continuous/delayed vesting accounts, in CHEQ.
There is no Cosmos SDK API that returns balances that are already vested for continuous or delayed vesting accounts.
data-api.cheqd.io/balances/liquid/<address>
Tokens in continuous/delayed vesting accounts that can be converted to liquid balances, in CHEQ.
Tokens in continuous or delayed vesting accounts that can be converted to liquid balances. This is calculated as the sum of the following figures:
- "Delegated free" balance (from the
/cosmos/auth/v1beta1/accounts/<address>REST API) or vested balance, whichever is higher - "Available" balance (if applicable)
- "Reward" balance (if applicable)
data-api.cheqd.io/balances/total/<address>
Total account balance for specified account, in CHEQ.
The standard Cosmos SDK REST API for account balances returns JSON with the account balances along with its denomination, usually the lowest denomination. This is hard to parse in applications such as Google Sheets (e.g., to monitor the account balance by fetching a response from a REST API directly in Google Sheets). This API returns a plain number that can be directly plugged into such applications, without having to parse JSON.
- Results filtered by threshold value:
data-api.cheqd.io/arbitrage - Unfiltered results:
data-api.cheqd.io/arbitrage/all
Returns current price of CHEQ token among different markets along with an evaluation of whether they are at risk of arbitrage opportunities.
The CHEQ token trades on multiple markets/exchanges (e.g., Osmosis, Gate.io, BitMart, LBank, Uniswap). This is typically established as CHEQ along with another token pair or currency.
Fluctuations in the exchange rate between CHEQ and other tokens pairs can give rise to opportunities for arbitrage. Having a significant market arbitrage among different exchanges creates a market inefficiencies. Extreme market inefficiencies result market failure and deadweight loss.
Having monitoring capabilities for arbitrage gives opportunities for the cheqd community to rectify potential liquidity issues and aware of exchange rate movements.
To alert a significant market arbitrages for CHEQ listings on different exchanges, we pull latest markets data from the CoinGecko API for cheqd's ticker page via our Market Monitoring API Monitor Markets API. If an arbitrage threshold is exceeded, a webhook trigger is sent to Zapier for alerting via different channels (such as Slack).
This frontend site was developed to work with Cloudflare Workers, a serverless and highly-scalable platform.
Originally, this project was discussed as potentially being deployed using a serverless platform such as AWS Lambda. However, AWS Lambda has a cold-start problem if the API doesn't receive too much traffic or is only accessed infrequently. This can lead to start times ranging into single/double digit seconds, which would be considered an API timeout by many client applications.
Using Cloudflare Workers, these APIs can be served in a highly-scalable fashion and have much lower cold-start times, i.e., in the range of less than 10 milliseconds.
The recommended method of interacting with this repository is using Cloudflare Wrangler CLI.
Dependencies can be installed using Yarn or any other package manager.
npm installWhile our deployment uses Cloudflare Wrangler, the application itself could be modified to run on other platforms with some refactoring.
Wrangler CLI uses wrangler.toml for configuring the application. If you're using this for your own purposes, you will need to replace values for account_id, Cloudflare KV bindings, route, etc. for the application to work correctly along with your own Cloudflare API tokens.
The application expects these environment variables to be set on Cloudflare:
TOKEN_EXPONENT: Denominator for token (default9for CHEQ token).REST_API: REST API for a Cosmos/cheqd node to target for queries.REST_API_PAGINATION_LIMIT: Number of results to fetch in a single query, for queries that require iterating multiple times. (E.g., many account balance queries require this, to be able to get all delegations etc.)GRAPHQL_API: GraphQL API for a BigDipper explorer instance for some queries. E.g., the GraphQL API for cheqd's block explorer ishttps://explorer-gql.cheqd.io/v1/graphql.CIRCULATING_SUPPLY_GROUPS: Number of sub-groups the circulating supply watchlist is split into (see sample JSON file below). This is to ensure that any lookups from APIs can be spaced out.MARKET_MONITORING_API: Upstream API for running queries from CoinGecko API (see the market-monitoring repository).WEBHOOK_URL: Zapier webhook URL to send market monitoring data to. Since this is a secret, it's not set in plaintext inwrangler.tomlbut passed via GitHub Actions secrets.
Cached data for computationally-expensive queries are stored in Cloudflare KV.
CIRCULATING_SUPPLY_WATCHLIST: This KV is pre-populated with a list of addresses to monitor for circulating supply. Initially, the value portion of this can be set to anything, since it will get replaced when periodic cron triggers run to set the account balance breakdown for this account. In case you have a lot of accounts to monitor, we recommend prefixing the key with agroup_Nprefix which will stagger the API lookup across multiple cron executions.
// Sample watchlist JSON file structure
[
{
"key": "group_1:cheqd1...xxx", // Group 1 prefix
"value": "26-May-2022" // This can be any value, and will be updated with account balance breakdown periodically
},
{
"key": "group_2:cheqd1...xxx", // Group 2 prefix
"value": "26-May-2022"
}
]Tip: There are online converter tools to transform CSV files to JSON files, which is an easy way of converting spreadsheets to JSON.
Entries can bulk-uploaded to Cloudflare KV using Wrangler CLI:
wrangler kv:bulk put <watchlist-file.json> --binding "CIRCULATING_SUPPLY_WATCHLIST" --preview falseEntries can bulk-deleted from Cloudflare KV using Wrangler CLI by providing a JSON file with list of keys to delete. This JSON file should be in the form ["key1", "key2", ...].
wrangler kv:bulk delete <watchlist-delete.json> --binding "CIRCULATING_SUPPLY_WATCHLIST" --preview falseWrangler CLI can serve a preview where the code and KV pairs are served from Cloudflare. This also automatically executes a build to be able to serve up the app.
wrangler devThis option will bind itself to the preview_id KV namespace binding (if defined).
Wrangler CLI also allows a degree of local development by running the web framework locally, but this option still relies on Cloudflare backend for aspects such as Cloudflare Workers KV.
wrangler dev --localIf you want completely standalone local development, this can achieved using an emulator framework like Miniflare.
Modify the required variables in wrangler.toml for publishing to Cloudflare Workers and execute the following command to execute a build and production deployment.
wrangler publishOther environments can be targetted (if defined in wrangler.toml) by specifying the --env flag:
wrangler publish --env stagingCI/CD deployments can be achieved using the wrangler Github Action. The deploy.yml Github Action in this repo provides an example of this can be achieved in practice.
If you notice anything not behaving how you expected, or would like to make a suggestion / request for a new feature, please create a new issue and let us know.
The cheqd Community Slack is our primary chat channel for the open-source community, software developers, and node operators.
Please reach out to us there for discussions, help, and feedback on the project.
