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
anddelegate_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
andactive_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 havevolume
field set to the initial delegated balance - operation: new fields
is_batch
andbatch_volume
on first operation in an explorer batch list - operation:
bake
andunfreeze
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}
toworking_{bakers|endorsers}
, also note the change in meaning ofactive_bakers
as described below - account: we're now hiding unused baker fields from non-baker accounts
- account: renamed explorer and table field
flow_rank
tovolume_rank
- account: moved
call_stats
from account table to contract table - account: changed
/explorer/account/{hash}/ballots
return value from an account object with embeddedballots
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.