To celebrate Tezos' 2nd anniversary 🚀🎉 we release an upgrade to our core Tezos API which makes it even more powerful. This upgrade will go live across all our main and testnet APIs one week from now on July 10, 2020 at 12:00 PM UTC. Please read the changelog and test your integrations against api.staging.tzstats.com. Let us know if you find any issues. We're here to help you migrate smoothly.

As you might have seen, we upgraded our Tezos block explorer to version 2 recently. Maybe you saw all the shiny new features like the extended operation lists, voter dictionary, account rankings or new batch operations, and maybe you also wondered how you can access all that data. Introducing: version v006-2020-06-24 of the Tezos API.

Our aim with this release is to improve user experience and stability for everybody. We're also fixing several bugs, correct the way end-of-cycle snapshots are calculated, and how missed rewards are counted. To handle the quickly growing request volume we're optimizing a few of the most heavily used API endpoints and replacing/deprecating a few expensive ones.

What's new on the Tezos API

The most important change is that we begin migrating operation listings on explorer endpoints from embedded arrays inside accounts/blocks to stand-alone arrays. Both flavors will remain available in parallel for a while. We invite you to migrate already now to avoid headaches when we remove the old endpoints in a future API upgrade. A full list of changes is available in the changelog.

// New and faster way of fetching operations (same for block operations)
GET /explorer/account/tz1W1en9UpMCH4ZJL8wQCh8JDKCZARyVx2co/operations
[{
    hash: "onpagk3fSDe6UwbJEafgxT4sKwpgKH8YcXUXib6mE2cFUPRi5b7"
    ...
}]

// Deprecated way of fetching operations
GET /explorer/account/tz1W1en9UpMCH4ZJL8wQCh8JDKCZARyVx2co/op
{
    address: "tz1W1en9UpMCH4ZJL8wQCh8JDKCZARyVx2co",
    ...
    ops: [{
        hash: "onpagk3fSDe6UwbJEafgxT4sKwpgKH8YcXUXib6mE2cFUPRi5b7"
        ...
    }]
}

Below is a list of all the new features we added to the API. Most of them were inspired by our new block explorer and we think you will find them extremely useful too.

  • new explorer endpoint /explorer/account/{hash}/operations (replaces embeds on ../ops)
  • new explorer endpoint /explorer/block/{hash}/operations (replaces embeds on ../ops)
  • new explorer endpoints /explorer/rank/balances (rich list), /explorer/rank/traffic (1D transaction counts), /explorer/rank/volume (1D transaction volume)
  • new explorer endpoint /explorer/election/:id/:stage/voters to list all voters, whether they voted already and the ballot they cast
  • new explorer endpoint /explorer/election/:id/:stage/ballots to list all ballots from a voting period
  • account: new explorer fields avg_luck_64, avg_performance_64, avg_contribution_64, baker_version, delegate_until and delegate_until_time
  • account: new table fields next_bake_height, next_bake_priority, next_bake_time, next_endorse_height, next_endorse_time that will be set for active bakers
  • cycle: new explorer fields snapshot_time, active_bakers and active_delegators for a total number of all registered bakers and funded delegators at cycle snapshot
  • rights: new flag is_bond_miss to differentiate loss events between low bonds and other failures
  • operation: delegation operations now have volume field set to the initial delegated balance
  • operation: new fields is_batch and batch_volume on first operation in an explorer batch list
  • operation: bake and unfreeze implicit operations now contain the baker as sender and receiver to allow listing bake/endorse/unfreeze ops with a single operation table call
  • operation: added implicit baker registrations in protocols v001 (due to a protocol bug) and v002 (at migration)

Breaking Changes

We renamed, moved, or updated the type of a few fields. If you are using any of the fields listed below, please update your clients.

  • block: nonce is now returned as hex string
  • cycle: renamed active_{bakers|endorsers} to working_{bakers|endorsers}, also note the change in meaning of active_bakers as described below
  • account: we're now hiding unused baker fields from non-baker accounts
  • account: renamed explorer and table field flow_rank to volume_rank
  • account: moved call_stats from account table to contract table
  • account: changed /explorer/account/{hash}/ballots return value from an account object with embedded ballots field to a ballots array

Using the Table API for Bulk Access

We always encourage our users to learn how to optimize request patterns. One obvious way to save on the number of calls and get results faster is by using the Table API. Explorer endpoints are handy but slow. They always deliver a complete view of individual objects and paged collections. It feels natural to use them because they return regular JSON objects/arrays, but there is an added transfer cost because object keys are repeated and you can only access one account or one block at a time.

For cheaper and faster access, especially if you need to crawl many accounts, operations or blocks on a regular basis, consider using Table API endpoints. Table access streams the responses to you row-by-row. You can limit the amount of data to those fields you really need and you can fetch a lot of rows at once, up to 50,000 per request. For example, to get account data for all active bakers in a single request, you call:

https://api.staging.tzstats.com/tables/account?is_active_delegate=1

The response is an array of arrays. We call it JSON bulk array. The order of elements is exactly the order of columns you requested or a default order. Remember, as we keep adding new fields to tables and also time-series the default column order may change between API versions. To ensure you always get the fields you expect, use the columns query argument. The order of columns you specify is exactly the order that's returned. Learn more about table access and table filters in our API docs.

We're hiring

If you are an experienced systems engineer who shares our passion for optimization, clean software architecture and secure, reliable code — let's talk. You can reach me at alex@blockwatch.cc.