Do you use the TzStats API in your projects? Help us do a better job by sending your feedback and feature requests on Discord.

The TzStats API serves data to a diverse and rapidly growing number of users across the Tezos ecosystem. Every day we deliver 1.6M+ API calls and 4GB+ of data. We are very happy and grateful for this success and continue our mission to bring the best-of-class data products in the blockchain space to Tezos.

In this blog post I'll explain how we handle new releases and the removal of deprecated features from our public data APIs. I'll also talk about what you need to know about licensing our API data.

There are two independent reasons for upgrades:

  1. We may add new features or update existing features to support broader use cases.
  2. Updates to the Tezos protocol may require changes to how we handle on-chain data.

While new features are more or less optional (if you don't need them, you should not be required to upgrade), protocol upgrades are mandatory (everybody needs to upgrade to continue using Tezos). We try to deploy breaking changes only on protocol upgrades to limit the amount of effort you need to invest to stay up-to-date. We also try to keep legacy features around if they are required to reference historic data.

Tezos Network Support

TzStats operates different APIs across several Tezos networks. The official production API at api.tzstats.com is our stable version which serves Tezos mainnet data. A staging API exists at api.staging.tzstats.com which runs the latest cutting edge pre-release version. Staging helps you test your integrations with new features using live mainnet data and it helps us catch last minute bugs before a new official API release goes live.

For app development we provide additional APIs to all public Tezos testnets: Zeronet (more or less "nomadic labs' and friends' public development network") and protocol-specific testnets Babylonnet and Carthagenet.

Here's our current list of supported Tezos networks and the corresponding TzStats API endpoints:

Name Endpoint Current Protocol Version
Mainnet Production api.tzstats.com Babylon 2.0.1
Mainnet Staging api.staging.tzstats.com Babylon 2.0.1
Zeronet api.zeronet.tzstats.com Babylon 2.0
Babylonnet api.babylonnet.tzstats.com Babylon 2.0.1 (fixed)
Carthagenet api.carthagenet.tzstats.com v005/v006 (upgrade test)

You can detect and monitor which API version we run by observing the following HTTP response headers:

# API version header
X-Api-Version:	 v005-2019-11-01

# Network header (Tezos chain id)
X-Network-Id:    NetXdQprcVkpaWU

# Protocol Header (Tezos protocol hash)
X-Protocol-Hash: PsBabyM1eUXZseaJdmXFApDSBqj8YBfwELoxZHHW77EMcAbbwAS

Network and protocol hashes are supposed to help you avoid errors when processing data from unexpected environments. It's good practice to check them in your applications and scripts before processing a response.

Lifecycle Management

Our highest priority is to provide you with stable access to high-quality data. While the Tezos protocol upgrades at most once every 3 months we extend our APIs more rapidly. In the medium term we expect update cycles to slow down as our API matures and major uses-cases are sufficiently supported. For every update we do our best to make changes non-breaking. If they are we align such upgrades with Tezos protocol upgrades and give you advance notice to allow time for changing and testing your integrations.

TzStats API Evolution

We aim to publish a new stable API version once every month or less but at least with every protocol upgrade. When a feature is marked deprecated in one release it will be removed from the API in the next release. For a detailed list of changes see our staging API docs.

When we schedule a new stable API release we will first update our staging environment with a pre-release of the next version and give you notice about the upcoming change. Make sure to monitor our blog or Twitter for announcements. You will have about a week time to update your tools and services to prepare for breaking changes. If you find bugs please file an issue on Discord or Github and we'll fix it shortly. The upgrade will then officially go live at the announced date.

Brand new TzStats API features and test releases are rolled out to our testnets without prior notice. We aim to track the feature set of a new Tezos protocol testnet as close as possible. Support for upcoming protocols will be available at the end of a mainnet testing vote period (the 2nd governance period in a voting cycle). Difficult or poorly documented protocol changes may require longer time to implement. When Tezos mainnet eventually activates a new protocol, all protocol-specific testnets will cycle. That is, on the next upgrade to Carthage, Babylonnet will shut down shortly after the upgrade and Carthagenet will become the new mainnet-equivalent test infrastructure.

API Licensing

It's no secret that maintaining, improving and operating a data service is expensive. We're very much committed to helping the Tezos ecosystem grow, but we also like to manage expectations. Our data is licensed to you under Creative Commons Attribution-NonCommercial License CC BY-NC 4.0 which means that all TzStats data API's are free for non-commercial use only. Commercial use is tolerated and also free of charge right now, but will transition to a paid subscription model in the future.

We started working out the details and like to stay transparent on the way. We also like to listen to your feedback, that's why we share our plans already now.

  • Non-commercial use will stay free forever, although data history may be limited.
  • If you use our APIs as part of your business or if you use our data to make money you will need a paid subscription.
  • Most of our real-time on-chain data and summaries will remain available in a free usage tier, although we will require you to sign up for a free API key.
  • Small bakers who help decentralize and secure the network will fall under non-commercial use and can continue to use all data for free (we'll be looking at delegation counts and staking balances to determine eligibility).

To start the migration process we will introduce API keys and multiple tiers of rate limits with an upcoming API release in 2020, potentially coinciding with v007 or v008 mainnet release. Subscriptions will probably cost a flat monthly fee for data access in a range comparable to well known Ethereum and Bitcoin data services.

If you're using TzStats data in your project today, please remember to attribute us. If you build software for use by others please inform your users about our data license and let them know they may require their own license in the future.

Thanks for watching and stay tuned for the upcoming API release.