Tezos API
Current Version
v016-2023-02-26
API Endpoints
Mainnet: https://api.tzstats.com
Mainnet Staging: https://api.staging.tzstats.com
Ghostnet: https://api.ghost.tzstats.com
Mumbainet: https://api.mumbai.tzstats.com
RPC Endpoints
Mainnet: https://rpc.tzstats.com
Mainnet Staging: https://rpc.staging.tzstats.com
Ghostnet: https://rpc.ghost.tzstats.com
Limanet: https://rpc.lima.tzstats.com
Mumbainet: https://rpc.mumbai.tzstats.com
TzStats provides a powerful Tezos API to access fully indexed on-chain data and statistics collected from the Tezos blockchain. Supported by Blockwatch Data and ready to use without permission for non-commercial projects. To inquire about commercial use send an email to license@blockwatch.cc.
This API reference provides information on all public API endpoints and how to call them. Access does not require authentication and we do not enforce rate limits right now, but we monitor usage and may apply individual limits to guarantee fair use for everybody.
The TzStats Tezos API supports different kinds of endpoints:
- explorer detailed on-chain data objects like blocks, accounts, operations, votes
- table for bulk lists and when you need to process large quantities of data
- series for aggregate counters and statistics as time-series
- metadata for off-chain and on-chain metadata
- markets for off-chain and on-chain asset prices
TzStats SDKs
Official client libraries for TzStats are currently available for
- Golang: TzStats-Go
- Golang: TzGo (low-level Tezos tools)
Calling the API
Our Tezos API is read-only at the moment, i.e. the only supported HTTP methods are GET
, HEAD
and OPTIONS
. Query parameters must be properly URL encoded and appended as query arguments.
For high-speed high-volume access, always use the table API endpoints. Table and time-series endpoints stream data and have higher limits, that is, they immediately return response headers after accepting and validating a request and then stream rows or aggregated data points as they are fetched from the underlying database.
Transport Security
All our certificates are signed by LetsEncrypt Authority X3 certificate.
Available ciphers are
ECDHE-ECDSA-AES256-GCM-SHA384
ECDHE-ECDSA-CHACHA20-POLY1305
ECDHE-ECDSA-AES128-GCM-SHA256
ECDHE-ECDSA-AES256-SHA384
ECDHE-ECDSA-AES128-SHA256
ECDHE-RSA-AES256-GCM-SHA384
ECDHE-RSA-CHACHA20-POLY1305
ECDHE-RSA-AES128-GCM-SHA256
ECDHE-RSA-AES256-SHA384
ECDHE-RSA-AES128-SHA256
The API supports secure connections via TLS v1.3 and v1.2 with Perfect Forward Secrecy based on Elliptic Curves and Diffie-Hellman key exchange. Insecure HTTP requests to port 80 are automatically redirected to HTTPS on port 443.
Tezos API Response Headers
All our API responses are tagged with an API version that’s included in the X-Api-Version
HTTP header field as well as the Tezos network id and protocol.
Current TzStats Mainnet Response Headers
# API version
X-Api-Version: v016-2023-02-26
# Tezos Network (chain id)
X-Network-Id: NetXdQprcVkpaWU
# Tezos Block Height
X-Chain-Height: 3264956
# Tezos Protocol (protocol hash)
X-Protocol-Hash: PtLimaPtLMwfNinJi9rCfDPWea8dFgTZ1MeJ9f1m2SRic6ayiwW
CORS
TzStats Data API supports cross-origin HTTP requests, commonly referred as CORS. This means that you can call the API using Javascript from any browser. Right now CORS support is limited to localhost and the tzstats.com domain. Send a request to tzstats@blockwatch.cc if you have an interesting use case and like to get whitelisted.
Rate Limits
We do not enforce limits on the number of calls or the amount of data you can query from the API. We do, however, use SPAM protection measures that limit the number of connection attempts and HTTP calls over short time-frames. Try to slow down your call rate if you start seeing 429 status codes. Be responsible with calls and retries, this API is a shared resource for everybody.
Data Formats
Regular JSON Objects
{
"hash": "BLPUNqkikFAbNDekUhiqJrCaao86o6sPNq5YrcGobHMzSPi4XWr",
"predecessor": "BM6xrDirVQLYf5KkU7ZFbTdhzxe8Hn9k2K1rR7bmByfcv75dzcu",
"baker": "tz1XfAjZyaLdceHnZxbMYop7g7kWKPut4PR7",
"height": 626158,
"cycle": 152
}
Compact JSON Arrays
[
[
"BMRdcMqU63QiXmU8vLE7a2qBES1kRX46mTDEGYEUsFV8uL4PDkd",
"tz1isXamBXpTUgbByQ6gXgZQg4GWNW7r6rKE",
626160,
152
],[
"BLhhgCSR8Avhbc7hrqQ9uSsB9Adfts2NwqZbzrGS5VCjxQdLX5N",
"tz1coHzgoQYRu1Ezn5QChfFEjwTrBzGNQT6U",
626159,
152
],[
"BLPUNqkikFAbNDekUhiqJrCaao86o6sPNq5YrcGobHMzSPi4XWr",
"tz1XfAjZyaLdceHnZxbMYop7g7kWKPut4PR7",
626158,
152
]
]
Results are returned as Content-Type
JSON (RFC 7159) or CSV (RFC 4180). Select either format by appending .json
or .csv
to the query path.
CSV files always include a header containing the requested column names in the requested order. Columns are separated by comma (ASCII 44, UTF-8 0x2C).
When downloading a CSV file you may add an optional filename
query argument (ASCII only, 128 characters max, no path separators) which will be used in the Content-Disposition header. Suffix .csv
is automatically appended if missing.
Compact JSON Arrays
Large JSON results such as lists and time-series use a more optimized (less verbose) format. Instead of JSON objects with named key/value pairs we use nested arrays, i.e. two levels of keyless JSON arrays. An outer array contains result rows or data points. The inner arrays contain lists of columns in an order requested by the columns
query parameter.
Note: New API versions may add, rename or remove columns. Please always use the columns
argument to specify the exact list and order of columns you expect in the default. If a column is renamed or removed you will get an appropriate error message.
JSON Data Types
We use the following data types and encoding conventions throughout the API:
string | unstructured ASCII/UTF-8 text |
bytes | binary data encoded |
datetime | UTC timestamps as UNIX milliseconds, e.g. 1536246000000 or ISO 8601/RFC3339 strings 2018-09-06T15:00:00Z |
duration | signed 64bit integers with second precision |
boolean | a binary value, either as string or number true (1) or false (0) |
float64 | an IEEE-754 64-bit floating-point number |
int64 | a signed 64-bit integer (Range: -9,223,372,036,854,775,807 through 9,223,372,036,854,775,807) |
uint64 | an unsigned 64-bit integer (Range: 0 through 18,446,744,073,709,551,615) |
enum | enumerable values expressed as strings, usually used for types |
hash | on-chain hashes encoded as base58-check strings |
money | monetary quantities are expressed as float64 with 6 decimal points (the Tezos coin unit precision); market endpoints use 5 or more decimal points depending on the fiat or crypto pairs |
For efficiency reasons, timestamps in JSON bulk arrays are encoded as UNIX time at millisecond resolution. That is, value 0
represents Jan 1, 1970 00:00:00 UTC
. Timestamps in explorer responses and CSV output are encoded according to RFC 3339 (2018-09-06T08:07:38Z
) for convenience and human readability.
Timestamps in queries can be expressed in multiple ways:
- as RFC3339 string with any timezone
- as UNIX timestamp in seconds or milliseconds, so
1536246000
and1536246000000
are equal - as date without time, i.e.
2018
,2018-09
,2018-09-06
represents midnight at the first day of month and/or month of year - as static string such as
now
,today
, oryesterday
to reference a relative point in time - as static string expression with truncation and offset arguments against
now
, e.g.now/d
for start of today ornow/d-30d
for start of day 30 days ago (expressions supports
,m
,h
,d
)
Status Codes
The TzStats Data API responds with regular HTTP status codes in the 2xx
range to indicate success, in the 4xx
range to indicate client-side errors and in the 5xx
range to indicate backend errors. The response body contains additional information encoded as JSON object.
200 OK
Success400 Bad Request
Missing required fields of malformed request data, your fault404 Not Found
No such object405 Method Not Allowed
Unsupported request method409 Conflict
Resource state conflict429 Too Many Requests
Request limit exceeded500 Internal Server
Something went wrong, not your fault502 Bad Gateway
Your request has reached a timeout and was canceled, try to reduce the range of data in your request504 Gateway Timeout
Our backend is overloaded or down for maintenance, wait a while before retry
Error Responses
API Error Response
{
"errors": [
{
"code": 1007,
"status": 400,
"message": "incorrect request syntax",
"scope": "StreamTable",
"detail": "unknown column 'cycles'",
"request_id": "BW-a935b7fedf6beefcedc94e539cfe320cc551c5b3",
}
]
}
All error messages are JSON encoded. They contain fields numeric and human readable fields to help developers easily debug and map errors.
Fields | Description |
---|---|
status int |
The HTTP status code, duplicated for convenience. |
message string |
A textual representation of the error status. |
scope string |
The name of the API call that has failed. |
detail string |
A detailed text description of the error. |
code int |
An internal error code. |
request_id string |
Unique call id that helps us trace failed requests. |
Explorer API
Endpoint Overview
Endpoint (P = paginated, F = filtered) | | Comment
------------------------------------------|----|----------------------------
/explorer/status | | indexer status
/explorer/config/{id} | | blockchain config
/explorer/tip | | blockchain tip info
/explorer/protocols | | list of deployed protocols
/explorer/bakers | | baker list
/explorer/bakers/{hash} | | baker info
/explorer/bakers/{hash}/votes | P | baker proposals and ballots
/explorer/bakers/{hash}/endorsements | P | baker endorsements
/explorer/bakers/{hash}/delegations | P | baker delegations
/explorer/bakers/{hash}/income/{cycle} | | baker income for cycle
/explorer/bakers/{hash}/rights/{cycle} | | baker rights for cycle
/explorer/bakers/{hash}/snapshot/{cycle} | | baker snapshot for cycle
/explorer/block/{id} | | block info
/explorer/block/{id}/operations | PF | list block ops
/explorer/op/{hash} | | operation info
/explorer/account/{hash} | | account info
/explorer/account/{hash}/contracts | P | list deployed contracts
/explorer/account/{hash}/operations | PF | list account operations
/explorer/contract/{hash} | | smart contract info
/explorer/contract/{hash}/calls | PF | list contract calls
/explorer/contract/{hash}/script | | contract script
/explorer/contract/{hash}/storage | | current contract storage
/explorer/constant/{hash} | | global constant
/explorer/bigmap/{id} | | bigmap info
/explorer/bigmap/{id}/keys | P | list bigmap keys
/explorer/bigmap/{id}/values | P | list bigmap key/value pairs
/explorer/bigmap/{id}/{key} | | read single bigmap value
/explorer/bigmap/{id}/updates | P | list bigmap updates
/explorer/bigmap/{id}/updates/{key} | P | list bigmap key updates
/explorer/cycle/{id} | | cycle info
/explorer/election/{id} | | election info
/explorer/election/{id}/{stage}/voters | P | list voters
/explorer/election/{id}/{stage}/ballots | P | list ballots
/metadata/{hash}[/{id}] | | read account & token metadata
/metadata/schemas | | list metadata schema names
/metadata/schemas/{schema} | | read JSON schema definition
/markets | | list known markets
/markets/tickers | | list market tickers
/markets/{exchange} | | read exchange status
/markets/{exchange}/{market} | | read market status
/markets/{exchange}/{market}/ticker | | read single market ticker
Explorer endpoints serve individual large JSON objects and a few related lists. JSON objects use the typical JSON key/value structure and you cannot limit the contents of objects (i.e. they are always sent in full). CSV format is not supported here.
Most explorer endpoints take different kinds of path arguments to define the object to return. This can be:
- a regular
hash
for blocks, operations or accounts - the string
head
for the most recent on-chain object (e.g. the recent block or cycle) - a block
height
(a.k.a level in Tezos) - a sequence
number
for cycles and elections
Pagination and Sorting
List endpoints support pagination (e.g. to list historic transactions, contract calls, voters, etc). Two pagination methods are supported:
cursor
+limit
is the preferred method, it uses therow_id
of the last result as argument to efficiently skips to the next available objectoffset
+limit
is an optional but highly DISCOURAGED method because it is much less efficient, it takes the count of objects seen so far and skips them when retrieving more results (as the chain grows, using offset in combination with descending order may return duplicates; we therefore recommend using the cursor method)
Default value for limit is 20 results on explorer endpoints and 500 results on tables, maximum is 500 and 50,000. Results are always sorted by row_id
of the underlying table. Sort direction can be controlled by order
(asc, or desc). If you require sorting by a different field, you have to do this client-side.
Indexer Status
Example request.
curl "https://api.tzstats.com/explorer/status"
import (
"context"
"blockwatch.cc/tzstats-go"
)
// use default Mainnet client
status, err := tzstats.DefaultClient.GetStatus(context.Background())
Example response.
{
"mode": "sync",
"status": "synced",
"blocks": 626399,
"indexed": 626399,
"progress": 1
}
Returns the current indexer status, useful to check if the indexer is in sync with the blockchain.
HTTP Request
GET /explorer/status
HTTP Response
Field | Description |
---|---|
mode enum |
Chain crawling mode (sync = live monitoring). |
status enum |
Indexer status (connecting , syncing , synced , failed ). |
blocks int64 |
Most recent block height seen by the connected Tezos node. |
indexed int64 |
Most recent block height indexed. |
progress float |
Percentage of blocks indexed. |
Blockchain Config
Example request.
curl "https://api.tzstats.com/explorer/config/head"
import (
"context"
"blockwatch.cc/tzstats-go"
)
// use default Mainnet client
config, err := tzstats.DefaultClient.GetConfig(context.Background())
Example response.
{
"name": "Tezos",
"network": "Mainnet",
"symbol": "XTZ",
"chain_id": "NetXdQprcVkpaWU",
"deployment": 14,
"version": 14,
"protocol": "PtKathmankSpLLDALzWw7CGD2j2MtyveTwboEYokqUCP4a1LxMg",
"start_height": 2736129,
"end_height": 2981888,
"decimals": 6,
"minimal_stake": 6000,
"preserved_cycles": 5,
"blocks_per_cycle": 8192,
"minimal_block_delay": 30,
"delay_increment_per_round": 15
}
Fetches blockchain configuration parameters. This endpoint accepts head
and a block height
as path parameters, so you can access configurations of past protocols as well.
HTTP Request
GET /explorer/config/head
HTTP Response
The response contains most of the configuration fields of a regular Tezos blockchain node, enriched with some additional contextual data.
Field | Description |
---|---|
name string |
Blockchain name (Tezos ). |
symbol string |
Ticker symbol (XTZ ). |
network string |
Network name (e.g. Mainnet , or testnet name). |
chain_id hash |
Chain hash. |
deployment int64 |
Number of deployed protocols on this network. |
version int64 |
Protocol version number. |
protocol hash |
Protocol hash. |
start_height int64 |
Activation height of the protocol. |
end_height int64 |
Deactivation height of the protocol (0 if undefined). |
decimals int64 |
Decimal points of one coin unit. |
minimal_stake int64 |
Min amount of tez required to receive block voting rights. |
preserved_cycles int64 |
Number of cycles for freezing security deposits and rewards. |
blocks_per_cycle int64 |
Number of blocks per consensus cycle. |
minimal_block_delay int |
Expected time between blocks, replacement for time_between_blocks . |
delay_increment_per_round int |
Number of seconds extra wait time for each additional round. |
Blockchain Tip
Example request.
curl "https://api.tzstats.com/explorer/tip"
import (
"context"
"blockwatch.cc/tzstats-go"
)
// use default Mainnet client
tip, err := tzstats.DefaultClient.GetTip(context.Background())
Example response.
{
"name": "Tezos",
"network": "Mainnet",
"symbol": "XTZ",
"chain_id": "NetXdQprcVkpaWU",
"genesis_time": "2018-06-30T16: 07: 32Z",
"block_hash": "BM88piH4ePJz8NZyesqWKNgCyjU2aEhHBewjTQQbvVwydJZMNVN",
"timestamp": "2022-12-14T08: 28: 44Z",
"height": 2968360,
"cycle": 556,
"protocol": "PtKathmankSpLLDALzWw7CGD2j2MtyveTwboEYokqUCP4a1LxMg",
"total_accounts": 3052891,
"total_contracts": 132579,
"total_rollups": 0,
"funded_accounts": 2268900,
"dust_accounts": 675620,
"dust_delegators": 14381,
"total_ops": 377310841,
"delegators": 183766,
"bakers": 406,
"new_accounts_30d": 51541,
"cleared_accounts_30d": 5127,
"funded_accounts_30d": 34116,
"inflation_1y": 42122089.465996,
"inflation_rate_1y": 4.6849143381499445,
"health": 96,
"supply": {
"row_id": 2968360,
"height": 2968360,
"cycle": 556,
"time": "2022-12-14T08: 28: 44Z",
"total": 941222615.658965,
"activated": 742886141.731728,
"unclaimed": 21432456.280972,
"circulating": 919790159.377993,
"liquid": 847095718.32112,
"delegated": 606151239.727164,
"staking": 727177050.163093,
"shielded": 5.312,
"active_stake": 722310173.771745,
"active_delegated": 601420616.919612,
"active_staking": 720442618.53477,
"inactive_delegated": 4730622.807552,
"inactive_staking": 6734431.628323,
"minted": 178488402.955549,
"minted_baking": 68310177.018692,
"minted_endorsing": 106606270.71385,
"minted_seeding": 8834.875,
"minted_airdrop": 3700.007321,
"minted_subsidy": 3447782.5,
"burned": 1584385.309284,
"burned_double_baking": 228687.464089,
"burned_double_endorse": 31838.219485,
"burned_origination": 15729.62075,
"burned_allocation": 274129.821,
"burned_storage": 826976.10425,
"burned_explicit": 290759.575499,
"burned_seed_miss": 120649.290052,
"burned_absence": 86373.772524,
"burned_rollup": 0,
"frozen": 72694441.056873,
"frozen_deposits": 72694441.056873,
"frozen_rewards": 0,
"frozen_fees": 0,
"frozen_bonds": 0
},
"status": {
"mode": "sync",
"status": "synced",
"blocks": 2968361,
"finalized": 2968360,
"indexed": 2968360,
"progress": 1
}
}
Returns info about the most recent block, indexer status, protocol deployments and supply statistics.
HTTP Request
GET /explorer/tip
HTTP Response
Field | Description |
---|---|
name string |
Blockchain name (Tezos ). |
symbol string |
Ticker symbol (XTZ ). |
network string |
Network name (e.g. Mainnet , Ghostnet , Sandbox ). |
chain_id hash |
Chain hash. |
genesis_time datetime |
Genesis block timestamp. |
block_hash hash |
Current block hash. |
timestamp datetime |
Current block timestamp. |
height int64 |
Current block height (level). |
cycle int64 |
Current cycle. |
protocol hash |
Current active protocol. |
total_accounts int64 |
Number of on-chain accounts in existence. |
total_contracts int64 |
Number of deployed contracts. |
total_rollups int64 |
Number of deployed rollups. |
funded_accounts int64 |
Number of funded (non-zero) accounts. |
bakers int64 |
Current number of active bakers. |
delegators int64 |
Current number of delegators. |
dust_accounts int64 |
Number of funded accounts with balance < 0.01tez. |
dust_delegators int64 |
Current number of delegators with balance <0.01 tez. |
total_ops int64 |
Total number of on-chain operations. |
new_accounts_30d int64 |
Accounts created during the past 30 days. |
cleared_accounts_30d int64 |
Accounts emptied during the past 30 days. |
funded_accounts_30d int64 |
Accounts (re)funded (new and previously empty) during the past 30 days. |
inflation_1y money |
Absolute inflation in tez. |
inflation_rate_1y float |
Relative annualized inflation in percent. |
health int64 |
Blockchain and consensus health indicator with range [0..100] based on recent 128 blocks (priority, endorsements, reorgs). |
supply object |
Coin supply statistics at current block height. |
status object |
Indexer status, embedded for efficiency. |
Accounts
Example request for accounts.
curl "https://api.tzstats.com/explorer/account/tz1Z7eWGw18LqUgRqmDqNZFQx7f8GEHXRfT8"
import (
"context"
"blockwatch.cc/tzstats-go"
"blockwatch.cc/tzgo/tezos"
)
// get account data and embed metadata if available
a, err := tzstats.DefaultClient.GetAccount(
context.Background(),
tezos.MustParseAddress("tz1Z7eWGw18LqUgRqmDqNZFQx7f8GEHXRfT8"),
tzstats.NewAccountParams().WithMeta(),
)
Example response for accounts.
{
"row_id":301865,
"address":" tz1Z7eWGw18LqUgRqmDqNZFQx7f8GEHXRfT8",
"address_type":" ed25519",
"pubkey":" edpkudvMBDoh5mStcMEs6LC4GvTL6WQCvqCg4naMhcyYMGSJfamLy5",
"counter": 1735944,
"first_in": 533980,
"first_out": 535803,
"last_in": 2236180,
"last_out": 2236130,
"first_seen": 533980,
"last_seen": 2236180,
"first_in_time":" 2019-07-23T19:11:46Z",
"first_out_time":" 2019-07-25T02:43:09Z",
"last_in_time":" 2022-03-29T07:29:54Z",
"last_out_time":" 2022-03-29T07:03:44Z",
"first_seen_time":" 2019-07-23T19:11:46Z",
"last_seen_time":" 2022-03-29T07:29:54Z",
"total_received": 189175188.06929,
"total_sent": 189160697.126554,
"total_burned": 3044.679,
"total_fees_paid": 70.93894,
"total_fees_used": 0.12345,
"spendable_balance": 11375.324796,
"is_funded": true,
"is_activated": false,
"is_delegated": false,
"is_revealed": true,
"is_baker": false,
"is_contract": false,
"n_tx_success": 87719,
"n_tx_failed": 14,
"n_tx_out": 87719,
"n_tx_in": 1234,
"frozen_bond": 0,
"lost_bond": 0,
"metadata": {
"tz1Z7eWGw18LqUgRqmDqNZFQx7f8GEHXRfT8": {
"address":"tz1Z7eWGw18LqUgRqmDqNZFQx7f8GEHXRfT8",
"alias":{
"name": "Coinbase 1",
"kind": "exchange",
"logo": "coinbase.png"
},
"location": {
"country": "US"
},
"social": {
"twitter": "coinbase"
}
}
}
}
Provides information about the most recent state of an account. This endpoint works for regular accounts, bakers and smart contracts. Delegator accounts contain additional state information. Use meta
(boolean) to embed optional metadata. Missing boolean flags mean false.
HTTP Request
GET /explorer/account/{hash}
HTTP Response
Field | Description |
---|---|
row_id uint64 |
Unique account id. |
address hash |
Account address as base58-check encoded string. |
address_type enum |
Account address type ed25519 (tz1), secp256k1 (tz2), p256 (tz3), contract (KT1) or blinded (btz1). |
pubkey hash |
Revealed public key. |
counter int64 |
Unique sender account ’nonce’ value. |
first_in int64 |
Block height of first incoming transaction. |
first_out int64 |
Block height of first outgoing transaction. |
last_in int64 |
Block height of latest incoming transaction. |
last_out int64 |
Block height of latest outgoing transaction. |
first_seen int64 |
Block height of account creation. |
last_seen int64 |
Block height of last activity. |
first_in_time datetime |
Block time of first incoming transaction. |
first_out_time datetime |
Block time of first outgoing transaction. |
last_in_time datetime |
Block time of latest incoming transaction. |
last_out_time datetime |
Block time of latest outgoing transaction. |
first_seen_time datetime |
Block time of account creation. |
last_seen_time datetime |
Block time of last activity. |
creator hash contract-only |
Smart contract creator account. |
baker hash delegator-only |
Current baker if account is delegated. |
delegated_since int64 delegator-only |
Block height of most recent delegation. |
delegated_since_time datetime delegator-only |
Time of most recent delegation. |
total_received money |
Lifetime total tokens received in transactions. |
total_sent money |
Lifetime total tokens sent in transactions. |
total_burned money |
Lifetime total tokens burned in tez. |
total_fees_paid money |
Lifetime fees paid in tez. |
total_fees_used money |
Lifetime fees accrued from tx sent to this account or contract. |
unclaimed_balance money |
Currently unclaimed balance (for vesting contracts and commitments). |
spendable_balance money |
Currently spendable balance. |
is_funded bool |
Flag indicating the account is funded. |
is_activated bool |
Flag indicating the account was activated from a commitment. |
is_delegated bool |
Flag indicating the account is currently delegated. |
is_revealed bool |
Flag indicating the account has a revealed public key . |
is_baker bool |
Flag indicating the account is a registered baker. |
is_contract bool |
Flag indicating the account is a smart contract. |
n_tx_success int64 |
Lifetime total number of successful operations sent. |
n_tx_failed int64 |
Lifetime total number of operations that failed. |
n_tx_out int64 |
Lifetime total number of transactions sent. |
n_tx_in int64 |
Lifetime total number of transactions received. |
frozen_bond money |
Total rollup bond currently frozen. |
lost_bond money |
Total rollup bond lost due to slashing. |
metadata object meta-arg |
Embedded account metadata if available. Requires meta=1 argument. |
List Account Operations
Example request for account operation list.
curl "https://api.tzstats.com/explorer/account/tz1Z7eWGw18LqUgRqmDqNZFQx7f8GEHXRfT8/operations?limit=100&order=desc"
import (
"context"
"blockwatch.cc/tzstats-go"
"blockwatch.cc/tzgo/tezos"
)
// list operations sent and received by this account
ops, err := tzstats.DefaultClient.GetAccountOps(
context.Background(),
tezos.MustParseAddress("tz1Z7eWGw18LqUgRqmDqNZFQx7f8GEHXRfT8"),
tzstats.NewOpParams().WithLimit(100),
)
GET /explorer/account/{hash}/operations
Lists operations sent from and to an account (defaults to all types and ascending order). This endpoint supports pagination with cursor
or offset
and limit
. Use type
to filter for a specific operation type (e.g. transaction
).
To query for updates after a certain block use the optional argument since
(int64|hash) or simply use cursor
. Using block hash has the advantage that the query is reorg-aware, i.e. it throws a 409 error when the specified block has become orphan.
Transactions are ordered descending, i.e. the most recent transaction is first. To change the order use the optional order
(asc|desc) parameter. Use meta
(boolean) to add optional account metadata.
List Created Contracts
Example request for listing created contracts.
curl "https://api.tzstats.com/explorer/account/tz1UBZUkXpKGhYsP5KtzDNqLLchwF4uHrGjw/contracts"
import (
"context"
"blockwatch.cc/tzstats-go"
"blockwatch.cc/tzgo/tezos"
)
// list deployed contracts
contracts, err := tzstats.DefaultClient.GetAccountContracts(
context.Background(),
tezos.MustParseAddress("tz1UBZUkXpKGhYsP5KtzDNqLLchwF4uHrGjw"),
tzstats.NewAccountParams(),
)
GET /explorer/account/{hash}/contracts
Bakers
Example request for a single baker.
curl "https://api.tzstats.com/explorer/account/tz3RDC3Jdn4j15J7bBHZd29EUee9gVB1CxD9"
import (
"context"
"blockwatch.cc/tzstats-go"
"blockwatch.cc/tzgo/tezos"
)
// get account data and embed metadata if available
a, err := tzstats.DefaultClient.GetBaker(
context.Background(),
tezos.MustParseAddress("tz3RDC3Jdn4j15J7bBHZd29EUee9gVB1CxD9"),
tzstats.NewBakerParams().WithMeta(),
)
Example response for bakers.
{
"address": "tz3RDC3Jdn4j15J7bBHZd29EUee9gVB1CxD9",
"baker_since_time": "2018-06-30T17:39:57Z",
"grace_period": 472,
"baker_version": "409a3f3f",
"total_balance": 1447710.509997,
"spendable_balance": 461363.181134,
"frozen_balance": 1016362.024825,
"delegated_balance": 9273620.284011,
"staking_balance": 10721330.794008,
"active_stake": 10721330.794008,
"staking_capacity": 14344835.691344,
"deposits_limit": null,
"staking_share": 0.02,
"active_delegations": 8,
"is_full": false,
"is_active": false,
"events":{
"last_bake_height": 2234562,
"last_bake_block": "BL9SaC72zRzUBRshVf4dsdozng7CtHX9PmX6q5Cgy3ZV9PWPexn",
"last_bake_time": "2022-03-28T17:32:54Z",
"last_endorse_height": 2234624,
"last_endorse_block": "BMX3oDi8xXf8PU9fgriCRwfqieKUhAMBfS9gTPaDgPMk7HM6bQj",
"last_endorse_time": "2022-03-28T18:06:14Z",
"next_bake_height": 0,
"next_bake_time": "0001-01-01T00:00:00Z",
"next_endorse_height": 0,
"next_endorse_time": "0001-01-01T00:00:00Z"
},
"stats":{
"total_rewards_earned": 30014.695962,
"total_fees_earned": 6139.414466,
"total_lost": 0,
"blocks_baked": 72070,
"blocks_not_baked": 494,
"blocks_proposed": 72070,
"blocks_not_endorsed": 27866,
"slots_endorsed": 4503095,
"avg_luck_64": 10089,
"avg_performance_64": 9900,
"avg_contribution_64": 9898,
"n_baker_ops": 1708015,
"n_proposals": 0,
"n_ballots": 20,
"n_endorsements": 1705340,
"n_preendorsements": 0,
"n_nonce_revelations": 2645,
"n_double_bakings": 10,
"n_double_endorsements": 0,
"n_set_limits": 0
},
"metadata":{
"address": "tz3RDC3Jdn4j15J7bBHZd29EUee9gVB1CxD9",
"alias":{
"name": "Foundation Baker 1",
"kind": "validator",
"logo": "tf.png"
},
"baker":{
"status": "private",
"non_delegatable": true
},
"location":{
"country": "CH"
},
"social":{
"twitter": "TezosFoundation"
}
}
}
Provides detailed information about a baker account. Use meta
(boolean) to embed metadata, additional statistics and last/next baking/endorsing events which are more costly to query.
HTTP Request
GET /explorer/bakers/{hash}
HTTP Response
Common baker fields
Field | Description |
---|---|
address hash |
Baker address |
baker_since_time datetime |
Most recent registration timestamp |
grace_period int64 |
Grace period cycle at which the baker gets deactivated when inactive. |
baker_version string |
Git short hash of the Octez software version the baker was running when producing the most recent block (only blocks contain this info, so bakers with few rights may not see frequent updates) |
active_stake money |
Current stake counting towards baking rights, may be lower than staking balance when deposits limit is active. |
total_balance money |
Total own balance, locked and spendable. |
spendable_balance money |
Spendable balance |
frozen_balance money |
Sum of frozen balances (deposit, reward, fee) |
delegated_balance money |
Sum of all incoming delegations. |
staking_balance money |
Own plus delegated balance. |
staking_capacity money |
Amount of delegations the baker can accept before becoming overdelegated. Note that in Ithaca+ a baker can still be overdelegated when not enough security deposit is locked. Then delegators will not earn the expected income. |
deposits_limit money |
Current signalled setting for deposit limits. May be null which will use 10% of a baker’s total balance as deposit at start of next cycle. |
staking_share float |
A baker’s staking share in percent as fraction of all the network wide staking. |
active_delegations |
Number of funded delegators. |
is_full bool |
Flag indcating the baker’s capacity is reached. |
is_active bool |
Flag indicating the baker is actively participating in consensus and earning rewards. |
Baker event fields
Field | Description |
---|---|
last_bake_height int64 |
latest baked block height |
last_bake_block hash |
latest baked block hash |
last_bake_time datetime |
latest baked block timestamp |
last_endorse_height int64 |
latest endorsed block height |
last_endorse_block hash |
latest endorsed block hash |
last_endorse_time datetime |
latest endorsed block timestamp |
next_bake_height int64 |
next round 0 baking opportunity as block height |
next_bake_time datetime |
next round 0 baking opportunity as estimated timestamp |
next_endorse_height int64 |
next endorsing opportunity as block height |
next_endorse_time datetime |
next endorsing opportunity as estimated timestamp |
Baker statistics fields
Field | Description |
---|---|
total_rewards_earned money |
Sum of lifetime rewards earned |
total_fees_earned money |
Sum of lifetime fees earned |
total_lost money |
Sum of lifetime coins lost in punishments |
blocks_baked int64 |
Sum of lifetime blocks baked |
blocks_proposed int64 |
Sum of lifetime blocks proposed (in Ithaca+ baker and proposer may differ) |
blocks_not_baked int64 |
Number of blocks not baked although rights existed (previously called lost ). |
blocks_endorsed int64 |
Number of blocks endorsed. |
blocks_not_endorsed int64 |
Number of blocks not endorsed although rights existed (previously called missed ). |
slots_endorsed int64 |
Sum of lifetime slots endorsed |
avg_luck_64 float |
Average 64-cycle luck, consensus rights received below/above fair share relative to staking balance. |
avg_performance_64 float |
Average 64-cycle performance, realized rewards + fee income relative to expected max possible income based on rights allocated. |
avg_contribution_64 float |
Average 64-cycle contribution, i.e. number of consensus rights sucessfully used (participation in consensus). |
n_baker_ops int64 |
Number of baker operations sent. |
n_proposals int64 |
Voting proposals sent. |
n_ballots int64 |
Voting ballots sent. |
n_endorsements int64 |
Endorsements sent. |
n_preendorsements int64 |
Preendorsements sent (Ithaca+). |
n_nonce_revelations int64 |
Seed nonces sent. |
n_double_bakings int64 |
Double baking punishments received. |
n_double_endorsements int64 |
Double (pre)endorsing punishments received. |
n_accusations int64 |
Number of 2bake/2endorse ops sent as accuser. |
n_set_limits int64 |
Number of deposit limit ops sent. |
n_update_consensus_key int64 |
Number of consensus key changes. |
n_drain_delegate int64 |
Number of drain operations sent by an attacker. |
List Bakers
Example list requests.
# bakers
curl "https://api.tzstats.com/explorer/bakers"
# votes
curl "https://api.tzstats.com/explorer/bakers/tz1aRoaRhSpRYvFdyvgWLL6TGyRoGF51wDjM/votes"
# endorsements
curl "https://api.tzstats.com/explorer/bakers/tz1aRoaRhSpRYvFdyvgWLL6TGyRoGF51wDjM/endorsements"
# delegations
curl "https://api.tzstats.com/explorer/bakers/tz1aRoaRhSpRYvFdyvgWLL6TGyRoGF51wDjM/delegations"
# income
curl "https://api.tzstats.com/explorer/bakers/tz1aRoaRhSpRYvFdyvgWLL6TGyRoGF51wDjM/income/400"
# rights
curl "https://api.tzstats.com/explorer/bakers/tz1aRoaRhSpRYvFdyvgWLL6TGyRoGF51wDjM/rights/400"
# snapshot
curl "https://api.tzstats.com/explorer/bakers/tz1aRoaRhSpRYvFdyvgWLL6TGyRoGF51wDjM/snapshot/400"
import (
"context"
"blockwatch.cc/tzstats-go"
"blockwatch.cc/tzgo/tezos"
)
c := tzstats.DefaultClient
ctx := context.Background()
params := tzstats.NewBakerParams()
addr := tezos.MustParseAddress("tz3RDC3Jdn4j15J7bBHZd29EUee9gVB1CxD9")
// baker votes
votes, err := c.ListBakerVotes(ctx, addr, params)
// baker endorsements
endorsements, err := c.ListBakerEndorsements(ctx, addr, params)
// delegations
delegations, err := c.ListBakerDelegations(ctx, addr, params)
// baker income
income, err := c.GetBakerIncome(ctx, addr, 400, params)
// rights
rights, err := c.GetBakerRights(ctx, addr, 400, params)
// snapshot
snapshot, err := c.GetBakerSnapshot(ctx, addr, 400, params)
Example response for cycle rights.
{
"address": "tz1aRoaRhSpRYvFdyvgWLL6TGyRoGF51wDjM",
"cycle": 400,
"start_height": 1687553,
"baking_rights": "0000...0000",
"endorsing_rights": "ffff...ffff",
"blocks_baked": "00000...0000",
"blocks_endorsed": "fc1f...feef",
"seeds_required": "04000000020010040400102400000100",
"seeds_revealed": "04000000020010040400102400000100"
}
Example response for cycle snapshot.
{
"baking_cycle": 400,
"snapshot_height": 1631744,
"snapshot_cycle": 393,
"snapshot_time":" 2021-08-23T10:02:56Z",
"snapshot_index": 2,
"snapshot_rolls": 1412,
"staking_balance": 11296346.793394,
"own_balance": 1367345.986303,
"delegated_balance": 9929000.807091,
"n_delegations": 7,
"delegators": [{
"address": "KT1QuofAgnsWffHzLA7D78rxytJruGHDe7XG",
"balance": 6731138.546637,
"is_funded": true
},
// ...
]
}
Get a list of all active bakers, their current status and affiliation metadata. Optionally filter by status and country or get a random list of suggestions for a given account. This endpoint is supposed to be a simple to use listing feature for wallets and other dapps who like to enable delegation.
Filter Options
You can filter the baker list by the following criteria
Argument | Description |
---|---|
status enum |
Filter by baker status public , private , closing , closed . |
country enum |
Filter by baker country of operation (use ISO 3166-1 Alpha-2 country codes, that’s two uppercase letters like US, DE, FR) |
suggest address |
Return a suggested list of bakers for the given address (see below) |
cursor int |
Last baker id after which to continue listing, use for paging. |
limit int |
Max number of results to return (max 100). |
offset int |
Skip first N results, use for paging instead of cursor. |
List Baker Votes
GET /explorer/account/{hash}/votes
Lists all voting proposals and ballots operations the baker has sent.
List Baker Endorsements
GET /explorer/account/{hash}/endorsements
Lists all endorsement operations the baker has sent.
List Baker Delegations
GET /explorer/account/{hash}/delegations
Lists all delegation operations where this baker was set or removed as the baker of choice for a delegator.
Get Baker Cycle Income
GET /explorer/account/{hash}/income/{cycle}
Get income statistics for this baker at the specific cycle. Past cycles are final. Future cycles are available as soon as a shapshot was selected.
Get Baker Cycle Rights
GET /explorer/account/{hash}/rights/{cycle}
Get rights for this baker at the specific cycle. Rights are represented as bitsets containing a binary 1 where a right exists or was used for a block.
Get Baker Cycle Snapshot
GET /explorer/account/{hash}/snapshot/{cycle}
Get snapshot for this baker at the specific cycle. A snapshot contains info about staking status at the cycle’s snapshot block as well as a list of delegators with their balances at that block. In combination with cycle income, this info can be used to prepare baker payouts.
Operations
Example request.
curl "https://api.tzstats.com/explorer/op/opSrt7oYHDTZcfGnhNt3BzGrrCQf364VuYmKo5ZQVQRfTnczjnf"
import (
"context"
"blockwatch.cc/tzstats-go"
"blockwatch.cc/tzgo/tezos"
)
// get all members of the operation group identified by hash
opGroup, err := tzstats.DefaultClient.GetOp(
context.Background(),
tezos.MustParseOpHash("opSrt7oYHDTZcfGnhNt3BzGrrCQf364VuYmKo5ZQVQRfTnczjnf"),
tzstats.NewOpParams(),
)
Example response.
[{
"id":66314240022,
"hash": "opSrt7oYHDTZcfGnhNt3BzGrrCQf364VuYmKo5ZQVQRfTnczjnf",
"type": "transaction",
"block": "BL1PGezBat3BX1N2rnk1qycTJbCXdWJwYoGBChyeFyYJABGLyZ9",
"time": "2020-06-25T06:18:19Z",
"height": 1011875,
"cycle": 247,
"counter": 2187104,
"op_n": 22,
"op_p": 3,
"status": "applied",
"is_success": true,
"gas_limit": 15385,
"gas_used": 10207,
"storage_limit": 257,
"volume": 0.040128,
"fee": 0.001792,
"sender": "tz1Ywgcavxq9D6hL32Q2AQWHAux9MrWqGoZC",
"receiver": "tz1ijyJy2QncvgDKZJARDgPqEYVRk6yTE5d7",
"confirmations": 1224432
},
// ...
]
Returns info about a single operation or a list of related operations. Tezos supports batch operations (multiple operations sharing the same hash) and internal operations (created by smart contract calls in response to a transaction) this endpoint always returns an array of operation objects. In many cases this array contains one element only. Use the optional prim
(boolean) parameter to embed Michelson primitive trees with smart contract calls. Use meta
(boolean) to add optional account metadata.
HTTP Request
GET /explorer/op/{hash|id}
HTTP Response
Field | Description |
---|---|
id uint64 |
Global unique id. |
hash hash |
Operation hash. |
type enum |
Operation type. |
block hash |
Block hash at which the operation was included on-chain. |
time datetime |
Block time at which the operation was included on-chain. |
height int64 |
Block height at which the operation was included on-chain. |
cycle int64 |
Cycle in which the operation was included on-chain. |
counter int64 |
Unique sender account ’nonce’ value. |
op_n int64 |
Unique block event/operation counter. |
op_p int64 |
Tezos RPC operation list position (the op list can be deducted from the operation type). |
status enum |
Operation status applied , failed , backtracked , skipped . |
is_success bool |
Flag indicating operation was successfully applied. |
is_contract bool |
Flag indicating smart-contract calls. |
is_event bool |
Flag indicating an event, i.e. state changes that don’t have an operation hash such as bake , unfreeze , seed_slash , airdrop , invoice , migration , subsidy , deposit , reward , bonus . |
is_internal bool |
Flag indicating if this operation was sent be a smart contract. |
is_rollup bool |
Flag indicating this is a rollup related operation. |
gas_limit int64 |
Caller-defined gas limit. |
gas_used int64 |
Gas used by the operation. |
storage_limit int64 |
Caller-defined storage limit. |
storage_paid int64 |
Part of the storage the operation paid for. |
volume money |
Amount of tokens transferred in tz. In denunciation operations, this field contains the accuser reward, in delegation operations this field contains the initially delegated balance. |
fee money |
Fees paid in tez. In denunciation operations, this field contains the offender loss as negative value. |
reward money |
Rewards earned in tez. In denunciation operations, this field contains the offender loss as negative value. |
deposit money |
Amount of deposited tokens in tez. In denunciation operations, this field contains the offender loss as negative value. |
burned money |
Amount of burned tokens in tez. |
data polymorph |
Extra type-dependent operation data. See below. |
errors array |
Native Tezos RPC errors. |
parameters object |
Contract call parameters including entrypoint and value . Use prim=1 to add Micheline primitive tree as prim . On Rollup operations params are found in method and arguments . |
script object |
Embedded Micheline script on originations. |
storage object |
Updated contract storage as embedded JSON object, contract-only. Optional, use storage=1 to add. |
big_map_diff object |
Inserted, updated or deleted bigmap entries as embedded JSON object, contract-only. Optional, use storage=1 to add. |
value object |
Micheline data for global constants. |
code_hash bytes |
Short hash to uniquely identify the receiver contract, first 8 bytes of the SHA256 hash over binary encoded Michelson script code. |
sender hash |
Operation sender (note some event types have no sender). |
receiver hash |
Transaction receiver, may be empty. For activation the source account is referenced when the activation merged coins from a second blinded account (i.e. when a fundraiser signed up twice). For delegation the previous delegate is referenced. |
source hash |
In internal operations, source is the original signer of the outer transaction. |
creator hash |
Contains contract creator on origination . For nonce_revelation the actual seed publisher is referenced. |
baker hash |
New baker, only used by origination and delegation . When empty for a delegation the operation was a withdrawal. |
previous_baker hash |
On re-delegations, contains the previous baker. |
accuser hash |
For double bake/endorse this is the account who sent the accusation. |
offender hash |
For double bake/endorse this is the account who was slashed. |
power int64 |
Endorsing power (in number of slots), (pre)endorsement only. |
level int64 |
Rollup level, rollup ops only. |
limit money |
Deposits limit, set deposit limit op only. |
solution bytes |
VDF operation solution bytes |
proof bytes |
VDF operation proof bytes |
confirmations int64 |
Number of blocks following the inclusion of this operation. Usually 6 blocks are OK to consider an operation final (not subject to reorg). |
metadata object |
Use meta=1 to embed optional account metadata for sender, receiver, delegate, creator. May be empty if no account has metadata defined. |
events array |
List of emitted on-chain events. Kathmandu+ |
ticket_updates array |
List of emitted ticket updates. Lima+ |
staker hash |
Smart rollup publisher. |
loser hash |
Loser of a smart rollup refutation game. |
winner hash |
Winner of a smart rollup refutation game. |
Event Object
Field | Description |
---|---|
contract hash |
Event emitter contract |
type object |
Micheline encoded event type |
payload object |
Micheline encoded value |
tag string |
Event tag defined by the contract author |
type_hash hash |
Unique type hash as uint64 in hex format. Hash is sha256(type_no_annots) |
Ticket Update Object
Field | Description |
---|---|
ticketer hash |
Ticket issuer contract |
type object |
Micheline encoded ticket type |
content object |
Micheline encoded ticket content |
account hash |
Owner account of the ticket |
amount bigint |
Amount of tickets owned by account |
List of supported operation types
activation
double_baking
double_endorsement
double_preendorsement
nonce_revelation
transaction
origination
delegation
reveal
endorsement
preendorsement
proposal
ballot
register_constant
deposits_limit
Ithaca+bake
eventunfreeze
eventseed_slash
eventairdrop
eventinvoice
eventmigration
eventsubsidy
eventdeposit
event Ithaca+reward
event Ithaca+bonus
event Ithaca+rollup_origination
Jakarta+ (wraps tx_rollup and smart_rollup originations)rollup_transaction
Jakarta+ (wraps all other tx_rollup and smart_rollup operations)vdf_revelation
Kathmandu+increase_paid_storage
Kathmandu+drain_delegate
Lima+update_consensus_key
Lima+
Decoding Operation Data
Some operations contain extra data in the string field data
. Format depends on the operation type
.
Operation | Data Type | Specification |
---|---|---|
activation |
string | hex(secret),blinded-address |
endorsement |
uint | 32bit big-endian bitmask identifying endorsed slots |
ballot |
string | proposal-hash,ballot (yay, nay, pass) |
proposals |
string | comma-separated list or proposal hashes |
reveal |
string | public key hash |
nonce_revelation |
string | level,hex(nonce) |
double_baking |
object | Original JSON object of double signed block headers |
double_endorsemnt |
object | Original JSON object of double signed endorsements |
double_preendorsemnt |
object | Original JSON object of double signed endorsements |
vdf_revelation |
string | Original hex string, a concatenation of solution and proof |
update_consensus_key |
string | The new consensus key as base58 string |
Bigmaps
Bigmaps are key-value stores where smart contracts keep large amounts of data. Values in bigmaps are accessed by unique keys. The TzStats bigmap index supports different keys, a hash (script expression hash) and the native typed version of a key. For convenience, both variants are present in responses as hash
and key
.
Types A bigmap is defined by a key_type
and a value_type
. While the key type is most often a simple type (int, string, bytes, address, etc) it can also be an object. Values are represented as unfolded (decoded) form and optionally as original Michelson primitives.
Unfolding uses Micheline type annotations from the smart contract to decompose native primitives into nested JSON objects. Annotations become JSON property names. To request the original Micheline primitives, add query parameter prim=1
(bool).
Packed Data When data is packed using the PACK
instruction, an unpacked version can be obtained with the unpack=1
(bool) query argument. In this case both key
and value
contain the unpacked version. We also try to recursively unpack all embedded values of type bytes
so that URLs, names and other packed data becomes easier to access.
Metadata Each bigmap entry comes with a set of metadata that describes its latest update time, block hash and height as well as the bigmap id and its owner contract.
Pagination The Bigmap API support paginated queries for keys, values and updates using limit
and cursor
or offset
.
Historic Values To query a bigmap at a certain point in time add the block
(int64|hash) query argument. Using block hashes is reorg-aware, i.e. in case you execute a query on a block that becomes orphaned, the API returns a 409 Conflict error.
If you like to query for updates that happened after a certain block, add a since
(int64|hash) argument.
SECURITY WARNING
Unlike other on-chain data where values and ranges are predictable the contents of bigmaps is entirely user-controlled and unpredictable. IT MAY CONTAIN MALICIOUS DATA INTENDED TO ATTACK YOUR APPLICATIONS AND USERS! Be vigilant and sanitize all data before you process or display it.
Bigmap Info
Example request.
curl "https://api.tzstats.com/explorer/bigmap/523"
import (
"context"
"blockwatch.cc/tzstats-go"
)
bigmap, err := tzstats.DefaultClient.GetBigmap(
context.Background(),
523,
tzstats.NewContractParams(),
)
Example response.
{
"alloc_block": "BLmmtt7CFJagi9DWTNNjqD1JBBRmknpmcgAcpsJRhw5KQnybBoc",
"alloc_height": 1365148,
"alloc_time": "2021-03-01T02:04:41Z",
"bigmap_id": 523,
"contract": "KT1Hkg5qeNhfwpKW4fXvq7HGZB9z2EnmCCA9",
"key_type": {
"name": "@key",
"type": "nat"
},
"n_keys": 90005,
"n_updates": 640725,
"update_block": "BLFiakfUmXoLuN7DGoRkykQjEHr73ShWspXKLEdDC1hwpHiENu6",
"update_height": 1478163,
"update_time": "2021-05-19T10:59:14Z",
"value_type": {
"args": [
{
"name": "issuer",
"type": "address"
},
{
"name": "objkt_amount",
"type": "nat"
},
{
"name": "objkt_id",
"type": "nat"
},
{
"name": "xtz_per_objkt",
"type": "mutez"
}
],
"name": "@value",
"type": "struct"
}
}
Returns information about the identity and type of a bigmap. At access native Micheline type info, add prim=1
(boolean)
HTTP Request
GET /explorer/bigmap/{id}
HTTP Response
Field | Description |
---|---|
alloc_block hash |
Hash of the block where the bigmap was allocated. |
alloc_height int64 |
Height when the bigmap was allocated. |
alloc_time datetime |
Timestamp when the bigmap was allocated. |
bigmap_id int64 |
Unique on-chain id of this bigmap. |
contract hash |
Contract that owns the bigmap. |
key_type object |
Typedef describing bigmap keys. |
value_type object |
Typedef describing bigmap values. |
n_keys int64 |
Current number of live keys in bigmap. |
n_updates int64 |
Total update count. |
update_height int64 |
Last update height. |
update_block hash |
Hash of the block containing the latest update. |
update_time datetime |
Last update timestamp. |
deleted_height int64 |
Deletion height (only when bigmap was deleted). |
deleted_block hash |
Deletiom block hash (only when bigmap was deleted). |
deleted_time datetime |
Deletion timestamp (only when bigmap was deleted). |
key_type_prim object |
Native Micheline type for key. |
value_type_prim object |
Native Micheline type for value. |
Bigmap Keys
Example request.
curl "https://api.tzstats.com/explorer/bigmap/523/keys?meta=1&prim=1&unpack=1"
import (
"context"
"blockwatch.cc/tzstats-go"
)
keys, err := tzstats.DefaultClient.GetBigmapKeys(
context.Background(),
523,
tzstats.NewContractParams().
WithMeta().
WithPrim().
WithUnpack(),
)
// access integer key
i, ok := keys[0].GetBig("")
// access pair key element
addr, ok := keys[0].GetAddress("0")
Example response.
[
{
"key": "29",
"hash": "exprvFW5tJBbcQUhtABJ2ThMb6v5ufBaoanohBBBikEMBJDjEjKdS6",
"meta": {
"bigmap_id": 523,
"contract": "KT1Hkg5qeNhfwpKW4fXvq7HGZB9z2EnmCCA9",
"height": "2021-03-01T18:10:47Z",
"time": ""
},
"prim": {
"int": "29"
}
}
// ...
]
Lists bigmap keys with optional metadata, native primitives and unpacking. Supports
- paging with
limit
andcursor
/offset
- historic key listing using
block
(int64|hash) - native Micheline primitives
prim=1
- unpacking of packed data withh
unpack=1
HTTP Request
GET /explorer/bigmap/{id}/keys
HTTP Response
Field | Description |
---|---|
key polymorph |
The native representation of the key. Integers are bigints wrapped in strings, other types are rendered according to type rules, e.g. addresses, keys and signatures are base58check encoded, timestamps are ISO8601, etc. Can be used for lookup. |
hash hash |
The script expression hash for this key. Can be used for lookup. |
meta object |
Metadata for the current bigmap entry (optional, use meta=1 ). |
meta.bigmap_id int64 |
Unique on-chain id of this bigmap. |
meta.contract hash |
Contract that owns the bigmap. |
meta.time datetime |
Update timestamp for this key/value pair. |
meta.height int64 |
Update height for this key/value pair. |
prim object |
Native JSON encoded Micheline primitives (optional, use prim=1 ). |
Bigmap Values
Example request.
curl "https://api.tzstats.com/explorer/bigmap/511/values"
import (
"context"
"blockwatch.cc/tzstats-go"
)
values, err := tzstats.DefaultClient.GetBigmapValues(
context.Background(),
511,
tzstats.NewContractParams().
WithMeta().
WithPrim().
WithUnpack(),
)
// access pair key element
addr, ok := values[0].Key.GetAddress("0")
// access integer value
i, ok := values[0].GetBig("")
Example response.
[
{
"key": {
"0": "tz1UBZUkXpKGhYsP5KtzDNqLLchwF4uHrGjw",
"1": "153"
},
"hash": "exprvD1v8DxXvrsCqbx7BA2ZqxYuUk9jXE1QrXuL46i3MWG6o1szUq",
"key_prim": {
"args": [
{
"bytes": "00005db799bf9b0dc319ba1cf21ab01461a9639043ca"
},
{
"int": "153"
}
],
"prim": "Pair"
},
"meta": {
"bigmap_id": 511,
"contract": "KT1RJ6PbjHpwc3M5rw5s2Nbmefwbuwbdxton",
"height": 1365467,
"time": "2021-03-01T07:27:27Z"
},
"value": "2",
"value_prim": {
"int": "2"
}
}
// ...
]
Lists key/value pairs in bigmaps with optional metadata, native primitives and unpacking. Supports
- paging with
limit
andcursor
/offset
- historic key listing using
block
(int64|hash) - native Micheline primitives
prim=1
- unpacking of packed data withh
unpack=1
HTTP Request
GET /explorer/bigmap/{id}/values
GET /explorer/bigmap/{id}/{key}
The second variant returns a single bigmap value stored at key
if it exists. Key can be a key hash (script expr hash) or the native key representation (i.e. an address or integer). For pair keys, separate the pair’s elements with comma.
HTTP Response
Field | Description |
---|---|
key polymorph |
The native representation of the key. Integers are bigints wrapped in strings, other types are rendered according to type rules, e.g. addresses, keys and signatures are base58check encoded, timestamps are ISO8601, etc). |
hash hash |
The script expression hash for this key. |
value object |
Unfolded and optionally unpacked value, such as simple string or nested JSON objects/arrays to represent records, lists, sets, and maps. |
meta object |
Metadata for the current bigmap entry (optional, use meta=1 ). |
meta.contract hash |
Contract that owns the bigmap. |
meta.bigmap_id int64 |
Unique on-chain id of this bigmap. |
meta.time datetime |
Update timestamp for this key/value pair. |
meta.height int64 |
Update height for this key/value pair. |
key_prim object |
Native Micheline primitive for key (optional, use prim=1 ). |
value_prim object |
Native Micheline primitive for value (optional, use prim=1 ). |
Bigmap Updates
Example request.
curl "https://api.tzstats.com/explorer/bigmap/511/updates?prim=1&meta=1&unpack=1"
import (
"context"
"blockwatch.cc/tzstats-go"
)
upd, err := tzstats.DefaultClient.GetBigmapUpdates(
context.Background(),
511,
tzstats.NewContractParams().
WithMeta().
WithPrim().
WithUnpack(),
)
Example response.
[
{
"action": "update",
"bigmap_id": 511,
"key": {
"0": "tz1UBZUkXpKGhYsP5KtzDNqLLchwF4uHrGjw",
"1": "152"
},
"hash": "expru3VKqrBfsG3ZbP9eBTTpWrYWth5Ypp8qhn6JyM4BR3pTB3PGu8",
"key_prim": {
"args": [
{
"bytes": "00005db799bf9b0dc319ba1cf21ab01461a9639043ca"
},
{
"int": "152"
}
],
"prim": "Pair"
},
"meta": {
"bigmap_id": 511,
"contract": "KT1RJ6PbjHpwc3M5rw5s2Nbmefwbuwbdxton",
"height": 1365242,
"time": "2021-03-01T03:39:21Z"
},
"value": "1",
"value_prim": {
"int": "1"
}
}
// ...
]
List historic updates to a bigmap in chronological order, including keys that have been deleted. Supports
- paging with
limit
andcursor
/offset
- native Micheline primitives
prim=1
- unpacking of packed data withh
unpack=1
HTTP Request
GET /explorer/bigmap/{id}/updates
GET /explorer/bigmap/{id}/updates/{key}
The second variant lists updates for a specific key only.Key can be a key hash (script expr hash) or the native key representation (i.e. an address or integer). For pair keys, separate the pair’s elements with comma.
HTTP Response
Contains the same fields as the values endpoint above with one addition:
Field | Description |
---|---|
action enum |
Update kind, one of alloc , update , remove , copy . |
bigmap_id int64 |
Unique on-chain id of this bigmap. |
key polymorph |
The native representation of the key. Integers are bigints wrapped in strings, other types are rendered according to type rules, e.g. addresses, keys and signatures are base58check encoded, timestamps are ISO8601, etc). |
hash hash |
The script expression hash for this key. |
value object |
Unfolded and optionally unpacked value, such as simple string or nested JSON objects/arrays to represent records, lists, sets, and maps. |
meta object |
Metadata for the current bigmap entry (optional, use meta=1 ). |
meta.contract hash |
Contract that owns the bigmap. |
meta.bigmap_id int64 |
Unique on-chain id of this bigmap. |
meta.time datetime |
Update timestamp for this key/value pair. |
meta.height int64 |
Update height for this key/value pair. |
key_prim object |
Native Micheline primitive for key (optional, use prim=1 ). |
value_prim object |
Native Micheline primitive for value (optional, use prim=1 ). |
source_big_map int64 |
Source bigmap copied (only for action=copy). |
destination_big_map int64 |
Destination bigmap created (only for action=copy). |
Blocks
Example request.
curl "https://api.tzstats.com/explorer/block/1342853?meta=1&rights=1"
import (
"context"
"blockwatch.cc/tzstats-go"
)
block, err := tzstats.DefaultClient.GetBlockHeight(
context.Background(),
1342853,
tzstats.NewBlockParams().
WithMeta().
WithRights(),
)
Example response.
{
"hash": "BKrPhXCfGnGow78WF4togWfviupxZNosfJaaQZgdrb6qpfySe9K",
"predecessor": "BMDbYbZgTurLcrK1BnNyVhpe4hwoCpyp9B1fmwH4QuAzfEgL8Ti",
"successor": "BMcr9c93QiuHgU4Kniq3LyVXfUrNSspn39Zw41U2TDbH4UdHcrP",
"protocol": "PtKathmankSpLLDALzWw7CGD2j2MtyveTwboEYokqUCP4a1LxMg",
"baker": "tz1VQnqCCqX4K5sP3FNkVSNKTdCAMJDd3E1n",
"proposer": "tz1VQnqCCqX4K5sP3FNkVSNKTdCAMJDd3E1n",
"baker_consensus_key": "tz1VQnqCCqX4K5sP3FNkVSNKTdCAMJDd3E1n",
"proposer_consensus_key": "tz1VQnqCCqX4K5sP3FNkVSNKTdCAMJDd3E1n",
"height": 2968449,
"cycle": 556,
"is_cycle_snapshot": false,
"time": "2022-12-14T09: 13: 14Z",
"solvetime": 30,
"version": 14,
"round": 0,
"nonce": "763259c5986f0700",
"voting_period_kind": "adoption",
"n_endorsed_slots": 0,
"n_ops_applied": 240,
"n_ops_failed": 0,
"n_events": 2,
"n_calls": 15,
"n_rollup_calls": 0,
"n_tx": 17,
"volume": 109.773037,
"fee": 0.011742,
"reward": 19.913518,
"deposit": 0,
"activated_supply": 0,
"minted_supply": 22.413518,
"burned_supply": 0.16475,
"n_accounts": 239,
"n_new_accounts": 1,
"n_new_contracts": 0,
"n_cleared_accounts": 0,
"n_funded_accounts": 1,
"gas_limit": 55241,
"gas_used": 52211,
"storage_paid": 402,
"pct_account_reuse": 99.581589958159,
"lb_esc_vote": "off",
"lb_esc_ema": 0,
"metadata": {
"tz1VQnqCCqX4K5sP3FNkVSNKTdCAMJDd3E1n": {
"address": "tz1VQnqCCqX4K5sP3FNkVSNKTdCAMJDd3E1n",
"alias": {
"name": "PosDog",
"kind": "validator",
"logo": "tz1VQnqCCqX4K5sP3FNkVSNKTdCAMJDd3E1n.png"},
"baker": {
"status": "public",
"fee": 0.1,
"min_delegation": 1000
},
"location": {
"country": "CN"
},
"social": {
"website": "https://pos.dog"
}
}
},
"rights": [
{
"type": "baking",
"round": 0,
"address": "tz1VQnqCCqX4K5sP3FNkVSNKTdCAMJDd3E1n",
"is_used": true
},
{
"type": "endorsing",
"address": "tz2FCNBrERXtaTtNX6iimR1UJ5JSDxvdHM93",
"is_used": true
},
// ...
]
}
Fetches information about the specified block. Takes either a block hash
, a block height
or the string head
as argument. Use meta
(boolean) to embed optional account metadata and rights
to embed information about baking and endorsing rights as well as their status.
HTTP Request
GET /explorer/block/{hash,height,head}
HTTP Response
Field | Description |
---|---|
hash hash |
Block hash. |
predecessor hash |
Parent block on canonical chain or orphan side-chain. |
successor hash |
Child block on canonical chain or orphan side-chain. |
protocol hash |
Active protocol. |
baker hash |
Baker address. |
proposer hash |
Payload proposer address. Ithaca+ |
baker_consensus_key hash |
Baker key (address) used to sign this block. |
proposer_consensus_key hash |
Baker key (address) to sign the payload. |
height int64 |
Block height (a.k.a level). |
cycle int64 |
Cycle |
is_cycle_snapshot bool |
True if this block has been selected as snapshot. |
time datetime |
Block creation time. |
solvetime duration |
Time since last block in seconds. |
version int64 |
Protocol version. |
round int64 |
Baking priority or round (Ithaca+). |
nonce uint64 |
Block nonce, part of this nonce is the baker software version Git hash. |
voting_period_kind enum |
Current voting period proposal , exploration , cooldown , promotion , adoption . |
n_endorsed_slots int64 |
Count of endorsed slots. (Note this field will be set from endorsements published in the subsequent block.) |
n_ops_appled int64 |
Count of successful operations. |
n_ops_failed int64 |
Count of failed operations. |
n_calls int64 |
Count of smart contract calls from externally owned accounts (transactions sent to contracts without internal operations sent between contracts). |
n_rollup_calls int64 |
Count of rollup operations. |
n_events int64 |
Count of implicit events, i.e. operations and state changes that don’t have an operation hash such as bake , unfreeze , seed_slash , airdrop and invoice . |
volume money |
Total amount of tokens moved between accounts. |
fee money |
Total fee paid (and frozen) by all operations. |
reward money |
Reward earned (and frozen) by the block baker. |
deposit money |
Deposit frozen by the block baker. |
activated_supply money |
Total amount of commitments activated in tez. |
minted_supply money |
Total amount of new tokens minted by events and operations in tez. |
burned_supply money |
Total amount of tokens burned by operations in tez. |
n_accounts int64 |
Count of accounts seen in this block (i.e. this includes all operation senders, receivers, delegates and the block’s baker). |
n_new_accounts int64 |
Count of new accounts created regardless of type. |
n_new_contracts int64 |
Count of created smart contracts (KT1 with code). |
n_cleared_accounts int64 |
Count of accounts that were emptied (final balance = 0). |
n_funded_accounts int64 |
Count of accounts that were funded by operations (this includes all new accounts plus previously cleared accounts that were funded again). |
gas_limit int64 |
Total gas limit defined by operations. |
gas_used int64 |
Total gas consumed by operations. |
storage_paid int64 |
Total sum of new storage allocated by operations. |
pct_account_reuse float |
Portion of seen accounts that existed before. |
lb_esc_ema int64 |
Granada liquidity baking vote moving average. |
lb_esc_vote bool |
Granada liquidity baking disable vote flag. |
metadata object |
Optional account metadata for baker and endorsers, missing when no metadata is available. Endorser metadata is only embedded when rights arg is also set. |
rights array |
List of endorsing and prio/round zero baking rights including owner and status. |
List Block Operations
Example request to list block operations.
curl "https://api.tzstats.com/explorer/block/head/operations?meta=1"
import (
"context"
"blockwatch.cc/tzstats-go"
)
ops, err := tzstats.DefaultClient.GetBlockOps(
context.Background(),
1342853,
tzstats.NewOpParams().
WithMeta(),
)
Example response.
[{
"id": 146569756672,
"type": "bake",
"block": "BMX2R59xLV3gFRGTfjJKWbU2GTBajM4Yhv4MjDvfRFGgSfoNDMs",
"time": "2022-03-29T10:11:54Z",
"height": 2236477,
"cycle": 467,
"op_n": 0,
"status": "applied",
"is_success": true,
"is_event": true,
"fee": 0.05937,
"reward": 19.765625,
"deposit": 640,
"sender": "tz2FCNBrERXtaTtNX6iimR1UJ5JSDxvdHM93",
"confirmations": 0,
"metadata": {
"tz2FCNBrERXtaTtNX6iimR1UJ5JSDxvdHM93": {
"address": "tz2FCNBrERXtaTtNX6iimR1UJ5JSDxvdHM93",
"alias":{
"name": "stakefish",
"kind": "validator",
"logo": "tz2FCNBrERXtaTtNX6iimR1UJ5JSDxvdHM93.png"
},
"baker":{
"status":"public",
"fee":0.08
},
"social":{
"twitter": "stakedotfish"
}
}
}
},{
"id": 146569756673,
"type": "subsidy",
"block": "BMX2R59xLV3gFRGTfjJKWbU2GTBajM4Yhv4MjDvfRFGgSfoNDMs",
"time": "2022-03-29T10:11:54Z",
"height": 2236477,
"cycle": 467,
"op_n": 1,
"status": "applied",
"is_success": true,
"is_contract": true,
"is_event": true,
"gas_used": 224,
"volume": 2.5,
"reward": 2.5,
"receiver": "KT1TxqZ8QtKvLu3V3JH7Gx58n7Co8pgtpQU5",
"confirmations": 0,
"metadata": {
"KT1TxqZ8QtKvLu3V3JH7Gx58n7Co8pgtpQU5": {
"address": "KT1TxqZ8QtKvLu3V3JH7Gx58n7Co8pgtpQU5",
"alias": {
"name": "Constant Product Market Maker",
"kind": "dex",
"logo": "KT1TxqZ8QtKvLu3V3JH7Gx58n7Co8pgtpQU5.png"
}
}
}
},
// ...
]
Returns a list of operations in the corresponding block as well as a list of implicit events. Supports
limit
andcursor
/offset
for pagingorder
withasc
ordesc
for ordering (by row_id)type
for filtering operations (see query filters)meta=1
to embed optional account metadata senders, receivers, delegates
HTTP Request
List Block Operations
GET /explorer/block/{hash,height,head}/operations
Contracts
Example request.
curl "https://api.tzstats.com/explorer/contract/KT1Puc9St8wdNoGtLiD2WXaHbWU7styaxYhD"
import (
"context"
"blockwatch.cc/tzgo"
"blockwatch.cc/tzstats-go"
)
contract, err := tzstats.DefaultClient.GetContract(
context.Background(),
tezos.MustParseAddress("KT1Puc9St8wdNoGtLiD2WXaHbWU7styaxYhD"),
tzstats.NewContractParams(),
)
Example response.
{
"account_id": 818761,
"address": "KT1Puc9St8wdNoGtLiD2WXaHbWU7styaxYhD",
"creator": "tz1P7A3YFgeSsGgopKN9vUU86W3psgTMdtcJ",
"baker": "tz1WCd2jm4uSt4vntk4vSuUWoZQGhLcDuR9q",
"storage_size": 89,
"storage_paid": 35957,
"storage_burn": 26.228,
"total_fees_used": 148.058555,
"first_seen": 1149672,
"last_seen": 1855764,
"first_seen_time": "2020-09-29T16:18:45Z",
"last_seen_time": "2021-11-11T22:15:18Z",
"n_calls_in": 5909,
"n_calls_out": 8810,
"n_calls_failed": 20,
"bigmaps": {
"accounts": 124
},
"iface_hash": "cf9361e19e152667",
"code_hash": "666dcc0163791250",
"storage_hash": "f078cbd9d26e6f66",
"call_stats": {
"addLiquidity": 641,
"approve": 1,
"default": 0,
"removeLiquidity": 250,
"setBaker": 0,
"setManager": 0,
"tokenToToken": 22,
"tokenToXtz": 2631,
"updateTokenPool": 1,
"updateTokenPoolInternal": 1,
"xtzToToken": 2362
},
"features": [
"set_delegate",
"transfer_tokens"
],
"interfaces": []
}
Returns information about a Tezos smart contract. For balance details call the explorer account endpoint using the contracts KT1 address.
HTTP Request
GET /explorer/contract/{hash}
HTTP Response
Field | Description |
---|---|
account_id uintt64 |
Id of the related account. |
address hash |
Contract address. |
creator hash |
Creator account (called manager before Babylon. |
baker hash |
Baker the contract delegates to (may be empty). |
storage_size int64 |
Storage size allocated in bytes. |
storage_paid int64 |
Storage bytes paid for in bytes. |
storage_burn money |
Storage costs burned for allocating bytes. |
total_fees_used money |
Total sum of fees accrued as tx receiver. |
first_seen int64 |
Block height of account creation. |
last_seen int64 |
Block height of last activity. |
delegated_since int64 |
Block height of most recent delegation. |
first_seen_time datetime |
Block time of account creation. |
last_seen_time datetime |
Block time of last activity. |
delegated_since_time datetime |
Block time of most recent delegation. |
n_calls_in int64 |
Lifetime total number of successful calls received. |
n_calls_out int64 |
Lifetime total number of successful internal calls sent. |
n_calls_failed int64 |
Lifetime total number of calls failed. |
bigmaps object |
Named bigmaps owned by this contract, map between annotation used in storage spec and bigmap id. |
iface_hash bytes |
Short hash to uniquely identify the contract interface, first 8 bytes of the SHA256 hash over binary encoded Michelson script parameters. |
code_hash bytes |
Short hash to uniquely identify the contract code, first 8 bytes of the SHA256 hash over binary encoded Michelson script code. |
storage_hash bytes |
Short hash to uniquely identify the contract code, first 8 bytes of the SHA256 hash over binary encoded Michelson storage. |
call_stats object |
Per-entrypoint call statistics, as named key/value pairs. |
features array |
Michelson features used by this contract. Any of account_factory , contract_factory , set_delegate , lambda , transfer_tokens , chain_id , ticket , sapling , view , global_constant , timelock . |
interfaces array |
Standard interfaces implemented by this contract. Any of MANAGER , SET_DELEGATE , TZIP-005 , TZIP-007 , TZIP-012 , DEXTER (list may be extended). |
Contract Scripts
Example request.
curl "https://api.tzstats.com/explorer/contract/KT1Puc9St8wdNoGtLiD2WXaHbWU7styaxYhD/script?prim=1"
import (
"context"
"blockwatch.cc/tzgo"
"blockwatch.cc/tzstats-go"
)
script, err := tzstats.DefaultClient.GetContractScript(
context.Background(),
tezos.MustParseAddress("KT1Puc9St8wdNoGtLiD2WXaHbWU7styaxYhD"),
tzstats.NewContractParams().WithPrim(),
)
Example response.
// ...
{
"script": {
"code": [
//...
],
"storage": {
// ...
},
},
"storage_type": {
"name": "storage",
"type": "struct",
"args": [{
// ...
}]
},
"entrypoints": {
"approve": {
"id": 0,
"name": "approve",
"branch": "/L/L/L",
"type": [{
"name": "spender",
"type": "address"
},{
"name": "allowance",
"type": "nat"
},{
"name": "currentAllowance",
"type": "nat"
}],
"prim": {
// ...
}
},
//...
},
"views": {
// ...
}
},
// ...
GET /explorer/contract/{hash}/script
Returns the native Michelson JSON encoding of the deployed smart contract code as well as type specifications for call parameters, storage and bigmaps. Also contains decoded entrypoints and unfolded storage type.
Entrypoint names are extracted from type annotations and appear without prefix @. In rare cases when the entrypoint name is missing we use the convention @entrypoint_<num>
, or if duplicate we suffix the name with a counter <name>_<num>
.
Field | Description |
---|---|
script object |
Native Micheline primitives (optional, use prim=1 ). |
storage_type object |
Typedef for contract storage. |
entrypoints object |
List of named entrypoints. |
entrypoints.$.id int64 |
Position of the entrypoint in the Michelson parameter tree. |
entrypoints.$.branch string |
Path of left (L) or right (R) branches to reach the entrypoint’s code in the Michelson code tree. |
entrypoints.$.name string |
Annotated name of the entrypoint. |
entrypoints.$.type polymorph |
Array of typedef for entrypoint arguments. |
entrypoints.$.prim object |
Native Micheline primitives (optional, use prim=1 ). |
views object |
List of named on-chain views. |
views.$.name string |
Name of the view. |
views.$.type polymorph |
Array of typedefs for view input and return arguments. |
views.$.code object |
Native Micheline primitives for the Michelson script that implements the view (optional, use prim=1 ). |
views.$.prim object |
Native Micheline primitives for the entire view (optional, use prim=1 ). |
Contract Storage
Example request.
curl "https://api.tzstats.com/explorer/contract/KT1Puc9St8wdNoGtLiD2WXaHbWU7styaxYhD/storage?prim=1"
import (
"context"
"blockwatch.cc/tzgo"
"blockwatch.cc/tzstats-go"
)
storage, err := tzstats.DefaultClient.GetContractStorage(
context.Background(),
tezos.MustParseAddress("KT1Puc9St8wdNoGtLiD2WXaHbWU7styaxYhD"),
tzstats.NewContractParams().WithPrim(),
)
Example response.
{
"value": {
"accounts": "124",
"freezeBaker": false,
"lqtTotal": "55431856030",
"manager": "KT1B5VTw8ZSMnrjhy337CEvAm4tnT8Gu8Geu",
"selfIsUpdatingTokenPool": false,
"tokenAddress": "KT1LN4LPSqTMS7Sd2CJw4bbDGRkMv2t68Fy9",
"tokenPool": "1494861",
"xtzPool": "1191482"
},
"prim": {
// ...
}
}
GET /explorer/contract/{hash}/storage
Returns the most recent or a historic version of the contracts storage. Supports
- historic values when using
block
(int64|hash) - native Micheline primitives
prim=1
- unpacking of packed data with
unpack=1
Field | Description |
---|---|
value object |
Unfolded storage using type annotations. |
prim object |
Native Micheline primitives (optional, use prim=1 ). |
Contract Calls
Example request.
curl "https://api.tzstats.com/explorer/contract/KT1Puc9St8wdNoGtLiD2WXaHbWU7styaxYhD/calls?prim=1"
import (
"context"
"blockwatch.cc/tzgo"
"blockwatch.cc/tzstats-go"
)
calls, err := tzstats.DefaultClient.GetContractCalls(
context.Background(),
tezos.MustParseAddress("KT1Puc9St8wdNoGtLiD2WXaHbWU7styaxYhD"),
tzstats.NewContractParams().WithPrim(),
)
Example response.
// ...
"parameters": {
"entrypoint": "addLiquidity",
"value": {
"deadline": "2020-09-30T18:30:44.002Z",
"maxTokensDeposited": "6000000",
"minLqtMinted": "1",
"owner": "tz1fSkEwBCgTLas8Y82SYpEGW9aFZPBag8uY"
},
"prim": {
// ...
},
},
"big_map_diff": {
// ...
},
"storage": {
// ...
}
// ...
GET /explorer/contract/{hash}/calls
Returns contract calls (transactions) sent to the contract with embedded parameters, storage and bigmap updates. Supports
- metadata with
meta=1
- native Micheline primitives
prim=1
- unpacking of packed data withh
unpack=1
- listing of newer updates with
since
(int64|hash) - ordering of calls with
order
(asc|desc) - filtering by
entrypoint
(int64|string) using id, name or branch
Call parameters contain the following properties:
Field | Description |
---|---|
entrypoint string |
Named entrypoint used in call params, e.g. ‘default’ or ‘entrypoint_00. |
value object |
Call parameters in order of type definition. |
prim object |
Native Micheline primitives (optional, use prim=1 ). |
method string |
A rollup operation that has been executed by this call (rollup only). |
arguments object |
Rollup operation arguments, content depends on the rollup method. |
Constants
Example request.
curl "https://api.tzstats.com/explorer/constant/exprteofHrmfpTEhdfQrQyt7LjVcYJfTsqgtPEQCT2kneXWm5DkH1m?prim=1"
import (
"context"
"blockwatch.cc/tzgo"
"blockwatch.cc/tzstats-go"
)
constant, err := tzstats.DefaultClient.GetConstant(
context.Background(),
tezos.MustParseExprHash("exprteofHrmfpTEhdfQrQyt7LjVcYJfTsqgtPEQCT2kneXWm5DkH1m"),
tzstats.NewContractParams().WithPrim(),
)
Example response.
{
"address": "exprteofHrmfpTEhdfQrQyt7LjVcYJfTsqgtPEQCT2kneXWm5DkH1m",
"creator": "tz1gt8TgBeWomA6dpqKeuzo8Umxfc78eS5Z6",
"height": 64862,
"time": "2021-11-19T12:20:52Z",
"storage_size": 2822,
"value": {
// ...
},
"features":[]
}
GET /explorer/constant/{hash}
Returns value and metadata for a registered global constant.
Field | Description |
---|---|
address hash |
Constant address (expr-hash). |
creator hash |
Creator account address. |
height int64 |
Block height when constant was registered. |
storage_size int64 |
Storage size in bytes. |
features string |
Comma separated list of Michelson features used by this constant. Any of account_factory , contract_factory , set_delegate , lambda , transfer_tokens , chain_id , ticket , sapling , global_constant , timelock , view . |
value *object |
array* |
Cycles
Example request.
curl "https://api.tzstats.com/explorer/cycle/head"
Example response.
{
"cycle": 247,
"start_height": 1011713,
"end_height": 1015808,
"start_time": "2020-06-25T03:36:14Z",
"end_time": "2020-06-27T23:54:04Z",
"progress": 13.2568359375,
"is_complete": false,
"is_snapshot": false,
"is_active": true,
"snapshot_height": -1,
"snapshot_index": -1,
"snapshot_time": "0001-01-01T00:00:00Z",
"rolls": 84176,
"roll_owners": 423,
"active_delegators": 54434,
"active_bakers": 447,
"staking_supply": 674670196.013393,
"staking_percent": 80.2706912175752,
"working_bakers": 117,
"working_endorsers": 300,
"missed_priorities": 4,
"missed_endorsements": 115,
"n_double_baking": 0,
"n_double_endorsement": 0,
"n_orphans": 0,
"solvetime_min": 60,
"solvetime_max": 100,
"solvetime_mean": 60.327808471454915,
"priority_min": 0,
"priority_max": 1,
"priority_mean": 0.007366482504604053,
"endorsement_rate": 99.33694649446494,
"endorsements_min": 25,
"endorsements_max": 32,
"endorsements_mean": 31.78782287822878,
"seed_rate": 100,
"worst_baked_block": 1011950,
"worst_endorsed_block": 1011819,
"snapshot_cycle": {
// ... same data as cycle
},
"follower_cycle": {
// ... same data as cycle
}
}
Provides information about a consensus cycle, the past roll snapshot cycle and the future cycle whose rights are determined by the current cycle. This endpoint accepts head
and a cycle number
as path parameters.
HTTP Request
GET /explorer/cycle/{head,number}
HTTP Response
Field | Description |
---|---|
cycle int64 |
The cycle number. |
start_height int64 |
First block height (level) in this cycle. |
end_height int64 |
Last block height (level) in this cycle. |
start_time datetime |
Start time (estimate for future cycles). |
end_time datetime |
End time (estimate for open and future cycles). |
progress float |
Cycle completion in percent. |
is_complete bool |
Flag indicating the cycle is complete. |
is_snapshot bool |
Flag indicating a roll snapshot has been selected. |
is_active bool |
Flag indicating the cycle is currently active. |
snapshot_height int64 |
Height of the snapshot block. |
snapshot_index int64 |
Index of the snapshot block. |
snapshot_time datetime |
Time the snapshot block was taken. |
rolls int64 |
Number of rolls at selected snapshot block or most recent snapshot block. |
roll_owners int64 |
Number of unique roll owners (delegates) at selected snapshot block or most recent snapshot block. |
staking_supply money |
Total staked supply at selected snapshot block or most recent snapshot block. |
staking_percent float |
Percentage of total supply staked at selected snapshot block or most recent snapshot block. |
active_bakers int64 |
Number of actively registered bakers. |
active_delegators int64 |
Number of non-zero accounts delegating to active bakers. |
working_bakers int64 |
Number of bakers seen during this cycle. It’s expected for this number to be lower than active_bakers because some may have no rolls, others may not contribute. |
working_endorsers int64 |
Number of unique endorsers seen during this cycle. It’s expected for this number to be lower than active_bakers because some may have no rolls, others may not contribute. |
missed_priorities int64 |
Total count of missed block priorities. |
missed_endorsements int64 |
Total count of missed endorsement slots. |
n_double_baking int64 |
Count of double_baking_evidence events. |
n_double_endorsement int64 |
Count of double_endorsement_evidence events. |
n_orphans int64 |
Number of orphan blocks in this cycle. |
solvetime_min int64 |
Minimum time between blocks. |
solvetime_max int64 |
Maximum time between blocks. |
solvetime_mean float |
Mean time between blocks. |
priority_min int64 |
Minimum block priority. |
priority_max int64 |
Maximum block priority. |
priority_mean float |
Mean block priority. |
endorsement_rate float |
Percentage of seen endorsements vs expected endorsements. |
endorsements_min int64 |
Minimum count of endorsements across all blocks. |
endorsements_max int64 |
Maximum count of endorsements across all blocks. |
endorsements_mean float |
Mean count of endorsements across all blocks. |
seed_rate int64 |
Percentage of published vs expected seed_nonce_revelations . |
worst_baked_block int64 |
Height of the block with lowest priority. |
worst_endorsed_block int64 |
Height of the block with least endorsed slots. |
snapshot_cycle object |
Embedded cycle data for the cycle that provided the roll snapshot for the current cycle. |
follower_cycle object |
Embedded cycle data for the future cycle that will get its rights assigned from a snapshot in the current cycle. |
Elections
Example request.
curl "https://api.tzstats.com/explorer/election/head"
Example response.
{
"election_id": 39,
"start_height": 2285569,
"start_time": "2022-04-16T09:50:14Z",
"end_height": 2490368,
"end_time": "2022-06-28T14:48:14Z",
"voting_period": "adoption",
"is_empty": false,
"is_failed": false,
"is_open": true,
"max_periods": 5,
"no_majority": false,
"no_proposal": false,
"no_quorum": false,
"num_periods": 5,
"num_proposals": 4,
"proposal": {
"eligible_rolls": 115155,
"eligible_stake": 685418342.568226,
"eligible_voters": 385,
"is_draw": false,
"is_failed": false,
"is_open": false,
"nay_rolls": 0,
"nay_stake": 0,
"nay_voters": 0,
"no_majority": false,
"no_proposal": false,
"no_quorum": false,
"pass_rolls": 0,
"pass_stake": 0,
"pass_voters": 0,
"period_end_block": 2326528,
"period_end_time": "2022-05-01T02:05:29Z",
"period_start_block": 2285569,
"period_start_time": "2022-04-16T09:50:14Z",
"proposals": [
{
"block_hash": "BLrcxiWFjAWf3E1KyPAQyPGfRSqTVSofZ1936ERT3nWxJC9j9dH",
"hash": "PtJakartaiDz69SfDDLXJSiuZqTSeSKRDbKVZC8MNzJnvRjvnGw",
"height": 2286604,
"op_hash": "ooNVwjdBEuFEcCr6Qjvj4ZmsaboAqxQxEc1JYvsXPQy63of9Z2z",
"rolls": 19086,
"source": "tz1S5WxdZR5f9NzsPXhr7L9L1vrEb5spZFur",
"stake": 0,
"time": "2022-04-16T18:46:59Z",
"voters": 47
},
{
"block_hash": "BLXGQGX1suCSsSF7Kx8ch2idKGSyJ5vJztA214TmgrMJ97VMiGN",
"hash": "PtJakart2xVj7pYXJBXrqHgd82rdkLey5ZeeGwDgPp9rhQUbSqY",
"height": 2313783,
"op_hash": "ongHcJPpjJmnReoNwxQQqiuZKr9ZxvSGFRfq1ZiJcvWYAN6bp3F",
"rolls": 27081,
"source": "tz1S5WxdZR5f9NzsPXhr7L9L1vrEb5spZFur",
"stake": 0,
"time": "2022-04-26T12:34:44Z",
"voters": 85
},
{
"block_hash": "BKrxpNphA3mJRBJtwc41SBVR29rHd1j8KsorzEbygcRi89QkyLR",
"hash": "PtSEBSEBSEBSEBSEBSEBSEBSEBSEBSEBSEBSEBSEBSEBS5VTrmo",
"height": 2323914,
"op_hash": "oojxUhKQrEp3kHqpjt3J2MSyvLu7KGieU1xQgangsPZfWNyMfSj",
"rolls": 4,
"source": "tz1R664EP6wjcM1RSUVJ7nrJisTpBW9QyJzP",
"stake": 0,
"time": "2022-04-30T03:53:29Z",
"voters": 1
},
{
"block_hash": "BKrxpNphA3mJRBJtwc41SBVR29rHd1j8KsorzEbygcRi89QkyLR",
"hash": "PtGXSEBUHXFARMxDEXxNFTxRPCxSEBxSEBxSEBxSEBxSE3GRJJC",
"height": 2323914,
"op_hash": "oojxUhKQrEp3kHqpjt3J2MSyvLu7KGieU1xQgangsPZfWNyMfSj",
"rolls": 4,
"source": "tz1R664EP6wjcM1RSUVJ7nrJisTpBW9QyJzP",
"stake": 0,
"time": "2022-04-30T03:53:29Z",
"voters": 1
}
],
"quorum_pct": 500,
"quorum_rolls": 5757,
"quorum_stake": 34270917.128411,
"turnout_ema": 0,
"turnout_pct": 2668,
"turnout_rolls": 30505,
"turnout_stake": 182912224.998332,
"turnout_voters": 96,
"voting_period": 70,
"voting_period_kind": "proposal",
"yay_rolls": 0,
"yay_stake": 0,
"yay_voters": 0
},
"exploration": {
"eligible_rolls": 115281,
"eligible_stake": 687620221.226926,
"eligible_voters": 380,
"is_draw": false,
"is_failed": false,
"is_open": false,
"nay_rolls": 0,
"nay_stake": 0,
"nay_voters": 0,
"no_majority": false,
"no_proposal": false,
"no_quorum": false,
"pass_rolls": 27594,
"pass_stake": 165617666.478757,
"pass_voters": 20,
"period_end_block": 2367488,
"period_end_time": "2022-05-15T16:51:14Z",
"period_start_block": 2326529,
"period_start_time": "2022-05-01T02:05:59Z",
"proposals": [
{
"block_hash": "BLXGQGX1suCSsSF7Kx8ch2idKGSyJ5vJztA214TmgrMJ97VMiGN",
"hash": "PtJakart2xVj7pYXJBXrqHgd82rdkLey5ZeeGwDgPp9rhQUbSqY",
"height": 2313783,
"op_hash": "ongHcJPpjJmnReoNwxQQqiuZKr9ZxvSGFRfq1ZiJcvWYAN6bp3F",
"rolls": 0,
"source": "tz1S5WxdZR5f9NzsPXhr7L9L1vrEb5spZFur",
"stake": 0,
"time": "2022-04-26T12:34:44Z",
"voters": 0
}
],
"quorum_pct": 5224,
"quorum_rolls": 60222,
"quorum_stake": 359212803.568946,
"turnout_ema": 6448,
"turnout_pct": 5854,
"turnout_rolls": 67188,
"turnout_stake": 402585743.698669,
"turnout_voters": 141,
"voting_period": 71,
"voting_period_kind": "exploration",
"yay_rolls": 39594,
"yay_stake": 236968077.219912,
"yay_voters": 121
},
"cooldown": {
"eligible_rolls": 113350,
"eligible_stake": 679602809.899885,
"eligible_voters": 383,
"is_draw": false,
"is_failed": false,
"is_open": false,
"nay_rolls": 0,
"nay_stake": 0,
"nay_voters": 0,
"no_majority": false,
"no_proposal": false,
"no_quorum": false,
"pass_rolls": 0,
"pass_stake": 0,
"pass_voters": 0,
"period_end_block": 2408448,
"period_end_time": "2022-05-30T04:12:14Z",
"period_start_block": 2367489,
"period_start_time": "2022-05-15T16:51:44Z",
"proposals": [
{
"block_hash": "BLXGQGX1suCSsSF7Kx8ch2idKGSyJ5vJztA214TmgrMJ97VMiGN",
"hash": "PtJakart2xVj7pYXJBXrqHgd82rdkLey5ZeeGwDgPp9rhQUbSqY",
"height": 2313783,
"op_hash": "ongHcJPpjJmnReoNwxQQqiuZKr9ZxvSGFRfq1ZiJcvWYAN6bp3F",
"rolls": 0,
"source": "tz1S5WxdZR5f9NzsPXhr7L9L1vrEb5spZFur",
"stake": 0,
"time": "2022-04-26T12:34:44Z",
"voters": 0
}
],
"quorum_pct": 0,
"quorum_rolls": 0,
"quorum_stake": 0,
"turnout_ema": 0,
"turnout_pct": 0,
"turnout_rolls": 0,
"turnout_stake": 0,
"turnout_voters": 0,
"voting_period": 72,
"voting_period_kind": "cooldown",
"yay_rolls": 0,
"yay_stake": 0,
"yay_voters": 0
},
"promotion": {
"eligible_rolls": 115096,
"eligible_stake": 690148163.099879,
"eligible_voters": 386,
"is_draw": false,
"is_failed": false,
"is_open": false,
"nay_rolls": 0,
"nay_stake": 0,
"nay_voters": 0,
"no_majority": false,
"no_proposal": false,
"no_quorum": false,
"pass_rolls": 35390,
"pass_stake": 212384627.309411,
"pass_voters": 20,
"period_end_block": 2449408,
"period_end_time": "2022-06-14T04:26:29Z",
"period_start_block": 2408449,
"period_start_time": "2022-05-30T04:13:14Z",
"proposals": [
{
"block_hash": "BLXGQGX1suCSsSF7Kx8ch2idKGSyJ5vJztA214TmgrMJ97VMiGN",
"hash": "PtJakart2xVj7pYXJBXrqHgd82rdkLey5ZeeGwDgPp9rhQUbSqY",
"height": 2313783,
"op_hash": "ongHcJPpjJmnReoNwxQQqiuZKr9ZxvSGFRfq1ZiJcvWYAN6bp3F",
"rolls": 0,
"source": "tz1S5WxdZR5f9NzsPXhr7L9L1vrEb5spZFur",
"stake": 0,
"time": "2022-04-26T12:34:44Z",
"voters": 0
}
],
"quorum_pct": 5164,
"quorum_rolls": 59435,
"quorum_stake": 356392511.424777,
"turnout_ema": 6329,
"turnout_pct": 6251,
"turnout_rolls": 71979,
"turnout_stake": 431431747.515176,
"turnout_voters": 134,
"voting_period": 73,
"voting_period_kind": "promotion",
"yay_rolls": 36589,
"yay_stake": 219047120.205765,
"yay_voters": 114
},
"adoption": {
"eligible_rolls": 115712,
"eligible_stake": 693473356.445228,
"eligible_voters": 387,
"is_draw": false,
"is_failed": false,
"is_open": true,
"nay_rolls": 0,
"nay_stake": 0,
"nay_voters": 0,
"no_majority": false,
"no_proposal": false,
"no_quorum": false,
"pass_rolls": 0,
"pass_stake": 0,
"pass_voters": 0,
"period_end_block": 2490368,
"period_end_time": "2022-06-28T14:47:44Z",
"period_start_block": 2449409,
"period_start_time": "2022-06-14T04:26:59Z",
"proposals": [
{
"block_hash": "BLXGQGX1suCSsSF7Kx8ch2idKGSyJ5vJztA214TmgrMJ97VMiGN",
"hash": "PtJakart2xVj7pYXJBXrqHgd82rdkLey5ZeeGwDgPp9rhQUbSqY",
"height": 2313783,
"op_hash": "ongHcJPpjJmnReoNwxQQqiuZKr9ZxvSGFRfq1ZiJcvWYAN6bp3F",
"rolls": 0,
"source": "tz1S5WxdZR5f9NzsPXhr7L9L1vrEb5spZFur",
"stake": 0,
"time": "2022-04-26T12:34:44Z",
"voters": 0
}
],
"quorum_pct": 0,
"quorum_rolls": 0,
"quorum_stake": 0,
"turnout_ema": 0,
"turnout_pct": 0,
"turnout_rolls": 0,
"turnout_stake": 0,
"turnout_voters": 0,
"voting_period": 74,
"voting_period_kind": "adoption",
"yay_rolls": 0,
"yay_stake": 0,
"yay_voters": 0
}
}
On-chain elections can be queried by proposal hash
or sequence number
. An election contains a complete set of data on a past or the currently ongoing (head
) on-chain voting process, including up to four voting periods. Voting periods may be empty when no proposal has been published. Only the last voting period of the last election can be in state open. Ballots represent the individual ballot operations sent by bakers during votes or the up-votes to a proposal during the first voting period.
From Jakarta, all voting activity uses stake instead of rolls. We continue support for both fields on the API, now all fields that used to contain rolls are accompanied by a second field mentioning the related stake.
HTTP Request
GET /explorer/election/{head,hash,number}
HTTP Response
Field | Description |
---|---|
election_id int64 |
Sequence number of the election. |
num_periods int64 |
Number of voting periods activated during this election (min 1, max 4) |
num_proposals int64 |
Total number of submitted proposals. |
start_time int64 |
Time of the first block in the election. |
end_time int64 |
Time of the last block in the election (when open this is an approximation of the latest possible end assuming all voting periods are used and all remaining blocks are produced at priority zero). |
start_height int64 |
First block of the election period. |
end_height bool |
Last block of the election (when open this is an approximation of the full duration assuming all voting periods are used). |
is_empty bool |
Flag indicating the election has not seen and proposal being submitted. |
is_open bool |
Flag indicating the election is ongoing. |
is_failed bool |
Flag indicating the election has failed to select or activate a new protocol. |
no_quorum bool |
Flag indicating the election has failed because no quorum could be reached. |
no_majority bool |
Flag indicating the election has failed because no majority could be reached. |
no_proposal bool |
Flag indicating the election has failed because no proposal has been submitted. |
voting_period enum |
Period kind proposal , exploration , cooldown , promotion , adoption . |
proposal object |
Vote object for the proposal period 1 (see below). |
exploration object |
Vote object for the exploration period 2 (see below). |
cooldown object |
Vote object for the cooldown period 3 (see below). |
promotion object |
Vote object for the promotion vote period 4 (see below). |
adoption object |
Vote object for the adoption vote period 5 (see below). |
Voting Period Object
Field | Description |
---|---|
voting_period int64 |
Protocol-level voting period counter. |
voting_period_kind enum |
Period kind proposal , exploration , cooldown , promotion , adoption . |
period_start_time datetime |
Time of the first block in the voting period. |
period_end_time datetime |
Time of the last block in the voting period (when open this is an approximation of the latest possible end assuming all remaining blocks are produced at priority zero). |
period_start_block int64 |
First block of the voting period. |
period_end_block int64 |
Last block of the voting period. |
eligible_rolls int64 |
Number of rolls eligible to vote. Snapshot at start of the voting period. |
eligible_stake money |
Amount of stake eligible to vote. Snapshot at start of the voting period. |
eligible_voters int64 |
Number of eligible voters (delegates) snapshot at start of the voting period. |
quorum_pct float |
Required quorum in percent. |
quorum_rolls int64 |
Required rolls to reach quorum. |
quorum_stake money |
Required stake to reach quorum. |
turnout_rolls int64 |
Actual voting rolls. |
turnout_stake money |
Actual voting stake. |
turnout_voters int64 |
Actual voters. |
turnout_pct float |
Actual participation in percent. |
turnout_ema float |
Moving average for Babylon v005 quorum algorithm. |
yay_rolls int64 |
Number of Yay rolls. |
yay_stake money |
Amount of Yay stake. |
yay_voters int64 |
Number of Yay voters. |
nay_rolls int64 |
Number of Nay rolls. |
nay_stake money |
Amount of Nay stake. |
nay_voters int64 |
Number of Nay voters. |
pass_rolls int64 |
Number of Pass rolls. |
pass_stake money |
Amount of Pass stake. |
pass_voters int64 |
Number of Pass voters. |
is_open bool |
Flag indicating the voting period is currently open. |
is_failed bool |
Flag indicating the voting period has failed to select or activate a new protocol. |
is_draw bool |
Flag indication the reason for failure was a draw between two proposals in the proposal period. |
no_proposal bool |
Flag indication the reason for failure was no submitted proposal in the proposal period. |
no_quorum bool |
Flag indication the reason for failure was participation below the required quorum. |
no_majority bool |
Flag indication the reason for failure was acceptance below the required supermajority. |
proposals array |
List of submitted proposals (in proposal period) or the selected proposal. |
Proposal Object
Field | Description |
---|---|
hash hash |
Protocol hash. |
source hash |
Sender account. |
block_hash hash |
Proposal operation block hash. |
op_hash hash |
Proposal operation hash. |
height int64 |
Proposal operation submission height. |
time datetime |
Proposal operation submission time. |
rolls int64 |
Count of rolls voting for this proposal during the proposal period. |
stake money |
Amount of stale voting for this proposal during the proposal period. |
voters int64 |
Count of voters voting for this proposal during the proposal period. |
List Voters
GET /explorer/election/{hash,number,head}/{stage}/voters
Lists all eligible voters for the current voting period where stage
is the sequence number of the voting period [1..4]
. The voter list supports pagination with limit
, offset
and cursor
. To change the order of returned calls use the optional order
(asc|desc) parameter.
Voter Object
Field | Description |
---|---|
row_id int64 |
Internal account id for use with cursor . |
address hash |
Voter address. |
rolls int64 |
Count of rolls the voter has during this voting period. |
stake money |
Staking balance the voter had at the beginning of this voting period. |
has_voted bool |
Flag indicating if the account has already voted. |
ballot enum |
Ballot cast by the voter, either yay , nay or pass . |
proposals array |
List of proposals (as hashes) the voter voted for. |
List Ballots
GET /explorer/election/{hash,number,head}/{stage}/ballots
Lists all ballots cast during the current voting period where stage
is the sequence number of the voting period [1..4]
. The voter list supports pagination with limit
, offset
and cursor
. To change the order of returned calls use the optional order
(asc|desc) parameter.
Ballot Object
Field | Description |
---|---|
row_id int64 |
Internal account id for use with cursor . |
sender hash |
Voter address. |
height int64 |
Operation submission height. |
time datetime |
Operation submission time. |
election_id int64 |
Sequence number of the election. |
voting_period int64 |
Protocol-level voting period counter. |
voting_period_kind enum |
Period kind proposal , exploration , cooldown , promotion , adoption . |
proposal hash |
Hash of the proposal the voter voted for. If the vote happened during the proposal period and the voter used to vote for multiple proposals either in a single proposals operation or with multiple proposals operations, multiple ballots exist. |
op hash |
Operation hash. |
ballot enum |
Ballot cast by the voter, either yay , nay or pass . During proposal period the ballot is always yay to describe the only choice. |
rolls int64 |
Count of rolls the voter had during this voting period. |
stake money |
Amount of stake the voter had during this voting period. |
Market Tickers
Example request.
curl "https://api.tzstats.com/markets/tickers"
Example response.
[
{
"pair": "XTZ_BNB",
"base": "XTZ",
"quote": "BNB",
"exchange": "binance",
"open": 0.05813000,
"high": 0.06058000,
"low": 0.05583000,
"last": 0.05741000,
"change": -1.23860313,
"vwap": 0.05787292,
"n_trades": 176,
"volume_base": 17373.80000000,
"volume_quote": 1005.47257300,
"timestamp": "2019-09-29T20:14:00.001014458Z"
},
{
"pair": "XTZ_BTC",
"base": "XTZ",
"quote": "BTC",
"exchange": "kraken",
"open": 0.00011090,
"high": 0.00011300,
"low": 0.00010710,
"last": 0.00010970,
"change": -1.08205591,
"vwap": 0.00011036,
"n_trades": 808,
"volume_base": 219356.80514484,
"volume_quote": 24.20907256,
"timestamp": "2019-09-29T20:14:00.000755843Z"
}
]
Fetches a list of market price tickers with 24h OHLCV data.
HTTP Request
GET /markets/tickers
HTTP Response
Field | Description |
---|---|
pair string |
Trading pair in format {base}_{quote} . |
base string |
Base currency (always XTZ ). |
quote string |
Quote currency. |
exchange string |
Exchange code. |
open money |
24h open price in quote currency. |
high money |
24h highest price in quote currency. |
low money |
24h lowest price in quote currency. |
last money |
Last price in quote currency. |
change float |
24h price change in percent. |
vwap money |
24h volume weighted average price in quote currency. |
n_trades int64 |
24h number of trades. |
volume_base money |
24h traded volume in base currency. |
volume_quote money |
24h traded volume in quote currency. |
timestamp datetime |
Timestamp of the ticker result. |
Table API
Table overview
Endpoint | Table Content
------------------------|---------------------------------------------------------
/tables/balance | historic end-of-block balances for all accounts
/tables/chain | running blockchain totals
/tables/supply | running supply totals
/tables/block | blocks (including orphans)
/tables/op | operations (only final)
/tables/account | most recent account balances and state
/tables/contract | smart contracts state at creation
/tables/constant | smart contract global constants
/tables/flow | balance, freezer and delegation flows
/tables/rights | baking and endorsing rights
/tables/snapshot | balances of bakers & delegators at all snapshot blocks
/tables/income | per-cycle statistics on baker income, efficiency, etc
/tables/election | election metadata (i.e. entire governance cycles)
/tables/proposal | individual proposals
/tables/vote | voting period metadata
/tables/ballot | ballots and proposal operations
/tables/bigmaps | bigmap allocations
/tables/bigmap_values | currently live bigmap values
/tables/bigmap_updates | historic bigmap updates (including copy/alloc)
Generic Table Query
https://api.tzstats.com/tables/{table_code}.{format}?{args}
Tables store data in tabular form as a set of columns. Each column has a specified type and each row has a unique uint64 row_id
. Empty values are represented as JSON null
or empty strings. Tables can grow extremely large, so it’s good practice to use filters and the columns
query argument to limit the result size. Table responses are automatically sorted by row_id
. Use client-side sorting if a different sorting order is required.
Query Arguments
Tables support the following general query parameters.
Argument | Description |
---|---|
columns optional |
Comma separated list of column names to return. Bulk array results will be ordered accordingly. Default is all defined columns for a table. |
limit optional |
Maximum number of rows to return. Limited to 50,000, default 500. |
cursor optional |
Id (row_id ) of the latest result row returned by a previous call. |
order optional |
Result order either asc (default) or desc , sorted by row_id . |
To paginate result sets larger than the maximum limit, include row_id
into the list of columns and use the last value of row_id as cursor in your next call. This will automatically apply an extra filter row_id.gt=cursor
for ascending and row_id.lt=cursor
for descending order. You can of course also apply the relevant row_id filter directly, without using cursor.
Query Filters
Filter Example
The example below filters blocks by time range from
time.gte=2019-08-01
(inclusive) totime.lte=2019-08-31
(inclusive) and returns columnstime
andheight
. The same effect can be achieved with the range operatortime.rg=2019-08-01,2019-08-31
.
curl "https://api.tzstats.com/tables/block.json?columns=time,height&time.gte=2018-08-01&time.lte=2018-08-31&limit=50000"
JSON result
[
[1533081657000,42672],
[1533081717000,42673],
[1533081777000,42674],
[1533081837000,42675],
[1533081897000,42676],
[1533081957000,42677],
[1533082017000,42678],
[1533082152000,42679],
[1533082287000,42680],
[1533082347000,42681],
[1533082407000,42682],
// ...
]
To filter tables use filter expressions of the form <column>.<operator>=<arg>
. Filters work on any combination of columns regardless of type. For arguments, type encoding rules of the column type apply. Filtering by multiple columns is similar to a logical AND between expressions. For simplicity and performance there are currently no OR expressions or more complex operators available. Comparison order for strings and binary is the lexicographical order over UTF8 (string) or ASCII (binary) alphabets.
Operator | Semantics |
---|---|
= , .eq= |
Equal. Matches rows where column values match exactly the filter value. |
.ne= |
Not equal. Matches rows where column values do not match the filter value. |
.gt= |
Greater than. matches columns whose value is strictly greater than the filter value. |
.gte= |
Greater than or equal. matches columns whose value is greater than or equal to the filter value. |
.lt= |
Less than. matches columns whose value is strictly smaller than the filter value. |
.lte= |
Less than or equal. matches columns whose value is strictly smaller than or equal to the filter value. |
.in= |
Inclusion in list. matches columns whose value is equal to one of the filter values. Multiple values must be separated by comma. |
.nin= |
Not included in list. matches columns whose value is not equal to one of the filter values. Multiple values may be separated by comma. |
.rg= |
Range. matches columns whose value is between the provided filter values, boundary inclusive. Requires exactly two values separated by comma. (This is similar to, but faster than using .gte= and .lte= in combination.) |
.re= |
Regexp. matches columns whose value matches the regular expression. Can only be used on string-type columns (not enum or hash). Non-URL-safe characters must be properly escaped. |
Account Table
Example request.
curl "https://api.tzstats.com/tables/account?address=tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m"
import (
"context"
"blockwatch.cc/tzstats-go"
)
// create a new query object
q := tzstats.DefaultClient.NewAccountQuery()
// add filters and configure the query
q.WithFilter(tzstats.FilterModeEqual, "address", "tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m").
WithLimit(1000).
WithColumns("row_id", "address", "spendable_balance")
// execute the query
list, err := q.Run(context.Background())
// walk accounts
for _, acc := range list.Rows {
// access regular Account structs
}
Example response (comments added for explanation).
[
[
278469, // row_id
"tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m", // address
"secp256k1", // address_type
"sppk7bn9MKAWDUFwqowcxA1zJgp12yn2kEnMQJP3WmqSZ4W8WQhLqJN" // pubkey
12345, // counter
278469, // baker_id
0, // creator_id
360996, // first_in
360997, // first_out
633203, // last_in
633203, // last_out
360996, // first_seen
633203, // last_seen
0, // delegated_since
4129917.992000, // total_received
1241985.094354, // total_sent
0.000000, // total_burned
0.041097, // total_fees_paid
0.000000, // unclaimed_balance
253038.498372, // spendable_balance
0, // frozen_bond
0, // lost_bond
1, // is_funded
0, // is_activated
0, // is_delegated
1, // is_revealed
1, // is_baker
0, // is_contract
103002, // n_tx_success
0, // n_tx_failed
38, // n_tx_out
2, // n_tx_in
"tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m", // baker
null, // creator
1553123452000, // first_seen_time
1570032391000, // last_seen_time
1553123452000, // first_in_time
1570032391000, // last_in_time
1553123512000, // first_out_time
0, // delegated_since_time
]
]
List information about the most recent state of implicit and smart contract accounts.
HTTP Request
GET https://api.tzstats.com/tables/account?args
HTTP Response
Field | Description |
---|---|
row_id uint64 |
Unique row identifier. |
address hash |
Account address. |
address_type enum |
Account address type ed25519 (tz1), secp256k1 (tz2), p256 (tz3), contract (KT1) or blinded (btz1) |
pubkey hash |
Revealed public key. |
counter int64 |
Replay protection counter for ops signed. |
baker_id uint64 |
Unique row_id of the baker this account delegates to. If same as row_id, this is a baker account. |
creator_id uint64 |
Contract creator unique row_id. |
first_in int64 |
Block height of first incoming transaction. |
first_out int64 |
Block height of first outgoing transaction. |
last_in int64 |
Block height of latest incoming transaction. |
last_out int64 |
Block height of latest outgoing transaction. |
first_seen int64 |
Block height of account creation. |
last_seen int64 |
Block height of last activity. |
delegated_since int64 |
Block height of most recent delegation. |
total_received money |
Lifetime total tokens received in transactions. |
total_sent money |
Lifetime total tokens sent in transactions. |
total_burned money |
Lifetime total tokens burned in tez. |
total_fees_paid money |
Lifetime fees paid in tez. |
unclaimed_balance money |
Currently unclaimed balance (for vesting contracts and commitments). |
spendable_balance money |
Currently spendable balance. |
frozen_bond money |
Total rollup bond currently frozen. |
lost_bond money |
Total rollup bond lost due to slashing. |
is_funded bool |
Flag indicating the account is funded. |
is_activated bool |
Flag indicating the account was activated from a commitment. |
is_delegated bool |
Flag indicating the account is currently delegated. |
is_revealed bool |
Flag indicating the account has a revealed public key . |
is_baker bool |
Flag indicating the account is a registered baker. |
is_contract bool |
Flag indicating the account is a smart contract. |
n_tx_success int64 |
Lifetime total number of operations sent. |
n_tx_failed int64 |
Lifetime total number of operations failed. |
n_tx_out int64 |
Lifetime total number of transactions sent. |
n_tx_in int64 |
Lifetime total number of transactions received. |
baker hash |
Account baker address. |
creator hash |
Account creator address. |
first_seen_time datetime |
Block time of account creation. |
last_seen_time datetime |
Block time of last activity. |
first_in_time datetime |
Block time of first incoming transaction. |
last_in_time datetime |
Block time of latest incoming transaction. |
first_out_time datetime |
Block time of first outgoing transaction. |
last_out_time datetime |
Block time of latest outgoing transaction. |
delegated_since_time datetime |
Block time of most recent delegation. |
Balance Table
Example request.
curl "https://api.tzstats.com/tables/balance?address=tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m"
Example response (comments added for explanation).
[
[
25, // row_id
25, // account_id
0, // balance
0 // valid_from
"tz3RDC3Jdn4j15J7bBHZd29EUee9gVB1CxD9", // address
0, // valid_from_time
],
// ...
]
Show account balances at the end of each block where a balance change occured.
HTTP Request
GET https://api.tzstats.com/tables/balance?args
HTTP Response
Field | Description |
---|---|
row_id uint64 |
Unique row identifier. |
account_id uint64 |
Unique account id. |
balance money |
Point in time balance snapshot at end of block. |
valid_from int64 |
Block height where the balance updated to the current value. |
address hash |
Account address |
valid_from_time datetime |
Block time where the balance updated to the current value. |
Ballot Table
Example request.
curl "https://api.tzstats.com/tables/ballot?voting_period=16&limit=1"
Example response (comments added for explanation).
[
[
856, // row_id
13, // election_id
5, // proposal_id
16, // voting_period
"exploration", // voting_period_kind
557061, // height
1565333732000, // time
63795, // source_id
13150288, // op_id
6, // rolls
"yay", // ballot
"tz1abmz7jiCV2GH2u81LRrGgAFFgvQgiDiaf", // source
"onw6yGKFPucybjz5ysTRoohdnZMt9UFkTo6RdUFe7vcMp5aGv4s", // op
"PsBABY5HQTSkA4297zNHfsZNKtxULfL18y95qb3m53QJiXGmrbU" // proposal
]
]
List individual ballot operations sent by bakers during votes.
HTTP Request
GET https://api.tzstats.com/tables/ballot?args
HTTP Response
Field | Description |
---|---|
row_id uint64 |
Unique row identifier. |
election_id uint64 |
Unique row_id of the election this proposal was submitted in. |
proposal_id uint64 |
Unique row_id of the proposal that is voted for. |
voting_period int64 |
On-chain sequence number of the voting period this ballot was cast at. |
voting_period_kind enum |
Type of the voting period proposal , exploration , cooldown , promotion , adoption . |
height int64 |
Block height where the ballot was included |
time datetime |
Block time where the ballot was included. |
source_id uint64 |
Unique row_id if the ballot sender account. |
op_id uint64 |
Unique row_id if the ballot operation. |
rolls int64 |
Number of rolls owned by source. |
stake money |
Amount of stake owned by source. |
ballot enum |
The actual ballot yay , nay , pass . |
source hash |
Address of the ballot sender account. |
op hash |
Hash of the ballot operation. |
proposal hash |
Hash of the proposal that is voted on, if any. |
Bigmap Table
Example request.
curl "https://api.tzstats.com/tables/bigmaps?limit=1&order=desc"
import (
"context"
"blockwatch.cc/tzstats-go"
)
// create a new query object
q := tzstats.DefaultClient.NewBigmapQuery()
// add filters and configure the query to list all active keys
q.WithLimit(1).WithOrder(tzstats.OrderDesc)
// execute the query
list, err := q.Run(context.Background())
// walk bigmaps
for _, row := range list.Rows {
// access BigmapRow structs
}
Example response (comments added for explanation).
[
[
9066, // row_id
9058, // bigmap_id
1478230, // account_id
1585347, // alloc_height
9, // n_keys
9, // n_updates
1585347, // update_height
0, // delete_height
"KT1PvEyN1xCFCgorN92QCfYjw3axS6jawCiJ", // contract
1628005298000, // alloc_time
"BLHBYPnzrqEszy6ZswFQkhc727hDbsYVNnWCTppdQnmqsh1fWDz", // alloc_block
1628005298000, // update_time
"BLHBYPnzrqEszy6ZswFQkhc727hDbsYVNnWCTppdQnmqsh1fWDz", // update_block
0, // delete_time
"", // delete_block
"0362", // key_type
"075e07650965000003ed076...", // value_type
]
]
Lists bigmap allocations and the most recent state of each bigmap. Use this table only when you have a very good reason, e.g. to search through all bigmaps of all contracts efficiently. A better way might be to use the explorer API endpoints.
HTTP Request
GET https://api.tzstats.com/tables/bigmaps?args
HTTP Response
Field | Description |
---|---|
row_id uint64 |
Unique row identifier. |
bigmap_id int64 |
Unique on-chain id of the bigmap. |
account_id uint64 |
Unique row_id of the account that owns the bigmap. |
alloc_height int64 |
Height at which the bigmap was allocated on-chain. |
alloc_time datetime |
Timestamp at which the bigmap was allocated on-chain. |
alloc_block hash |
Hash of the block in which the bigmap was allocated. |
update_height int64 |
Height at which the bigmap was last updated. |
update_time datetime |
Timestamp at which the bigmap was last updated. |
update_block hash |
Hash of the block in which the bigmap was last updated. |
delete_height int64 |
Height at which the bigmap was deleted. |
delete_time datetime |
Timestamp at which the bigmap was deleted. |
delete_block hash |
Hash of the block in which the bigmap was deleted. |
key_type string |
Hex string with Micheline encoded type for bigmap keys. |
value_type string |
Hex string with Micheline encoded type for bigmap values. |
n_keys int64 |
Number of live bigmap keys after the last update. |
n_updates int64 |
Total number of updates. |
Bigmap Value Table
Example request.
curl "https://api.tzstats.com/tables/bigmap_values?bigmap_id=515&limit=1&order=desc"
import (
"context"
"blockwatch.cc/tzstats-go"
)
// create a new query object
q := tzstats.DefaultClient.NewBigmapValueQuery()
// need typs for decoding
info, err := tzstats.DefaultClient.GetBigmap(
context.Background(),
511,
tzstats.NewContractParams().WithPrim(),
)
keyType := info.MakeKeyType()
valType := info.MakeValueType()
// add filters and configure the query to list all active keys
q.WithFilter(tzstats.FilterModeEqual, "bigmap_id", 511).
WithLimit(1).
WithOrder(tzstats.OrderDesc)
// execute the query
list, err := q.Run(context.Background())
// walk bigmap updates
for _, row := range list.Rows {
// access BigmapRow structs (use TzGo Type/Value to decode binary data)
key := row.GetKey(keyType)
val := row.GetValue(valType)
}
Example response (comments added for explanation).
[
[
3447263, // row_id
515, // bigmap_id
3143289717337607700, // key_id
1669888, // height
"07070a0000001600003f365276e50080856992f4382eaf5e4e6e6b93360000", // key
"00bca2f501", // value
"exprucYwnpqVYDKuUkPsoGAJ4213DjAJHef2FSqrLx66aFoyEn1Ygv" // key_hash
1630908360000 // time
]
]
Lists individual bigmap values exist in a bigmap at the time of the call. Use this table to bulk-fetch large quantities of bigmap content. A better way might be to use the explorer API endpoints.
HTTP Request
GET https://api.tzstats.com/tables/bigmap_values?args
HTTP Response
Field | Description |
---|---|
row_id uint64 |
Unique row identifier. |
bigmap_id int64 |
Unique on-chain id of the bigmap. |
height int64 |
Height when this key was last updated. |
time datetime |
Time of the latest key update. |
key_id uint64 |
Short hash of the bigmap key. |
key_hash string |
Tezos script expression hash of the key. |
key string |
Hex string with Micheline encoded data for the key. |
value string |
Hex string with Micheline encoded data for the value. |
Bigmap Update Table
Example request.
curl "https://api.tzstats.com/tables/bigmap_updates?bigmap_id=515&limit=1&order=desc"
import (
"context"
"blockwatch.cc/tzstats-go"
)
// create a new query object
q := tzstats.DefaultClient.NewBigmapUpdateQuery()
// need typs for decoding
info, err := tzstats.DefaultClient.GetBigmap(
context.Background(),
511,
tzstats.NewContractParams().WithPrim(),
)
keyType := info.MakeKeyType()
valType := info.MakeValueType()
// add filters and configure the query to list all updates (update/removal actions)
q.WithFilter(tzstats.FilterModeEqual, "bigmap_id", 511).
WithLimit(1).
WithOrder(tzstats.OrderDesc)
// execute the query
list, err := q.Run(context.Background())
// walk bigmap updates
for _, row := range list.Rows {
// access BigmapRow structs (use TzGo Type/Value to decode binary data)
key := row.GetKey(keyType)
val := row.GetValue(valType)
}
Example response (comments added for explanation).
[
[
12520900, // row_id
515, // bigmap_id
14880518129034867591, // key_id
"update", // action
63514493, // op_id
1585371, // height
1628006826000, // time
"07070a0000001601b39686f116bb35115559f7e781200850e02854c4000000", // key
"008d96adb1af01", // value
"onw1dT9DssyqPN6fGXq99qG5nd5zK1MXuHZPHm5GTrjQy6aERt1", // op_hash
"exprvLWAQodM4mjNkpX3WzgbUi8KKhL8qPDchFuwNQBdPbt6CTQQjf" // key_hash
]
]
Lists historic bigmap updates. Use this table to bulk-fetch large quantities of bigmap updates, e.g. to replay or reconstruct bigmap state. A different way to access updates is by using the explorer API endpoints.
HTTP Request
GET https://api.tzstats.com/tables/bigmap_updates?args
HTTP Response
Field | Description |
---|---|
row_id uint64 |
Unique row identifier. |
bigmap_id int64 |
Unique on-chain id of the bigmap. |
key_id uint64 |
Short hash of the bigmap key. |
hash string |
Tezos script expression hash of the key. |
key string |
Hex string with Micheline encoded data for the key. |
value string |
Hex string with Micheline encoded data for the value. |
action enum |
Update action, one of update , remove , alloc , copy . |
height int64 |
Block height at which the update happened. |
time timestamp |
Time of the update. |
op_id uint64 |
Unique row id of the operation that contained the update. |
op_hash hash |
Hash of the operation that contained the update. |
Block Table
Example request.
curl https://api.tzstats.com/tables/block?time.gte=today&limit=1
import (
"context"
"blockwatch.cc/tzstats-go"
)
// create a new query object
q := tzstats.DefaultClient.NewBlockQuery()
// add filters and configure the query
q.WithFilter(tzstats.FilterModeGte, "time", "today").WithLimit(1)
// execute the query
list, err := q.Run(context.Background())
// access that block
if list.Len() == 1 {
fmt.Println(list.Rows[0].Hash)
}
Example response (comments added for explanation).
[
[
632250, // row_id
632249, // parent_id
"BMapnMicyiqFsWU9NdqXvfQJQcpFfzWHMicRRjALEMNngkefd7B", // hash
632249, // height
154, // cycle
0, // is_cycle_snapshot
1569974422000, // time
60, // solvetime
4, // version
0, // round / priority
"000000036e731d39", // nonce
"promotion", // voting_period_kind
35034, // baker_id
35034, // proposer_id
32, // n_endorsed_slots
30, // n_ops_applied
0, // n_ops_failed
0, // n_calls
0, // n_rollup_calls
1, // n_events
10529.635160, // volume
0.004140, // fee
80.000000, // reward
2560.000000, // deposit
0.000000, // activated_supply
0.000000, // burned_supply
0.000000, // minted_supply
31, // n_accounts
0, // n_new_accounts
0, // n_new_contracts
0, // n_cleared_accounts
0, // n_funded_accounts
32100, // gas_limit
30414, // gas_used
0, // storage_paid
false, // lb_esc_vote
0, // lb_esc_ema
100, // pct_account_reuse
"tz1hThMBD8jQjFt78heuCnKxJnJtQo9Ao25X", // baker
"tz1hThMBD8jQjFt78heuCnKxJnJtQo9Ao25X", // proposer
"Pt24m4xiPbLDhVgVfABUjirbmda3yohdN82Sp9FeuAXJ4eV9otd" // protocol
]
]
List detailed information about each block, including orphans.
HTTP Request
GET https://api.tzstats.com/tables/block?args
HTTP Response
Field | Description |
---|---|
row_id uint64 |
Unique row identifier. |
parent_id uint64 |
Unique row id of parent block. |
hash hash |
Block hash. |
height int64 |
Block height. |
cycle int64 |
Consensus cycle this block is part of. |
is_cycle_snapshot bool |
Flag indicating this block is a cycle snapshot. |
time datetime |
Block timestamp. |
solvetime int64 |
Duration between the parent block’s timestamp and this block. |
version int64 |
Block protocol version (note, this is a serial version that depends on how many protocols have been activated on the current chain so far). |
round int64 |
Baking round/priority. |
nonce uint64 |
Block nonce. |
voting_period_kind enum |
Current voting period proposal , exploration , cooldown , promotion , adoption . |
baker_id uint64 |
Baker account id. |
proposer_id uint64 |
Proposer account id. |
n_endorsed_slots int64 |
Count of endorsed slots. (Note this field will be set from endorsements published in the subsequent block.) |
n_ops_applied int64 |
Count of successful operations. |
n_ops_failed int64 |
Count of failed operations. |
n_calls int64 |
Count of smart contract calls (transactions sent to contracts by externally owned accounts excluding internal operations sent between contracts). |
n_rollup_calls int64 |
Count of rollup operations. |
n_events int64 |
Count of implicit protocol events. |
volume money |
Total amount of tokens moved between accounts. |
fee money |
Total fees paid (and frozen) by all operations. |
reward money |
Reward earned (and frozen) by baker. |
deposit money |
Deposit frozen by baker. |
activated_supply money |
Total amount of commitments activated in tez. |
burned_supply money |
Total amount of tokens burned by operations in tez. |
minted_supply money |
Total amount of new tokens minted by operations in tez. |
n_accounts int64 |
Count of accounts seen in this block (i.e. this includes all operation senders, receivers and the block’s baker). |
n_new_accounts int64 |
Count of new accounts created regardless of type. |
n_new_contracts int64 |
Count of created smart contracts (KT1 with code). |
n_cleared_accounts int64 |
Count of accounts that were emptied (final balance = 0). |
n_funded_accounts int64 |
Count of accounts that were funded by operations (this includes all new accounts plus previously cleared accounts that were funded again). |
gas_limit int64 |
Total gas limit defined by operations. |
gas_used int64 |
Total gas consumed by operations. |
storage_paid int64 |
Total sum of new storage allocated by operations. |
lb_esc_ema int64 |
Granada liquidity baking vote moving average. |
lb_esc_vote bool |
Granada liquidity baking disable vote flag. |
pct_account_reuse int |
Percentage of existing accounts seen this block. |
baker hash |
Address of the block baker account. |
proposer hash |
Address of the block proposer account. |
protocol hash |
Hash of the protocol that was active at this block. |
baker_consensus_key hash |
Baker key (address) used to sign this block. |
proposer_consensus_key hash |
Baker key (address) to sign the payload. |
Chain Table
Example request.
curl "https://api.tzstats.com/tables/chain?time.gte=today&limit=1"
import (
"context"
"blockwatch.cc/tzstats-go"
)
// create a new query object
q := tzstats.DefaultClient.NewChainQuery()
// add filters and configure the query
q.WithFilter(tzstats.FilterModeGte, "time", "today").WithLimit(1)
// execute the query
list, err := q.Run(context.Background())
// access that chain status
if list.Len() == 1 {
fmt.Println(list.Rows[0].TotalAccounts)
}
Example response (comments added for explanation).
[
[
632250, // row_id
632249, // height
154, // cycle
1569974422000, // time
334414, // total_accounts
108, // total_contracts
0, // total_rollups
15227175, // total_ops
20112, // total_ops_failed
7139, // total_contract_ops
0, // total_contract_calls
0, // total_rollup_calls
20774, // total_activations
19559, // total_nonce_revelations
13113009, // total_endorsements
0, // total_preendorsements
127, // total_double_bakings
24, // total_double_endorsements
29354, // total_delegations
223262, // total_reveals
26863, // total_originations
1793082, // total_transactions
404, // total_proposals
725, // total_ballots
0, // total_constants
0, // total_set_limits
8747841, // total_storage_bytes
298796, // funded_accounts
210000, // dust_accounts
10751, // unclaimed_accounts
17567, // total_delegators
17105, // active_delegators
462, // inactive_delegators
10, // dust_delegators
3889, // total_bakers
483, // active_bakers
3406, // inactive_bakers
3, // zero_bakers
135, // self_bakers
78, // single_bakers
270, // multi_bakers
72059, // rolls
462 // roll_owners
]
]
List running totals of network-wide statistics. This table is updated at each block.
HTTP Request
GET https://api.tzstats.com/tables/chain?args
HTTP Response
Field | Description |
---|---|
row_id uint64 |
Unique row identifier. |
height int64 |
Block height the current row refers to. |
cycle int64 |
Cycle the current row refers to. |
time datetime |
Block time in UNIX milliseconds the current row refers to. |
total_accounts int64 |
Total count of existing funded & non-funded accounts. |
total_contracts int64 |
Total count of deployed smart contracts. |
total_rollups int64 |
Total count of rollups deployed. |
total_ops int64 |
Total count of on-chain operations. |
total_ops_failed int64 |
Total count of failed on-chain operations. |
total_contract_ops int64 |
Total count of smart contract calls (sent to or originated from contracts). |
total_contract_calls int64 |
Total count of smart contract calls (sent by EOA). |
total_rollup_calls int64 |
Total count of rollup calls. |
total_activations int64 |
Total count of activate_account operations. |
total_nonce_revelations int64 |
Total count of nonce_revelation operations. |
total_endorsements int64 |
Total count of endorsement operations. |
total_preendorsements int64 |
Total count of preendorsement operations. |
total_double_bakings int64 |
Total count of double_baking_evidence operations. |
total_double_endorse int64 |
Total count of double_endorsement_evidence operations. |
total_delegations int64 |
Total count of delegation operations. |
total_reveals int64 |
Total count of reveal operations. |
total_originations int64 |
Total count of origination operations. |
total_transactions int64 |
Total count of transaction operations. |
total_proposals int64 |
Total count of proposals operations. |
total_ballots int64 |
Total count of ballot operations. |
total_constants int64 |
Total count of register_global_constant operations. |
total_set_limits int64 |
Total count of set_deposits_limit operations. |
total_storage_bytes int64 |
Total count of storage bytes allocated. |
funded_accounts int64 |
Current number of funded accounts. |
dust_accounts int64 |
Current number of dust accounts (0 < balance < 1tez). |
unclaimed_accounts int64 |
Current number of unclaimed fundraiser accounts. |
total_delegators int64 |
Current number of non-zero delegators. |
active_delegators int64 |
Current number of non-zero delegators who delegate to an active baker. |
inactive_delegators int64 |
Total count of non-zero delegators who delegate to an inactive baker. |
dust_delegators int64 |
Total count of dust delegators. |
total_bakers int64 |
Current number of registered bakers (active and inactive). |
active_bakers int64 |
Current number of active bakers. |
inactive_bakers int64 |
Current number of inactive bakers (note: inactive bakers can still have future rights, but won’t get any new rights). |
zero_bakers int64 |
Current number of active bakers with zero staking balance. |
self_bakers int64 |
Current number of active bakers who self-bake only and have no incoming delegations. |
single_bakers int64 |
Current number of active bakers who potentially self-bake and have only a single incoming delegation. |
multi_bakers int64 |
Current number of bakers (potentially staking services) who have more than 1 incoming delegation. |
rolls int64 |
Current number of network-wide rolls. |
roll_owners int64 |
Current number of network-wide roll owners. |
Constants Table
Example | request.
curl "https://api.tzstats.com/tables/constant?address=exprteofHrmfpTEhdfQrQyt7LjVcYJfTsqgtPEQCT2kneXWm5DkH1m"
import (
"context"
"blockwatch.cc/tzstats-go"
)
// create a new query object
q := tzstats.DefaultClient.NewConstantQuery()
// add filters and configure the query
q.WithFilter(tzstats.FilterModeEqual, "address", "exprteofHrmfpTEhdfQrQyt7LjVcYJfTsqgtPEQCT2kneXWm5DkH1m")
// execute the query
list, err := q.Run(context.Background())
// process constants
if _, row := range list.Rows {
}
Example response (comments added for explanation).
[
[
512, // row_id
"exprteofHrmfpTEhdfQrQyt7LjVcYJfTsqgtPEQCT2kneXWm5DkH1m", // address
1234, // creator_id
"tz1gt8TgBeWomA6dpqKeuzo8Umxfc78eS5Z6", // creator
"020...", // value
64862, // height
2822, // storage_size
"" // features
]
]
List registered global constants.
HTTP Request
GET https://api.tzstats.com/tables/constant?args
HTTP Response
Field | Description |
---|---|
row_id uint64 |
Unique row identifier. |
address hash |
Constant address expression hash. |
creator_id uint64 |
Unique row_id of creator account. |
creator hash |
Creator account address. |
value bytes |
Micheline encoded value |
height int64 |
Block height when constant was registered. |
storage_size int64 |
Storage size in bytes. |
features string |
Comma separated list of Michelson features used by this constant. Any of account_factory , contract_factory , set_delegate , lambda , transfer_tokens , chain_id , ticket , sapling , global_constant , timelock , view . |
Contract Table
Example | request.
curl "https://api.tzstats.com/tables/contract?address=KT1REHQ183LzfoVoqiDR87mCrt7CLUH1MbcV"
import (
"context"
"blockwatch.cc/tzstats-go"
)
// create a new query object
q := tzstats.DefaultClient.NewContractQuery()
// add filters and configure the query
q.WithFilter(tzstats.FilterModeEqual, "iface_hash", "18e4c571a45b1557")
// execute the query
list, err := q.Run(context.Background())
// process contracts
if _, row := range list.Rows {
}
Example response (comments added for explanation).
[
[
80, // row_id
"KT1Puc9St8wdNoGtLiD2WXaHbWU7styaxYhD", // address
289804, // account_id
289784, // creator_id
438378, // first_seen
655361, // last_seen
3805, // storage_size
3805, // storage_paid
"00000fb20200000fad...", // script
"07070a0000001601b6...", // storage
"18e4c571a45b1557", // iface_hash
"4c50617eaadde218", // code_hash
"0457ad54dd6d141f", // storage_hash
"000000000000000...", // call_stats
"lambda", // features
"", // interfaces
"tz1N74dH3VSeRTeKobbXUbyU82G8pqT2YYEM" // creator
]
]
List creation-time information about smart contracts with embedded code and initial storage.
HTTP Request
GET https://api.tzstats.com/tables/contract?args
HTTP Response
Field | Description |
---|---|
row_id uint64 |
Unique row identifier. |
address hash |
Contract address. |
account_id uint64 |
Unique row_id of related account entry. |
creator_id uint64 |
Manager account row_id (deprecated in v005 Babylon). |
first_seen int64 |
Block height of contract creation. |
last_seen int64 |
Block height of last activity. |
storage_size int64 |
Storage size allocated in bytes. |
storage_paid int64 |
Storage bytes paid for in bytes. |
storage_burn money |
Total value burned for allocation storage. |
script bytes |
Binary encoded Michelson script and initial contract storage. |
storage bytes |
Binary encoded Michelson storage. |
iface_hash bytes |
Short hash to uniquely identify the contract interface, first 8 bytes of the SHA256 hash over binary encoded Michelson script parameters. |
code_hash bytes |
Short hash to uniquely identify the contract code, first 8 bytes of the SHA256 hash over binary encoded Michelson script code. |
storage_hash bytes |
Short hash to uniquely identify the contract storage, first 8 bytes of the SHA256 hash over binary encoded Michelson storage. |
call_stats bytes |
Big-endian uint32 call statistic counters per entrypoint. Only used on smart contracts. |
features string |
Comma separated list of Michelson features used by this contract. Any of account_factory , contract_factory , set_delegate , lambda , transfer_tokens , chain_id , ticket , sapling . |
interfaces string |
Comma separated list of standard interfaces implemented by this contract. Any of MANAGER , SET_DELEGATE , TZIP-005 , TZIP-007 , TZIP-012 , DEXTER (list may be extended). |
creator hash |
Contract creator address. |
Election Table
Example request.
curl "https://api.tzstats.com/tables/election?proposal=PsBABY5HQTSkA4297zNHfsZNKtxULfL18y95qb3m53QJiXGmrbU"
Example response (comments added for explanation).
[
[
13, // row_id
5, // proposal_id
4, // num_periods
2, // num_proposals
15, // voting_perid
1563303754000, // start_time
0, // end_time
524288, // start_height
0, // end_height
0, // is_empty
1, // is_open
0, // is_failed
0, // no_quorum
0, // no_majority
"PsBABY5HQTSkA4297zNHfsZNKtxULfL18y95qb3m53QJiXGmrbU", // proposal
"promotion_vote" // last_voting_period
]
]
List full details about past and current elections. Elections represent metadata about each consecutive run of related voting periods. Elections may contain 4, 2 or 1 vote periods. They are called empty when only one empty proposal vote without a proposal exists.
HTTP Request
GET https://api.tzstats.com/tables/election?args
HTTP Response
Field | Description |
---|---|
row_id uint64 |
Unique row identifier. |
proposal_id uint64 |
Unique row_id of the winning proposal, if any. |
num_periods int64 |
Election duration in number of voting periods. |
num_proposals int64 |
Total number of submitted proposals. |
voting_perid int64 |
On-chain voting period number. |
start_time datetime |
Block time of election start block. |
end_time datetime |
Block time of election end block. |
start_height int64 |
Block height of election start block. |
end_height int64 |
Block height of election end block. |
is_empty bool |
Flag indicating no proposal was submitted. |
is_open bool |
Flag indicating the election is in progress. |
is_failed bool |
Flag indicating the election has failed to select or activate a new protocol. |
no_quorum bool |
Flag indicating the election has failed because no quorum could be reached. |
no_majority bool |
Flag indicating the election has failed because no majority could be reached. |
proposal hash |
Hash of the proposal that is voted on, if any. |
last_voting_period enum |
Type of the last period at which this election ended proposal , exploration , cooldown , promotion , adoption . |
Flow Table
Example request.
curl "https://api.tzstats.com/tables/flow?address=tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m&limit=1"
Example response (comments added for explanation).
[
[
24807689, // row_id
360996, // height
88, // cycle
1553123452000, // time
24, // op_n
0, // op_c
0, // op_i
278469, // account_id
31922, // counterparty_id
"balance", // category
"transaction", // operation
2.000000, // amount_in
0.000000, // amount_out
0, // is_fee
0, // is_burned
0, // is_frozen
0, // is_unfrozen
0, // is_shielded
0, // is_unshielded
60, // token_age
"tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m", // address
"tz1Yju7jmmsaUiG9qQLoYv35v5pHgnWoLWbt" // counterparty
]
]
List balance updates on all sub-accounts and different categories. Our categories go beyond on-chain types and include baking, denunciations, vesting contracts and the invoicing feature of protocol upgrades.
HTTP Request
GET https://api.tzstats.com/tables/flow?args
HTTP Response
Field | Description |
---|---|
row_id uint64 |
Unique row identifier. |
height int64 |
Block height at which this flow was created. |
cycle int64 |
Cycle at which this flow was created. |
time datetime |
Block time at which this flow was created. |
op_n int64 |
Related operation position in block. |
op_c int64 |
Related bulk operation list position. |
op_i int64 |
Related internal operation list position. |
account_id uint64 |
Unique row_id of the account this flow relates to. |
counterparty_id uint64 |
Unique row_id of the counterparty that initiated/received the flow. |
category enum |
Flow category (i.e. sub-account) rewards , deposits , fees , balance , delegation , bond . |
operation enum |
Operation creating this flow endorsement , transaction , origination , delegation , reveal , baking , nonce_revelation , activation , penalty , internal , invoice , airdrop , subsidy , register_constant , bonus , reward , deposit , deposits_limit , rollup_origination , rollup_transaction , rollup_reward , rollup_penalty ,pay_storage , update_consensus_key , drain . |
amount_in money |
Incoming amount in tez. |
amount_out money |
Outgoing amount in tez. |
is_fee bool |
Flag indicating this flow is a fee payment. |
is_burned bool |
Flag indicating this flow burns coins. |
is_frozen bool |
Flag indicating this flow goes towards a freezer sub-account. |
is_unfrozen bool |
Flag indicating this flow comes from a freezer sub-account. |
is_shielded bool |
Flag indicating this flow shielded coins in Sapling. |
is_unshielded bool |
Flag indicating this flow unshielded coins from Sapling. |
token_age float |
Age of tokens moved in days. |
address hash |
Address of the related account. |
counterparty hash |
Address of the counterparty of this flow. |
Income Table
Example request.
curl "https://api.tzstats.com/tables/income?address=tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m&cycle=150"
Example response (comments added for explanation).
[
[
64698, // row_id
150, // cycle
278469, // account_id
3576, // rolls
3183854.077395, // balance
25426700.898205, // delegated
0, // active_stake
4, // n_delegations
199, // n_baking_rights
6507, // n_endorsing_rights
-292.000000, // luck
98.230000, // luck_percent
99.87, // performance_percent
100.00, // contribution_percent
201, // n_blocks_baked
201, // n_blocks_proposed
0, // n_blocks_not_baked
3293, // n_blocks_endorsed
0, // n_blocks_not_endorsed
6507, // n_slots_endorsed
15, // n_seeds_revealed
16198.000000, // expected_income
16176.875000, // total_income
519360.000000, // total_deposits
3216.000000, // baking_income
12959.000000, // endorsing_income
0.000000, // accusation_income
1.875000, // seed_income
1.680381, // fees_income
0, // total_loss
0, // accusation_loss
0, // seed_loss
0, // endorsing_loss
0, // lost_accusation_fees
0, // lost_accusation_rewards
0, // lost_accusation_deposits
0, // lost_seed_fees
0, // lost_seed_rewards
"tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m", // address
1568887343000, // start_time
1569136305000 // end_time
]
]
List detailed baker income and income statistics. This table is extended for all active bakers at each cycle and updated at every block until a cycle is complete. That way, rows for open cycles will always contain live data up to the most recent block in the chain.
HTTP Request
GET https://api.tzstats.com/tables/income?args
HTTP Response
Field | Description |
---|---|
row_id uint64 |
Unique row identifier. |
cycle int64 |
Cycle this income relates to. |
account_id uint64 |
Unique row_id of the baker account this income relates to. |
rolls int64 |
Number of rolls at snapshot block, deprecated by Ithaca+. |
balance money |
A baker’s own balance, composed of spendable balance and frozen deposits plus frozen fees (at snapshot block). Note that frozen rewards do not contribute towards rolls, hence they are not part of balance here. |
delegated money |
Delegated balance (at snapshot block). |
active_stake money |
Amount of stake, used in Ithaca+. |
n_delegations int64 |
Count of incoming non-zero delegations (at snapshot block). |
n_baking_rights int64 |
Count of baking rights in this cycle. |
n_endorsing_rights int64 |
Count of endorsing rights in this cycle. |
luck money |
Absolute luck in coins, i.e. the amount of extra coins that can be earned because randomization allocated more rights than the fair share of rolls. |
luck_percent float |
Relation between actual random rights allocated vs. ideal rights gainable by rolls. Neutral luck is 100%, lower values indicated less rights than fair share, higher values indicate more rights. |
performance_percent float |
Effectiveness of a baker in generating expected rewards. Optimal performance is 100%. The value is lower when blocks or endorsements are missed, low value blocks/endorsements are published or the baker is slashed and higher when extra income was generated from stolen blocks or denunciations. NOTE: This value is not ratio scale nor interval scale. CANNOT be used as benchmark between bakers. |
contribution_percent float |
Effectiveness of a baker in utilizing all rights assigned and contribute to consensus. Optimal contribution is 100%. The value is lower when blocks or endorsements are missed and higher when blocks are stolen. NOTE: This value is ratio scale. It can be used as benchmark for baker availability or participation in consensus. It is strongly correlated to generated income, but does not capture low priority blocks, endorsements or slashing. |
n_blocks_baked int64 |
Number of blocks baked in this cycle (post-Ithaca payload proposer and block baker can be different). |
n_blocks_proposed int64 |
Number of block payloads proposed in this cycle (post-Ithaca payload proposer and block baker can be different). |
n_blocks_not_baked int64 |
Number of blocks not baked although rights existed (previously called lost ). |
n_blocks_endorsed int64 |
Number of blocks endorsed. |
n_blocks_not_endorsed int64 |
Number of blocks not endorsed although rights existed (previously called missed ). |
n_slots_endorsed int64 |
Number of slots endorsed in this cycle. |
n_seeds_revealed int64 |
Number of seed nonces revealed in this cycle. |
expected_income money |
Total income expected based on endorsing and priority 0 baking rights. |
total_income money |
Total sum of all income (note: due to losses, the actual true income may be smaller which is not reflected by this field alone). |
total_deposits money |
Actual deposits (note: due to losses, the actual bonds that will later be unfrozen may be smaller). |
baking_income money |
Total income from baking blocks. |
endorsing_income money |
Total income from endorsing blocks. |
accusation_income money |
Total income from denouncing double baking and endorsing. |
seed_income money |
Total income from publishing seed nonces. |
fees_income money |
Total income from fees. |
total_loss money |
Total lost income due to denunciations or unpublished seed nonces. NOTE: This does not automatically reduce total_income above. |
accusation_loss money |
Lost value due to punishments for double signing. |
seed_loss money |
Loss due to an unpublished seed nonces (fees and rewards). |
endorsing_loss money |
Lost rewards due too low participation in Ithaca+. |
lost_accusation_fees money |
Lost fees due to double signing. |
lost_accusation_rewards money |
Lost rewards due to double signing. |
lost_accusation_deposits money |
Lost deposits due to double signing. |
lost_seed_fees money |
Lost fees due to unpublished seed nonces (only applicable pre-Ithaca). |
lost_seed_rewards money |
Lost rewards due to unpublished seed nonces (pre-Ithaca this is single block rewards, post-Ithaca an unpublished seed nonce leads to loss of the entire endorsing rewards for a cycle). |
address hash |
Account address. |
start_time datetime |
Income cycle start time. |
end_time datetime |
Income cycle end time. |
Operation Table
Example request.
curl "https://api.tzstats.com/tables/op?time.gte=today&limit=1"
import (
"context"
"blockwatch.cc/tzstats-go"
)
// create a new query object
q := tzstats.DefaultClient.NewOpQuery()
// add filters and configure the query
q.WithFilter(tzstats.FilterModeGte, "time", "today").WithLimit(1)
// execute the query
list, err := q.Run(context.Background())
// process ops
if _, row := range list.Rows {
}
Example response (comments added for explanation).
[
[
16848289, // row_id
"endorsement", // type
"opGz2Sg1QiXchJMyz9v1rV9VN7mQadmkL81KVwteANQWZpgV5ew", // hash
689942, // height
168, // cycle
1573516812000, // time
0, // op_n
0, // op_p
"applied", // status
1, // is_success
0, // is_contract
0, // is_internal
0, // is_event
0, // is_rollup
0, // counter
0, // gas_limit
0, // gas_used
0, // storage_limit
0, // storage_paid
0.000000, // volume
0.000000, // fee
2.000000, // reward
64.000000, // deposit
0.000000, // burned
18957, // sender_id
0, // receiver_id
0, // creator_id
0, // baker_id
"128", // data
null, // parameters
null, // storage_hash
null, // big_map_diff
null, // errors
0, // days_destroyed
"tz1Z2jXfEXL7dXhs6bsLmyLFLfmAkXBzA9WE", // sender
null, // receiver
null, // creator
null // baker
"BLKYeKsYgoQWkrQwSVuR5diN5RtM4WNpQaSyzGdhm5onVZhAWVz", // block hash
"", // entrypoint name
"", // code hash
]
]
List detailed information about operations. Note that Tezos supports batch operations and internal operations created by smart contract calls in response to a transaction. On both types multiple ops share the same hash.
HTTP Request
GET https://api.tzstats.com/tables/op?args
HTTP Response
Field | Description |
---|---|
row_id uint64 |
Unique row identifier. |
type enum |
Operation type, one of activation , double_baking , double_endorsement , double_preendorsement , nonce_revelation , transaction , origination , delegation , reveal , endorsement , preendorsement , proposal , ballot , register_constant , deposits_limit or implicit event type bake , seed_slash , unfreeze , airdrop , invoice , subsidy , deposit , reward , bonus , rollup_origination , rollup_transaction , update_consensus_key , drain . |
hash hash |
Operation hash. |
height int64 |
Block height. |
cycle int64 |
Cycle in which the operation was included on-chain. |
time datetime |
Block time at which the operation was included on-chain. |
op_n int64 |
Operation position in block. |
op_p int64 |
Tezos RPC operation list position. |
status enum |
Operation execution status applied , failed , backtracked , skipped . |
is_success int64 |
Flag indicating operation was successfully applied. |
is_contract bool |
Flag indicating smart-contract calls. |
is_event bool |
Flag indicating implicit on-chain events, i.e. state changes that don’t have an operation hash such as bake , unfreeze , seed_slash , airdrop , invoice , subsidy , deposit , reward , bonus . |
is_internal bool |
Flag indicating if this operation was sent be a smart contract. |
counter int64 |
Unique sender account ’nonce’ value. |
gas_limit int64 |
Caller-defined gas limit. |
gas_used int64 |
Gas used by the operation. |
storage_limit int64 |
Caller-defined storage limit. |
storage_paid int64 |
Part of the storage the operation paid for. |
volume money |
Amount of tokens transferred in tez. |
fee money |
Fees paid in tez. |
reward money |
Rewards earned in tez. |
deposit money |
Amount of deposited tokens in tez. |
burned money |
Amount of burned tokens in tez. |
sender_id uint64 |
Unique row id of the operation sender account. |
receiver_id uint64 |
Unique row id of the transaction receiver, may be zero. |
manager_id uint64 |
Unique row id of the new manager account, may be zero. |
baker_id uint64 |
Unique row id of the new baker account, may be zero. |
data bytes |
Extra operation-specific data, see decoding operation data. |
parameters bytes |
Call parameters as hex-encoded binary data serialized according to Micheline serialization for protocol v005 Babylon. Rollup op parameters are encoded as JSON byte strings in a Micheline Pair(input, result) . |
storage_hash bytes |
Hash of the storage after update, contract-only. For performance reasons the raw storage is no longer included, use relevant explorer API endpoints to fetch individual storage updates. |
big_map_diff bytes |
Inserted, updated or deleted bigmap entries as hex-encoded binary data serialized according to Micheline serialization for protocol v005 Babylon, contract-only. |
errors bytes |
When failed, contains details about the reason as escaped JSON string. |
days_destroyed float |
Token days destroyed by this operation (tokens transferred * token idle time ). |
sender hash |
Address of the operation sender, always set. |
receiver hash |
Address of the receiver of a transaction, may be empty. |
creator hash |
Address of the original source of a contract call, may be empty. |
baker hash |
Address of the new delegate account, may be empty. |
block hash |
Block the operation was included in. |
entrypoint string |
Name of the contract entrypoint if op is a contract call. |
code_hash bytes |
Short hash to uniquely identify the contract code, first 8 bytes of the SHA256 hash over binary encoded Michelson script code. |
Proposal Table
Example request.
curl "https://api.tzstats.com/tables/proposal"
Example response (comments added for explanation).
[
[
5, // row_id
"PsBABY5HQTSkA4297zNHfsZNKtxULfL18y95qb3m53QJiXGmrbU", // hash
547386, // height
1564738976000, // time
38263, // source_id
12880576, // op_id
13, // election_id
15, // voting_period
66302, // rolls
530416000, // stake
304, // voters
"tz1eEnQhbwf6trb8Q8mPb2RaPkNk2rN7BKi8", // source
"ooDAtGzFBeRUJcEK3QRBHU3kzk31CAp2RARYE3kmU3qsrvgs8JN" // op
]
]
List full details about every submitted proposal
HTTP Request
GET https://api.tzstats.com/tables/proposal?args
HTTP Response
Field | Description |
---|---|
row_id uint64 |
Unique row identifier. |
hash hash |
Protocol hash. |
height int64 |
Proposal operation block height. |
time datetime |
Proposal operation block time. |
source_id uint64 |
Unique row_id of the proposal sender account. |
op_id uint64 |
Unique row_id of the proposal operation. |
election_id uint64 |
Unique row_id of the election this proposal was submitted in. |
voting_period int64 |
On-chain sequence number of the voting period this proposal was submitted in. |
rolls int64 |
Number of rolls that voted for this proposal in the proposal period. |
stake money |
Amount of stake that voted for this proposal in the proposal period. |
voters int64 |
Number of voters who voted for this proposal in the proposal period. |
source hash |
Address of the sender account. |
op hash |
Hash of the proposal operation. |
Rights Table
Example request.
curl "https://api.tzstats.com/tables/rights?address=tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m&cycle=154&limit=1"
import (
"context"
"blockwatch.cc/tzstats-go"
)
// create a new query object
q := tzstats.DefaultClient.NewRightsQuery()
// add filters and configure the query
q.WithFilter(tzstats.FilterModeEqual, "address", "tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m").
WithFilter(tzstats.FilterModeEqual, "cycle", 154).
Limit(1)
// execute the query
list, err := q.Run(context.Background())
// process rights
if _, row := range list.Rows {
}
Example response (comments added for explanation).
[
[
60555268, // row_id
154, // cycle
278469, // account_id
"0000000000000200..", // baking_rights
"fff777b7774cfb2f..", // endorsing_rights
"0000000000000200..", // blocks_baked
"fff777b7774cfb2f..", // blocks_endorsed
"4000000000004000..", // seeds_required
"4000000000004000..", // seeds_revealed
"tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m", // address
630785 // cycle start height
]
]
List detailed rights for baking (all priorities 0..63) and endorsing. This table is extended with future data from cycle n+5 at the start of a new cycle N. During a cycle, rights for each block are updated according to actual baker, priority and endorsers.
HTTP Request
GET https://api.tzstats.com/tables/rights?args
HTTP Response
Field | Description |
---|---|
row_id uint64 |
Unique row identifier. |
cycle int64 |
Cycle this right relates to. |
account_id uint64 |
Unique row_id of the baker who owns this right. |
baking_rights hex |
Bitset for round 0 baking rights. |
endorsing_rights hex |
Bitset for round endorsing rights. |
blocks_baked hex |
Bitset for blocks baked. |
blocks_endorsed hex |
Bitset for blocks endorsed. |
seeds_required hex |
Bitset for block seed nonce commitments where the baker is required to publish a nonce_revelation in the next cycle. |
seeds_revealed hex |
Bitset for actually revealed seed nonces. |
address hash |
Address of the baker who owns this right. |
height int64 |
Block height at cycle start. |
Snapshot Table
Example request.
curl "https://api.tzstats.com/tables/snapshot?address=tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m&cycle=150&is_selected=1&limit=1"
import (
"context"
"blockwatch.cc/tzstats-go"
)
// create a new query object
q := tzstats.DefaultClient.NewSnapshotQuery()
// add filters and configure the query
q.WithFilter(tzstats.FilterModeEqual, "address", "tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m").
WithFilter(tzstats.FilterModeEqual, "cycle", 150).
WithFilter(tzstats.FilterModeEqual, "is_selected", true).
Limit(1)
// execute the query
list, err := q.Run(context.Background())
// process rows
if _, snapshot := range list.Rows {
}
Example response (comments added for explanation).
[
[
25384634, // row_id
616960, // height
150, // cycle
1, // is_selected
1569042994000, // time
9, // index
3915, // rolls
31320000, // active_stake
278469, // account_id
278469, // baker_id
1, // is_baker
1, // is_active
3216395.662038, // balance
28104896.167331, // delegated
7, // n_delegations
361000, // since
"tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m", // address
"tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m", // baker
1553123692000 // since_time
]
]
List network-wide staking status across all bakers and delegators at snapshot blocks. This table contains all snapshots regardless of them being later chosen as cycle snapshot or not.
HTTP Request
GET https://api.tzstats.com/tables/snapshot?args
HTTP Response
Field | Description |
---|---|
row_id uint64 |
Unique row identifier. |
height int64 |
Block height of this snapshot. |
cycle int64 |
Cycle of this snapshot. |
is_selected bool |
Flag indicating this snapshot was randomly selected as cycle snapshot. |
time datetime |
Block time of this snapshot. |
index int64 |
Snapshot index in the cycle [0..15]. |
rolls int64 |
(baker only) Number of rolls owned by the baker. |
active_stake money |
(baker only) Amount of stake owned by the baker. |
account_id uint64 |
Unique row_id of the account this snapshot relates to. |
baker_id uint64 |
Unique row_id of the baker this account delegates to. |
is_baker bool |
Flag indicating the current account is a baker. |
is_active bool |
Flag indicating the current account is an active baker. |
balance money |
Account staking balance (for bakers) or spendable balance (for delegators). |
delegated money |
(baker-only) Incoming delegated amount in tz. |
n_delegations int64 |
(baker-only) Incoming number of non-zero delegations. |
since int64 |
(delegator-only) Block height at which this delegation was created. |
address hash |
Account address. |
baker hash |
Account delegate address. |
since_time datetime |
(delegator-only) Timestamp when this delegation was created. |
Supply Table
Example request.
curl "https://api.tzstats.com/tables/supply?time.gte=today&limit=1"
Example response (comments added for explanation).
[
[
1342246, // row_id
1342245, // height
327, // cycle
1613174407000, // time
866116758.904542, // total
576334364.096960, // activated
35120514.313220, // unclaimed
769208476.09957, // circulating
759835790.730190, // liquid
533295452.655376, // delegated
684826946.710113, // staking
0.000000, // shielded
681028249.309738, // active_stake
531009506.095934, // active_delegated
681028249.309738, // active_staking
2285946.559442, // inactive_delegated
3798697.400375, // inactive_staking
102153556.968822, // minted
32054769.288139, // minted_baking
70092988.673362, // minted_endorsing
5199.000000, // minted_seeding
600.007321, // minted_airdrop
0, // minted_subsidy
355396.076980, // burned
132029.815883, // burned_double_baking
31838.219485, // burned_double_endorse
9210.716000, // burned_origination
176835.688250, // burned_allocation
5481.637362, // burned_seed_miss
10.1234, // burned_storage
0, // burned_explicit
0, // burned_absence
0, // burned_rollup
60264181.814994, // frozen
58508544.000000, // frozen_deposits
1754196.047913, // frozen_rewards
1441.767081, // frozen_fees
0 // frozen_bonds
]
]
List running supply totals at each block.
HTTP Request
GET https://api.tzstats.com/tables/supply?args
HTTP Response
Field | Description |
---|---|
row_id uint64 |
Unique row identifier. |
height int64 |
Block height the current row refers to. |
cycle int64 |
Cycle the current row refers to. |
time int64 |
Block time the current row refers to. |
total float64 |
Total supply, i.e. all coins in existence. |
activated money |
Activated fundraiser supply. |
unclaimed money |
Unclaimed fundraiser supply. |
liquid money |
Circulating supply, i.e. all immediately spendable supply (total - frozen - unclaimed). |
delegated money |
Delegated supply, i.e. all spendable supply owned by delegators. |
staking money |
Staking supply, i.e. delegated supply and supply owned by bakers in form of spendable balances, frozen deposits and frozen fees. Frozen rewards are explicitly excluded because they can be slashed. |
shielded money |
Shielded supply held in Sapling contracts. |
active_stake money |
Network wide active stake (Ithaca+). |
active_delegated money |
Portion of delegated supply that is delegated to active delegates. |
active_staking money |
Portion of staking supply available to active delegates and used for securing consensus. |
inactive_delegated money |
Portion of delegated supply that is delegated to inactive delegates. |
inactive_staking money |
Portion of staking supply on inactive delegates that is not used for securing consensus. |
minted money |
Total issued supply in the form of block rewards. |
minted_baking money |
Issued supply as rewards for block baking. |
minted_endorsing money |
Issued supply as rewards for block endorsement. |
minted_seeding money |
Issued supply as rewards for seed nonce revelations. |
minted_airdrop money |
Issued supply as rewards for developers and protocol-upgrade airdrops (i.e. in Babylon). |
minted_subsidy money |
Issued supply as liquidity baking subsidy (started in Granada). |
burned money |
Total burned supply. |
burned_double_baking money |
Total supply burned due to double baking. |
burned_double_endorse money |
Total supply burned due to double endorsement. |
burned_origination money |
Total supply burned due to contract originations. |
burned_allocation money |
Total supply burned due to implicit account creation. |
burned_seed_miss money |
Total supply burned due to non published seed nonces. |
burned_storage money |
Total supply burned due to allocating storage. |
burned_explicit money |
Total supply burned by sending to a burn address. |
burned_absence money |
Total supply burned from unpaid rewards due to low participation in Ithaca+ consensus. |
burned_rollup money |
Total supply burned by rollup punishments. |
frozen money |
Currently frozen supply. |
frozen_deposits money |
Currently frozen bonds. |
frozen_rewards money |
Currently frozen rewards. |
frozen_fees money |
Currently frozen fees. |
frozen_bond money |
Currently frozen rollup bond. |
Vote Table
Example request.
curl "https://api.tzstats.com/tables/vote?voting_period=16"
Example response (comments added for explanation).
[
[
18, // row_id
13, // election_id
5, // proposal_id
16, // voting_period
"exploration", // voting_period_kind
1565333282000, // period_start_time
1565333282000, // period_end_time
557056, // period_start_height
589823, // period_end_height
70585, // eligible_rolls
564680000, // eligible_stake
464, // eligible_voters
7291, // quorum_pct
51463, // quorum_rolls
411704000, // quorum_stake
57818, // turnout_rolls
462544000, // turnout_stake
179, // turnout_voters
8191, // turnout_pct
0, // turnout_ema
37144, // yay_rolls
297152000, // yay_stake
171, // yay_voters
0, // nay_rolls
0, // nay_stake
0, // nay_voters
20674, // pass_rolls
165392000, // pass_stake
8, // pass_voters
0, // is_open
0, // is_failed
0, // is_draw
0, // no_proposal
0, // no_quorum
0, // no_majority
"PsBABY5HQTSkA4297zNHfsZNKtxULfL18y95qb3m53QJiXGmrbU" // proposal
]
]
List full details about every on-chain voting period.
HTTP Request
GET https://api.tzstats.com/tables/vote?args
HTTP Response
Field | Description |
---|---|
row_id uint64 |
Unique row identifier. |
election_id uint64 |
Unique row_id of the election this proposal was submitted in. |
proposal_id uint64 |
Unique row_id of the proposal that is voted for (or the winning proposal, if any, from the proposal period). |
voting_period int64 |
On-chain sequence number of the voting period. |
voting_period_kind enum |
Type of the voting period proposal , exploration , cooldown , promotion , adoption . |
period_start_time datetime |
Block time of vote start block. |
period_end_time datetime |
Block time of vote end block. |
period_start_height int64 |
Block height of vote start block. |
period_end_height int64 |
Block height of vote end block. |
eligible_rolls int64 |
Number of eligible rolls for this vote. |
eligible_stake money |
Amount of eligible stake for this vote. |
eligible_voters int64 |
Number of eligible voters for this vote. |
quorum_pct int64 |
Required quorum for this vote in percent. |
quorum_rolls int64 |
Required quorum for this vote in rolls. |
quorum_stake money |
Required quorum for this vote in stake. |
turnout_rolls int64 |
Actual vote participation in rolls. |
turnout_stake money |
Actual vote participation in stake. |
turnout_voters int64 |
Actual vote participation in voters. |
turnout_pct int64 |
Actual vote participation in percent. |
turnout_ema int64 |
Actual vote participation as moving average. |
yay_rolls int64 |
Count of yay voting rolls. |
yay_stake money |
Amount of yay voting stake. |
yay_voters int64 |
Count of yay voting voters. |
nay_rolls int64 |
Count of nay voting rolls. |
nay_stake money |
Amount of nay voting stake. |
nay_voters int64 |
Count of nay voting voters. |
pass_rolls int64 |
Count of pass voting rolls. |
pass_stake money |
Amount of pass voting stake. |
pass_voters int64 |
Count of pass voting voters. |
is_open bool |
Flag indicating the vote is in progress. |
is_failed bool |
Flag indicating the vote has failed to select or activate a new protocol. |
is_draw bool |
Flag indication the reason for failure was a draw between two proposals in the proposal period. |
no_proposal bool |
Flag indication the reason for failure was no submitted proposal in the proposal period. |
no_quorum bool |
Flag indication the reason for failure was participation below the required quorum. |
no_majority bool |
Flag indication the reason for failure was acceptance below the required supermajority. |
proposal int64 |
Hash of the proposal that is voted on, if any. |
Time-Series API
Time-Series overview
Endpoint | Time-Series Content
----------------------------------|---------------------------------------------------
/series/balance | historic end-of-block balances for all accounts
/series/block | aggregated block data
/series/flow | aggregated balances, freezer and delegation flows
/series/op | aggregated operations data
/series/chain | running total counters
/series/supply | running supply totals
/series/{exchange}/{market}/ohlcv | OHLCV candles
Generic Time-Series Query
https://api.tzstats.com/series/{table_code}.{format}?{args}
The time-series API is an abstraction over tables which allows for server-side aggregation of multiple result rows over time. Time-series are meant to be displayed as graphs with time on the x-axis and some aggregate value on the y-axis. Since the underlying data is still in tabular form all table filters work on time-series as well.
Note that this time-series API does not fill gaps. That means when the underlying table contains no data for a particular time interval, the corresponding time-series row will be missing. Clients should be prepared for this case and fill gaps if required.
Intervals between timestamps are equally spaced and can be controlled by the collapse
query parameter, i.e. 1d
means each interval contains 24 hours of aggregated data. Time-series data can contain fields of all supported numeric data types (e.g. no strings or binary data). The aggregation function is fixed by the semantics of the data type. This may either be a sum, a count, first, last, min, max or mean value.
On the free API tier historic access is restricted to 90 days.
Query Arguments
Time-series datasets support the following query parameters.
Argument | Description |
---|---|
columns optional |
Comma separated list of columns you like to fetch. Bulk array results will be ordered accordingly. Default is all defined columns for a series. |
collapse optional |
Aggregate numeric data over different sampling intervals. Supported values are 1m (default), 5m , 15m , 30m , 1h , 2h , 3h , 4h , 6h , 12h , 1d , 1w , 1M , 3M and 1y . |
order optional |
Return data in asc (ascending) or desc (descending) order. Default is asc . |
limit optional |
Maximum number of aggregated results returned. Limited to 50,000, default 500. |
start_date optional |
Start of the time range to query. See timestamps for syntax. |
end_date optional |
End of the time range to query. See timestamps for syntax. |
When only start or end date are provided, the other end of the range is deducted from collapse and limit. I.e. with collapse of 1d
and limit of 30
you’ll get 30 days of data after start_date or before end_date. Called without any optional parameters a query defaults to the most recent 500 minutes (end_date=now
, limit=500
and collapse=1m
).
Query Filters
Time-series support the same filters used on tables with the same filter expressions of form <column>.<operator>=<arg>
. Filters can be used on all table fields, including fields that are not part of the aggregated result such as addresses and type enums.
Balance Series
Example request.
curl "https://api.tzstats.com/series/balance?start_date=2021&collapse=1d&address=tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m"
Example response.
[
[
1609459200000, // time
571685.025618, // balance
],
[
1609545600000,
543141.025618
]
// ...
]
Lists balance history data for a selected address. Uses last as time-series aggregation function. Argument address
is required.
HTTP Request
GET https://api.tzstats.com/series/balance?args
HTTP Response
Field | Description |
---|---|
time datetime |
Timestamp, start of interval. |
balance money |
Balance at end of interval. |
Block Series
Example request.
curl "https://api.tzstats.com/series/block.json?start_date=today&collapse=1d"
Example response.
[
[
1570060800000, // time
1440, // count
32, // n_endorsed_slots
25002, // n_ops_applied
6, // n_ops_failed
2, // n_calls
0, // n_rollup_calls
0, // n_events
2000, // n_tx
1489819.569887, // volume
2.223532, // fee
79822.000000, // reward
2565504.000000, // deposit
8522.749680, // activated_supply
42.148000, // minted_supply
42.148000, // burned_supply
152, // n_new_accounts
0, // n_new_contracts
46, // n_cleared_accounts
164, // n_funded_accounts
8167612, // gas_used
214 // storage_paid
]
]
Lists aggregate data about blocks. Filters are the same as on the block table, but response fields are limited to numeric data that can be aggregated over time. Aggregation function for all fields is sum.
HTTP Request
GET https://api.tzstats.com/series/block?args
HTTP Response
Field | Description |
---|---|
time datetime |
Timestamp, start of interval. |
count int |
Number of aggregated rows for this time bucket. |
n_endorsed_slots int64 |
Count of endorsed slots. |
n_ops_applied int |
Count of successful operations. |
n_ops_failed int |
Count of failed operations. |
n_calls int |
Count of smart-contract calls sent by externally owned accounts. |
n_rollup_calls int |
Count of rollup calls. |
n_events int |
Count of implicit smart-contract operations (issued by the protocol instead of users). |
n_tx int |
Count of transactions. |
volume int |
Count of amount of tokens moved between accounts. |
fee float |
Total fee paid (and frozen) by all operations. |
reward float |
Reward earned (and frozen) by baker. |
deposit float |
Deposit frozen by baker. |
activated_supply float |
Total amount of commitments activated in tez. |
minted_supply float |
Total amount of new tokens minted by operations in tez. |
burned_supply float |
Total amount of tokens burned by operations in tez. |
n_new_accounts int |
Count of new accounts created regardless of type. |
n_new_contracts int |
Count of created smart contracts (KT1 with code). |
n_cleared_accounts int |
Count of accounts that were emptied (final balance = 0). |
n_funded_accounts int |
Count of accounts that were funded by operations (this includes all new accounts plus previously cleared accounts that were funded again). |
gas_used int |
Total gas consumed by operations. |
storage_paid int |
Total sum of new storage allocated by operations. |
Flow Series
Example request (network-wide re-delegation flows).
curl "https://api.tzstats.com/series/flow?start_date=today&collapse=1d&category=delegation"
Example response.
[
[
1570060800000, // time
200650.535155, // amount_in
246036.709877 // amount_out
12, // count
]
]
Lists aggregate data about flows. Filters are the same as on the flow table, but response fields are limited to numeric data that can be aggregated over time. Aggregation function for all fields is sum.
An interesting feature of flow series is that you can reconstruct the entire balance and delegation history of an account. You can either start at account creation time assuming zero balances or start at the current account state and work your way backwards through flows.
HTTP Request
GET https://api.tzstats.com/series/flow?args
HTTP Response
Field | Description |
---|---|
time datetime |
Timestamp, start of interval. |
amount_in float |
Incoming amount during interval in tez. |
amount_out float |
Outgoing amount during interval in tez. |
count int |
Number of aggregated rows for this time bucket. |
Operation Series
Example request.
curl "https://api.tzstats.com/series/op?start_date=today&collapse=1d"
Example response.
[
[
1570060800000, // time
8187812, // gas_used
0, // storage_paid
1493221.154887, // volume
2.228532, // fee
63790.000000, // reward
2052480.000000, // deposit
42.148000, // burned
2000, // count
]
]
Lists aggregate data about operations. Filters are the same as on the operation table, but response fields are limited to numeric data that can be aggregated over time. Aggregation function for all fields is sum.
HTTP Request
GET https://api.tzstats.com/series/op?args
HTTP Response
Field | Description |
---|---|
time datetime |
Timestamp, start of interval. |
gas_used int |
Total gas used by all operations. |
storage_paid int |
Total storage paid by all operations. |
volume float |
Total amount of tokens transferred by all operations in tez. |
fee float |
Fees paid by all operation in tez. |
reward float |
Rewards earned in by all operation tez. |
deposit float |
Amount of deposited tokens by all operation in tez. |
burned float |
Amount of burned tokens by all operation in tez. |
count int |
Number of aggregated rows for this time bucket. |
Chain Series
Example request.
curl "https://api.tzstats.com/series/chain?start_date=today&collapse=1d"
Example response.
[
[
815464, // height
199, // cycle
1581160828000, // time
425778, // total_accounts
316, // total_contracts
0, // total_rollups
20554157, // total_ops
234567, // total_ops_failed
104074, // total_contract_ops
20000, // total_contract_calls
0, // total_rollup_calls
22179, // total_activations
25277, // total_nonce_revelations
17393631, // total_endorsements
0, // total_preendorsements
131, // total_double_bakings
24, // total_double_endorsements
54288, // total_delegations
272080, // total_reveals
29052, // total_originations
2755973, // total_transactions
494, // total_proposals
1036, // total_ballots
0, // total_constants
0, // total_set_limits
122042155, // total_storage_bytes
387718, // funded_accounts
200000, // dust_accounts
0, // ghost_accounts
9346, // unclaimed_accounts
29352, // total_delegators
28005, // active_delegators
1347, // inactive_delegators
10, // dust_delegators
4031, // total_bakers
461, // active_bakers
3570, // inactive_bakers
8, // zero_bakers
138, // self_bakers
68, // single_bakers
255, // multi_bakers
81005, // rolls
433 // roll_owners
1, // count
]
]
Lists running totals and counters at each block. Collapse selects data from the first block in a time window.
HTTP Request
GET https://api.tzstats.com/series/chain?args
HTTP Response
Field | Description |
---|---|
height int64 |
block height |
cycle int64 |
block cycle |
time int64 |
block creation time |
total_accounts int64 |
total number of accounts (all types, all states) |
total_contracts int64 |
total number of deployed smart contracts (KT1 with code) |
total_rollups int64 |
total number of deployed rollups |
total_ops int64 |
total number of operations (external and internal, but not implicit events) |
total_ops_failed int64 |
total number of failed operations |
total_contract_ops int64 |
total number of calls to KT1 contracts |
total_contract_calls int64 |
total number of calls to KT1 contracts sent by EOA |
total_rollup_calls int64 |
total number of rollup calls |
total_activations int64 |
total number of fundraiser account activations |
total_nonce_revelations int64 |
total number of seed nonce revelations |
total_endorsements int64 |
total number of endorsement operations |
total_preendorsements int64 |
total number of preendorsement operations |
total_double_bakings int64 |
total number of double-baking denunciations |
total_double_endorsements int64 |
total number of double-(pre)endorsing denunciations |
total_delegations int64 |
total number of delegations (including delegation withdrawals) |
total_reveals int64 |
total number of pubkey revelations |
total_originations int64 |
total number of contract originations (contains pre-Babylon delegation contracts) |
total_transactions int64 |
total number of transactions (contains internal transactions) |
total_proposals int64 |
total number of voting proposals operations |
total_ballots int64 |
total number of voting ballots |
total_constants int64 |
total number of registered global constants |
total_set_limits int64 |
total number of deposit limit operations |
total_storage_bytes int64 |
total number of allocated storage in bytes |
funded_accounts int64 |
current number of funded accounts (non-zero balance) |
dust_accounts int64 |
current number of dust accounts (0 < balance < 1 tez) |
ghost_accounts int64 |
current number of ghost accounts (unfunded accounts referenced in contracts as token owners or admins) |
unclaimed_accounts int64 |
current number of unclaimed fundraiser accounts |
total_delegators int64 |
current number on non-zero balance delegators |
active_delegators int64 |
current number of non-zero balance delegators delegating to active delegates |
inactive_delegators int64 |
current number of non-zero balance delegators delegating to inactive delegates |
dust_delegators int64 |
current number of dust delegators |
total_bakers int64 |
current number of registered bakers (active and inactive) |
active_bakers int64 |
current number of active bakers |
inactive_bakers int64 |
current number of inactive bakers |
zero_bakers int64 |
current number of active bakers with zero staking balance |
self_bakers int64 |
current number of active bakers with no incoming delegation |
single_bakers int64 |
current number of active bakers with 1 incoming delegation |
multi_bakers int64 |
current number of active bakers with >1 incoming delegations (delegation services) |
rolls int64 |
current number of rolls |
roll_owners int64 |
current number of distinct active bakers with rolls |
count int |
Number of aggregated rows. This series does a selection, so count is always equal to 1. |
Supply Series
Example request.
curl "https://api.tzstats.com/series/supply?start_date=today&collapse=1d"
Example response.
[
[
815478, // height
199, // cycle
1581161668000, // time
825170161.728791, // total
548313102.872648, // activated
63141775.537532, // unclaimed
699889185.554441, // circulating
699889185.554441, // liquid
516489777.211404, // delegated
660867550.008684, // staking
0, // shieled
649473768.198626, // active_stake
514264193.700025, // active_delegated
649473768.198626, // active_staking
2225583.511379, // inactive_delegated
11393781.810058, // inactive_staking
61045504.551923, // minted
12446481.404808, // minted_baking
48595263.514794, // minted_endorsing
3159.625000, // minted_seeding
600.007321, // minted_airdrop
0, // minted_subsidy
193940.835832, // burned
114197.267834, // burned_double_baking
31838.219485, // burned_double_endorse
7221.767000, // burned_origination
37584.857000, // burned_allocation
3098.724513, // burned_seed_miss
10.001, // burned_storage
0, // burned_explicit
0, // burned_absence
0, // burned_rollup
54639772.184175, // frozen
52997504.000000, // frozen_deposits
1641852.516645, // frozen_rewards
415.667530 // frozen_fees
0 // frozen_bonds
1, // count
]
]
Lists running supply totals at each block. Collapse selects data from the first block in a time window.
HTTP Request
GET https://api.tzstats.com/series/supply?args
HTTP Response
Field | Description |
---|---|
height int64 |
block height |
cycle int64 |
block cycle |
time datetime |
block creation time |
total money |
total available supply (including unclaimed) |
activated money |
total activated fundraiser supply |
unclaimed money |
total non-activated fundraiser supply |
circulating money |
current circulating supply (by unanimous consent this is total - unvested even though frozen supply cannot move next block but still counts against total network value) |
liquid money |
metric to show how much is economically available for sale, i.e. total - frozen - unvested |
delegated money |
current delegated supply (balances of all delegators) |
staking money |
current staking supply (balances of delegators and all bakers even if inactive, see below) |
shielded money |
current shielded supply (balances held in Sapling contracts) |
active_stake money |
current active stake (Ithaca+) |
active_delegated money |
current active delegated supply (balances of all delegators delegating to active bakers) |
active_staking money |
current active staking supply (balances of all active bakers and their delegators) |
inactive_delegated money |
current inactive delegated supply (balances of all delegators delegating to inactive bakers) |
inactive_staking money |
current inactive staking supply (balances of all inactive bakers and their delegators) |
minted money |
total supply minted so far |
minted_baking money |
total supply minted as baking rewards |
minted_endorsing money |
total supply minted as endorsing rewards |
minted_seeding money |
total supply minted as seed nonce revelation rewards |
minted_airdrop money |
total supply minted in airdrops |
minted_subsidy money |
Issued supply as liquidity baking subsidy (started in Granada). |
burned money |
total supply burned so far |
burned_double_baking money |
total supply burned by double baking denunciations |
burned_double_endorse money |
total supply burned by double endorsing denunciations |
burned_origination money |
total supply burned by contract originations |
burned_allocation money |
total supply burned by implicit account allocations |
burned_seed_miss money |
total supply burned by seed nonce revelation misses |
burned_storage money |
total supply burned by allocating storage |
burned_explicit money |
supply burned by sending it to a burn address |
burned_absence money |
supply burned by not issuing endorsing rewards to absent bakers |
burned_rollup money |
supply burned by rollup slashing |
frozen money |
current frozen supply |
frozen_deposits money |
current frozen deposits |
frozen_rewards money |
current frozen rewards |
frozen_fees money |
current frozen fees |
frozen_bonds money |
current frozen rollup bonds |
count int |
Number of aggregated rows. This series does a selection, so count is always equal to 1. |
OHLCV Series
Example request for the 24 most recent hourly candles.
curl "https://api.tzstats.com/series/kraken/XTZ_USD/ohlcv?start_date=now-24h&collapse=1h"
Example response.
[
[
1570032000000, // time
0.94000, // open
0.94460, // high
0.90890, // low
0.92180, // close
0.92183, // vwap
36, // n_trades
3, // n_buy
33, // n_sell
7878.17322, // vol_base
7262.35661, // vol_quote
162.09115, // vol_buy_base
150.18552, // vol_buy_quote
7716.08207, // vol_sell_base
7112.17109 // vol_sell_quote
],
// ...
]
List aggregated OHLCV market data.
HTTP Request
GET https://api.tzstats.com/series/{exchange}/{market}/ohlcv
HTTP Response
Field | Description |
---|---|
time datetime |
Timestamp, start of interval. |
open float |
Opening price. |
high float |
Highest price. |
low float |
Lowest price. |
close float |
Closing price. |
vwap float |
Volume weighted average price from smallest increment (1 min). |
n_trades int |
Count of trades in the time-frame. |
n_buy int |
Count of trades where the market maker was buyer. |
n_sell int |
Count of trades where the market maker was seller. |
vol_base float |
Total trading volume in base currency (i.e. always XTZ). |
vol_quote float |
Total trading volume in quote currency. |
vol_buy_base float |
Buy-side volume in base currency. |
vol_buy_quote float |
Buy-side volume in quote currency. |
vol_sell_base float |
Sell-side volume in base currency. |
vol_sell_quote float |
Sell-side volume in quote currency. |
Changelog
Recent changes and additions to the TzStats Data API.
2023-03-28
Mumbai release
- op model (/exolorer/op/:id)
- add Mumbai operations wrapped into
rollup_origination
androllup_transaction
transfer_ticket
(split from tx_rollup, made it an explicit op)smart_rollup_add_messages
smart_rollup_cement
smart_rollup_originate
smart_rollup_execute_outbox_message
smart_rollup_publish
smart_rollup_recover_bond
smart_rollup_refute
smart_rollup_timeout
- export ticket updates on tz1 accounts
- add Mumbai operations wrapped into
- constants model (/explorer/config/:id)
- removed all but indexer-related properties, use Tezos RPC for protocol constants instead
- tables API: removed translation from
head
keyword for cycle and block filters /explorer/account/:id/contracts
will list factory created contracts now- fixes
- return raw Micheline data on broken contract call parameters
- bigmap type detection for union types
- handle storage burn on transfer_ticket
2022-12-06
Lima release
- op model
- add Lima operations
drain_delegate
andupdate_consensus_key
- removed
days_destroyed
without replacement - add
code_hash
field on contract calls to help filter by receiver contract type - add Lima
ticket_updates
on contract calls that mint, burn or transfer tickets
- add Lima operations
- block model
- add Lima
proposer_consensus_key_id
andproposer_consensus_key
fields - add Lima
baker_consensus_key_id
andbaker_consensus_key
fields - removed
days_destroyed
without replacement
- add Lima
- account model (update statistics fields)
- replace
n_ops
withn_tx_success
- replace
n_ops_failed
withn_tx_failed
- replace
n_tx
byn_tx_out
andn_tx_in
- drop
token_gen_min
without replacement - drop
token_gen_max
without replacement - drop
n_constants
without replacement - drop
n_origination
without replacement - drop
n_delegation
without replacement - add
total_fees_used
for total fees from tx where this account is receiver - hide
frozen_bond
,lost_bond
,is_activated
,is_baker
,is_contract
flags if unused
- replace
- contract model (update statistics fields)
- replace
n_calls_success
byn_calls_in
- add
n_calls_out
- add
total_fees_used
for all fees pay for calling this contract
- replace
- ticket models
- add
ticket_update
table to track ticket updates - add
ticket_type
table to track ticket types (== ticketer, type and content)
- add
- constants model (cleanup)
- replace
tokens_per_roll
withminimal_stake
- remove
time_between_blocks
(useminimal_block_delay
anddelay_increment_per_round
instead) - remove
block_rewards_v6
andendorsement_rewards_v6
without replacement - remove
max_proposals_per_delegate
,max_revelations_per_block
,max_anon_ops_per_block
without replacement - remove
nonce_length
,proof_of_work_nonce_size
,proof_of_work_threshold
without replacement - remove
test_chain_duration
without replacement
- replace
- balance model
- drop
valid_until
field and always store most recent balance
- drop
- Micheline
- add new opcodes Lima
D_LAMBDA_REC
,I_LAMBDA_REC
- replace deprecated opcode
TICKET
with new opcode of same name (breaking!)
- add new opcodes Lima
- fixes
- fix missing bigmap type annotations post Jakarta
- fix detecting protocol invoices
- fix use consistent field
volume
for all invoices - fix balance history start value when out of request window
2022-09-06
Kathmandu release
- new
vdf_revelation
andincrease_paid_storage
operations - add
event
table - add
events
field to contract calls (off by default on lists, enable withstorage=1
) - add
EMIT
opcode - add
script
to explorer API originations - add
code_hash
to explorer and table API contract calls - fix contract table time filters
- return
storage
in explorer API subsidy operations - store ghost accounts (unfunded addresses that appear in smart contract storage)
- add
ghost_accounts
to chain model - don’t return deleted bigmaps
- strip unused info from on-chain constants
- fix bigmap metadata timestamps
- fix time-series gap fill
2022-06-15
Jakarta release
- support new (transaction) optimistic rollup operations
- extend income, supply, chain, block, operation with new rollup fields
- replace hash indexes on operation, block and bigmap tables with bloom filters
- use active stake for governance counters in Ithaca+
- new Micheline opcodes
- support filter by vote period in ballot and vote tables
- keep zero delegators in snapshot index
- fix nested entrypoint detection (use executed entrypoint instead of called entrypoint; i.e. for nested entrypoints only leafs inside OR trees are used)
Model changes
- account model
- new balance type
frozen_bond
for current rollup bonds - new
lost_bond
for rollup slashes
- new balance type
- baker model
- new
active_stake
- new
- bigmap model
- add
delete_height
,delete_block
,delete_time
fields to signal when a bigmap was removed from storage - fix returning dynamic allocated bigmaps in responses
- add
- block model
- new counter
n_rollup_calls
- new counter
- chain model
- new
total_ops_failed
,total_rollup_calls
andtotal_rollups
- new
- contract model
- new
storage_burn
counter
- new
- flow model
- new balance category
bond
- new operations types
rollup_origination
,rollup_transaction
,rollup_reward
,rollup_penalty
- new balance category
- income model
- add
lost_accusation_fees
,lost_accusation_rewards
,lost_accusation_deposits
,lost_seed_fees
,lost_seed_rewards
, - renamed
total_bonds
tototal_deposits
to avoid name conflict with rollup bonds contribution_percent
andavg_contribution_64
are now counted up until position in cycle, formerly this was end of cycle which skewed numbers for the current cycle
- add
- op model
- new types
rollup_origination
androllup_transaction
- rollup op arguments are packed into
parameters
- new parameter fields
l2_address
,method
andarguments
- different rollup op types are represented as method names
- new
is_rollup
flag
- new types
- snapshot model
- new
active_stake
- new
- supply model
- new
active_stake
,frozen_bonds
andburned_rollup
(for penalties)
- new
- tip model
- removed
rolls
androll_owners
- added
total_contracts
andtotal_rollups
- removed
- vote model
- new
eligible_stake
,quorum_stake
,turnout_stake
,yay_stake
,nay_stake
,pass_stake
- new
2022-04-18
- baker model
- added
blocks_not_baked
,blocks_endorsed
andblocks_not_endorsed
counters - fixed output for
deposits_limit
- added
is_funded
state to delegator data - added income fields to snapshot data
- added
- income model
- added
n_blocks_not_baked
,n_blocks_endorsed
andn_blocks_not_endorsed
counters - fixed
expected_income
andactive_stake
numbers for the first 6 Ithaca cycles
- added
- balance model
- time-series requests require an address
- op model
- fixed endorsement power, added preendorsement power
2022-03-25
Tezos Ithaca protocol support and refactoring for Tenderbake consensus.
Refactoring
- new Ithaca operations and events
- new baker table with baker specific data and stats
- new balance history table and time series
- separate endorsements from operations table
- simplified rights table to use bitsets instead of individual rights
Breaking changes
- general
- renamed API argument
collapse
tomerge
(used for nesting internal and batch operations) - renamed all occurences of
delegate
tobaker
- renamed API argument
- block model
- we no longer store orphan blocks
- dropped fields
endorsed_slots
,fitness
,is_orphan
,parent_id
,slot_mask
,gas_price
and most counters such asn_ops_contract
,n_tx
,n_activation
,n_seed_nonce_revelation
,n_double_baking_evidence
,n_double_endorsement_evidence
,n_endorsement
,n_delegation
,n_reveal
,n_origination
,n_proposal
,n_ballot
,n_register_constant
- added fields
proposer
,proposer_id
,minted_supply
- renamed fields
priority
toround
storage_size
tostorage_paid
n_ops
ton_ops_applied
n_ops_implicit
ton_events
- operation model
- renamed
implicit
operations toevents
- new global stable/unique
id
instead ofrow_id
- unique
op_n
event counter inside each block (before, batch and internal operations shared the same op_n) - switched
sender
andcreator
accounts on internal operations such that an internal call always lists the original signer of the outer operation as sender- refactored op list ids for protocol upgrade events (
-3
), block-level events like auto (un)freeze and rewards payments (-2
) and block header implicit operations like liquidity baking (-1
)
- refactored op list ids for protocol upgrade events (
- dropped op table fields
has_data
,branch_height
,branch_hash
,branch_depth
,is_orphan
,is_sapling
,entrypoint_id
,gas_price
,storage_size
,has_data
- penalty ops now use
accuser
andoffender
instead ofsender
andreceiver
- internal ops now use
source
instead ofcreator
for the outer transaction signer - ops in lists (block, account) no longer contain storage updates, use
storage=1
to add - op lists default to
order=desc
(most recent transactions first), useorder=asc
for previous behaviour) - renamed fields
is_implicit
tois_event
block_hash
toblock
delegate_id
anddelegate
tobaker_id
andbaker
- renamed operation types
seed_nonce_revelation
tononce_revelation
double_baking_evidence
todouble_baking
double_endorsement_evidence
todouble_endorsement
- added new operation and event types for Tenderbake
preendorsement
for preendorsements (only visible when block round > 0)double_preendorsement
for double signatures on preendorsementsdeposits_limit
for explicit baker deposit limit opsdeposit
for explicit deposit freeze and unfreeze eventsreward
for endorsement reward paymentsbonus
for baker bonus payments (i.e. including more than threshold endorsements)subsidy
for minting liquidity baking subsidy (was typetransaction
before)
- renamed
- rights model
- dropped individual rights in favour of per-cycle bitmaps (only round 0 baking rights and endorsing rights are available)
- endorsements no longer store power or list of slots
- baking rights no longer store priority/round
- flow model
- dropped fields
account_type
,op_l
,op_p
,op_n
,op_c
,op_i
,token_gen_min
andtoken_gen_min
- added new types
bonus
,deposit
anddeposits_limit
for Ithaca
- dropped fields
- chain model
- dropped field
total_paid_bytes
(duplicate oftotal_storage_bytes
) - added fields
total_set_limits
andtotal_preendorsements
- renamed fields
*_delegates
to*_bakers
- renamed
total_double_baking_evidences
tototal_double_bakings
- renamed
total_double_endorsement_evidences
tototal_double_endorsements
- renamed
total_seed_nonce_revelations
tototal_nonce_revelations
- dropped field
- cycle model
- renamed
missed_priorities
intomissed_rounds
- renamed
priority_min|max|mean
intoround_min|max|mean
- dropped
n_orphans
- renamed
- tip
- moved
deployments
from to separate endpoint/explorer/protocols
- moved
- account model
- split account and baker data into two tables/models
- dropped all baker related fields from account
- removed
/explorer/account/{address}/managed
and/explorer/account/{address}/ballots
endpoints
- income model
- added new fields
active_stake
,endorsing_loss
- replaced fields
double_baking_income
,double_endorsing_income
withaccusation_income
- replaced fields
lost_accusation_fees
,lost_accusation_rewards
,lost_accusation_deposits
withaccusation_loss
- replaced
lost_revelation_fees
,lost_revelation_rewards
withseed_loss
- removed fields
n_blocks_lost
,n_blocks_stolen
,n_slots_missed
,expected_bonds
,missed_endorsing_income
without replacement
- added new fields
- baker model
- use
/explorer/bakers/{address}
endpoint for baker-specific data, add?meta=1
for baker statistics /explorer/bakers/{address}/votes
to list baker votes (defaults to descending order, i.e. newest first)/explorer/bakers/{address}/endorsements
to list baker endorsements (defaults to descending order, i.e. newest first)/explorer/bakers/{address}/delegations
to list baker delegation events (defaults to descending order, i.e. newest first)/explorer/bakers/{address}/income/{cycle}
returns baker income for a cycle/explorer/bakers/{address}/rights/{cycle}
returns baker rights and their use for a cycle/explorer/bakers/{address}/delegators/{cycle}
returns list of delegators at shapshot block for a cycle
- use
- bigmap model
- renamed
key_hash
tohash
in bigmap keys and bigmap update table
- renamed
2021-11-20
Tezos Hangzhou protocol support
- ETL: support for new Michelson smart contract on-chain views, global constants and timelocks
- ETL: new global constants table
- ETL: global constants are automatically injected into new originated contracts
- API: new endpoints
/tables/constant
and/explorer/constant/{hash}
- API: new typedefs for on-chain views in
/explorer/contracts/{address}/script
Fixes and enhancements
- ETL: fix bigmap copy owner on origination
- ETL: improve TTL block cache usage
- API: support long collapse intervals
w
week,M
month,y
year for time-series - API: fix future vote end date
- API: block table, series and block explorer endpoints
- removed
n_new_managed
,n_new_implicit
- changed
n_new_accounts
to count EOA only (before this also counted new contracts) - new
n_register_constant
,n_contract_calls
- removed
- API: chain table and series
- removed
total_implicit
,total_managed
- changed
total_accounts
to count EOA only (before this also counted new contracts) - new
total_constants
,total_contract_calls
- new
dust_accounts
anddust_delegators
for accounts with balance <1tez
- removed
- API: supply table and series
- renamed
burned_implicit
toburned_allocation
- new
burned_storage
(storage fees) andburned_explicit
(sent to burn address)
- renamed
Breaking changes
- block table and series field order
- chain table and series field order
- suply table and series field order
2021-09-04
This release is a minor update with a few performance improvements and several new fields.
- API: added virtual
address
filter to operation table which allows to express OR condition across all address fields (sender, receiver, delegate, creator) - API: added
height
andtime
to bigmap values table - API: added
entrypoint
name to explorer opperations - API: added
block_hash
field and filter to operation table - API: added
entrypoint
name and filter to operation table - API: renamed operation field
branch
tobranch_hash
- API: added optional
predecessor
block hash to block table (Note: this field must be explicitly requested in columns list)
2021-07-24
This API release introduces Granada support, changes the structure of rights and upgrades to a new bigmap index that is now split into 3 parts (bigmaps, bigmap_values and bigmap_updates). The bigmap explorer API does not change, but the tables API will reflect that new structure.
BREAKING CHANGES
- API: replace single
bigmap
tables with 3 new tablesbigmaps
(allocs),bigmap_updates
(updates only, not indexed) andbigmap_values
(live key/value pairs, indexed by key hash) - API: removed bigmap info flags
is_removed
that used to signal whether a bigmap was deleted - API: removed bigmap metadata flags
is_removed
andis_replaced
on values/keys - API: bigmap updates no longer contain alloc
- API: added new field
slots
to rights table, only used for endorsing rights to collect all slots assigned to a baker (before each individual slot was stored as a single rights table entry) - API: replaced block field
endorsed_slots
(uint32) withslot_mask
(hex string) on explorer and table endpoints, it remains a bitset (32 or 256 bits) - API: replaced block field
rights.slot
torights.slots
and changed type to array of integers to list all endorsement slots for a baker in a single entry - API: op field
data
for type endorsement now contains a 256bit hex string instead of 32bit
New fields
- API: added block fields
lb_esc_vote
andlb_esc_ema
to track liquidity baking - API: added field
minted_subsidy
to supply counters - API: added blockchain config fields
liquidity_baking_escape_ema_threshold
,liquidity_baking_subsidy
,liquidity_baking_sunset_level
,minimal_block_delay
2021-04-16
- API: NEW contract storage, bigmap, parameters data decoding engine
- API: new JSON-schema powered metadata endpoints
/metadata
- API: add
confirmations
to operations - API: fix offset argument on contract calls
BREAKING CHANGES
With this release we introduce a new Micheline decoding engine which changes how data and typedefs are represented for contract storage, bigmaps and operation parameters.
- API: new data formats for type definitions on contract storage, entrypoints, bigmap key and value types
- new type definitions using nested arrays of
name
,type
,args
objects - value key names are plain annotation names with
@type
as before - more record nesting levels exported from Micheline type annotations
- new type definitions using nested arrays of
- API: new data formats for bigmap keys and values, deprecated fields
key_binary
,key_unpacked
,key_pretty
,value_unpacked
,key_type
,key_encoding
- API: contract data decoding does no longer unpack bytes to string/timestamp/etc. automatically, use argument
unpack
- API: deprecated endpoints
/explorer/bigmap/:id/type
(merged into bigmap info), - API: changed bigmap update URL for single keys from
/explorer/bigmap/:id/:key/updates
to/explorer/bigmap/:id/updates/:key
- API: supply metrics: removed
vesting
andcirculating
, addedliquid
(= total - frozen - unclaimed)
2021-02-10
A big deal of behind-the-scenes performance improvements went into this release, so that we are able to deliver the snappy response times you’re used to. We’ve started to prune irrelevant historic data from rights
(unused block priorities) and snapshots
(non-selected baker and delegator balances) to make querying relevant data faster.
We also reworked our smart contract data model, stripping less useful fields available elsewhere and adding new fields like detected interface standard and used Michelson features. When contract code is patched by a protocol upgrade we now add an implicit migration operation and update the stored representation of contract code as well. The previous version of the contract code is still available, either as part of the origination or the most recent migration operation.
This release adds support for Edo, namely Michelson extensions tickets, comb pairs and lazy storage (currently still exposed as bigmap on the API) as well as simple Sapling support (tracking total Sapling supply and flows). Please reach out to tzstats@blockwatch.cc if you need additional Sapling or ticket support.
We decided to not remove deprecated operation listing endpoints because many people still use them and we found a way to optimize their performance.
BREAKING CHANGES
- api/contract: simplified and extended contract data model
- api/contract: replaced
bigmap_ids
array (numeric only) withbigmaps
object (mapping name to bigmap id) - api/contract: renamed
/explorer/contract/{hash}/manager
to/explorer/contract/{hash}/creator
- api/block: removed
endorsers
list and replaced it with an optional more informativerights
list (use new query argrights=1
) - api/account: renamed
/explorer/account/{hash}/managed
to/explorer/account/{hash}/contracts
- api/account: removed deprecated fields
is_delegatable
,is_spendable
andis_vesting
- api/account: renamed field
manager
tocreator
- api/op: renamed field
manager
tocreator
- api/op: branch info moved behind the
meta
flag
NEW FEATURES
- api/metadata: added structured metadata to accounts, available as optional embedded field
metadata
on all accounts, operations, contracts, and contract calls (use new query argmeta=1
) - api/metadata: account metadata is also available as list on
/explorer/metadata
and single objects on/explorer/metadata/{hash}
- api/contract: added new lists
interfaces
andfeatures
that signal whether a contract implements any well-known interface standard or uses a specific Michelson feature - api/block: added new
rights
list that details owner and status of baking and endorsing rights - api/bakers: added new endpoint
/explorer/bakers
with several filters to list all active public and non-public bakers - api/op: new implicit contract migration operations as event log about changes to deployed contracts on protocol upgrades
- api/protocols:: new endpoint
/explorer/protocols
to list all deployed protocols, - api/bigmap: support bigmap pair keys from comma separated url args
- etl support Edonet, Edo protocol, new Edo opcodes, comb pairs, tickets and lazy storage
- etl detect Sapling enabled accounts, flag them in contract
features
- etl/flow new
is_shielded
andis_unshielded
flags to indicate flows into and out of Sapling contracts - etl/op new
is_sapling
flag to indicate a transaction interacted with a Sapling contracts
FIXES
- etl/account: fix removing accounts on rollback
- api/bigmap: more bigmap value rendering fixes
DEPRECATION NOTICES
- api/explorer:
deployments
list in/explorer/tip
will be removed in a future version
2020-06-24
To handle the surge in volume we’re optimizing a few of the most heavily used API endpoints. Our aim is to improve user experience and stability for everybody.
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 be available in parallel for a while. For high-speed high-volume access, consider using the table API endpoints. Table access is much faster since data is streamed and requires less calls due to higher limits.
As we keep adding new fields to tables and time-series the default order of JSON bulk arrays may change over time. To ensure that our API always returns the field order you expect, use the columns
query argument. The order of columns you specify is exactly the order that’s returned.
DEPRECATION NOTICES
- api/account: listing operations with
/explorer/account/{hash}/ops
and the embeddedops
array will be removed in the next API release - api/block: listing operations with
/explorer/block/{hash}/ops
and the embeddedops
array will be removed in the next API release
BREAKING CHANGES
- api/block:
nonce
is now returned as hex string - api/cycle: renamed
active_{bakers|endorsers}
toworking_{bakers|endorsers}
, also note the change in meaning ofactive_bakers
as described below - api/account: renamed explorer and table field
flow_rank
tovolume_rank
- api/account: moved
call_stats
from account table to contract table - api/account: we’re now hiding unused baker fields from non-baker accounts
- api/account: changed
/explorer/account/{hash}/ballots
return value from an account object with embeddedballots
field to a ballots array
FIXES
- api/account: fixed traffic and volume rank sorting
- api/account: return origination only when no entrypoint filter is used
- api/account: fixed
since
off-by-one bug on contract call and account operation lists - api/account: fixed
until
param not limiting call/operation lists for recently active accounts - api/account: fixed duplicates in account operation list
- api/operation: fixed return data from bigmap copy and bigmap delete operations
- api/cache: fixed cache expiration time on account, contract, rights
- etl/income: don’t count unfrozen rewards into end-of-cycle snapshots
- etl/income: use max block reward for counting missed rewards on priority zero baker and max endorsement reward for missed endorsement slots
- etl/statistics: fixed active delegation counting for foundation bakers
- etl/statistics: fixed block volume counting for failed ops
- etl/account: fixed pubkey updates on reveal that caused some keys to be scrambled
- api/deployments: fixed protocol version lookup and deployment info
- etl/income: fixed
total_income
to include all fees and denunciation rewards
NEW FEATURES
- api/operation:
delegation
operations now havevolume
field set to the initial delegated balance - api/operation: new fields
is_batch
andbatch_volume
on first operation in an explorer batch list - api/operation: added new implicit activation and delegation operations from genesis bootstrap
- api/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 - api/operation: added implicit baker registrations in protocols v001 (due to a protocol bug) and v002 (at migration)
- api/series: new virtual column
count
that contains the number of aggregated entries per bucket - api/account: support query arguments
limit
,cursor
,order
on ballot lists - api/account: new explorer fields
avg_luck_64
,avg_performance_64
,avg_contribution_64
,baker_version
,delegate_until
anddelegate_until_time
- api/cycle: new explorer fields
snapshot_time
,active_bakers
andactive_delegators
for a total number of all registered bakers and funded delegators at cycle snapshot - api/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 - api/ballot: new table filter modes
ne
,in
,nin
forballot
- api/rights: new table filter modes
ne
,in
,nin
fortype
- api/rights: new flag
is_bond_miss
to differentiate loss events between low bonds and other failures - 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 - new explorer endpoint
/explorer/election/:id/:stage/ballots
to list all ballots cast during a voting period - new explorer endpoint
/explorer/account/{hash}/operations
(replaces embeds on../ops
) - new explorer endpoint
/explorer/block/{hash}/operations
(replaces embeds on../ops
) - support
filename
argument for CSV downloads from tables and time-series
2020-02-24
FIXES
- etl/model: frozen deposits, rewards and fees were not correctly deducted from delegate balance and total frozen supply
- etl/model: fixed spelling of
denunciation
type in flow table - chain: use protocol constants for snapshot block calculations (was a fixed offset value before that only worked on mainnet)
- chain: tolerate arbitrary padding after binary address values in contract storage (when manually packed into type bytes inside a contract one can add an optional annotation which now gets stripped to obtain a valid address)
- etl/index: fix baker performance on zero rights to avoid edge case in 3rd party reputation algorithms that penalized bakers without rights, no income still yields 100% performance now
- micheline/entrypoint: fix detecting named Unit entrypoints
- etl/index: fix empty bigmap operation that deletes all keys and allocates a new bigmap, added
is_removed
bool field to explorer/bigmap endpoint - micheline/bigmap: refactor to support pairs as key type
- micheline/bigmap: render empty optional values, use inner type in keys when option annotation is missing
NEW FEATURES
- etl:
delegation
operation now stores previous delegate in formerly unusedreceiver
field - etl:
seed_nonce_revelation
operation now stores actual seed publisher in formerly unusedreceiver
field - etl: internal transaction operations keep original sender of an external transaction in formerly unused
manager
field - etl: added new operation types for implicit events
bake
,invoice
,airdrop
,unfreeze
,seed_slash
; op hashes for implicit operations are empty, values forop_n
are negative (-1 for block header, -2 for protocol upgrade events); available on explorer, table and series endpoints - api/block: block operation listing now supports
order
similar to accounts - api/op: explorer operation lists now support table-style filters on type, e.g. to filter for multiple types use
type.in=bake,endorsement
as query argument - api/op: explorer operation lists now support
prim
andunpack
query arguments to simplify working with contract calls - api/op: added new field
entrypoint_id
to operations which contains the sequence number (id) of the called entrypoint; filter by entrypoint on table endpoints is also supported - api/op: added new field
call
to embedded operationparameters
to identify the actual named entrypoint that was called, this is useful if parameters call the default or root entrypoint and specify the real one by branching - api/op:
unpack=1
now recursively unpacks all packed binary data - api/contract: added new field
iface_hash
(first 4 bytes of the SHA256 hash over binary encoded Michelson script parameters) - api/contract: added new field
call_stats
with per-entrypoint call statistics (an array containing running totals) - api/contract: added new fields
op_l
,op_p
andop_i
to reference the position of the contract’s origination operation in a block. - api/contract: contract calls now support
entrypoint
filters using entrypoint name, branch or id - etl/model: added cycle
start_time
andend_time
to baker income (estimated when start or end is in the future) - api/series: new time-series endpoints for
chain
andsupply
tables that will return the first value per collapse interval (ie. first value per hour or day) - flow table: added new fields
op
(hash),op_id
(uint64),op_n
,op_l
,op_p
,op_c
,op_i
(int) which contain metadata about the operation the flow relates to - operation table: added new fields
op_l
,op_p
containing Tezos RPC operation list positions, andis_implicit
for non-operation events as well asentrypoint_id
BREAKING CHANGES
- block: replaced fields
deposits
,fees
,rewards
(plural) which included total sums of all baking and endorsing activity in a block withdeposit
,fee
,reward
(singular form) to only cover baking activity - flow: replaced fields
origin_id
andorigin
withcounterparty_id
andcounterparty
; origin used to contain the source of a flow but was too restrictive since on-way only, now counterparty can hold either party (sender or receiver) who has caused or received a flow, on in-flows (amount_in > 0) the counterparty is the sender, on out-flows (amount_out > 0) counterparty it receiver - flow: JSON bulk array list positions shift because of new fields in the inner array
- operation: changed data for
denunciation
operations, now losses incured by the offender are kept inreward
,fee
, anddeposit
as negative values, reward for the accuser is stored involume
as positive value - operation: JSON bulk array list positions shift because of new fields in the inner array. Changed
op_n
to contain a unique per-block operation counter across all implicit and regular operations. - contract/script: JSON keys for entrypoint arguments now always follow the convention
<order>@<name>
, ie. they include an integer order number as first argument, followed by an optional@
symbol and an optional argument name extracted from type annotations. This way argument order is no longer lost when a name is defined. - bigmap/type: JSON keys for bigmap type arguments now always follow the convention
<order>@<name>@<container-type>
, ie. they include an integer order number as first argument, followed by an optional@
symbol, an optional name extracted from type annotations and in case the type is a container like list, map or set another@
and the container type. This way type argument order is no longer lost when a name is defined.
2020-01-06
- UPGRADES
- supports Carthage protocol PsCARTHAGazKbHtnKfLzQg3kms52kSRpgnDY982a9oYsSXRLQEb
- supports new Carthage reward constants for Emmy+ called
baking_reward_per_endorsement
andendorsement_reward
in the Tezos RPC - updated expected income based on new rewards formula
- NEW EXPLORER FEATURES
/explorer/config/{height}
now returns two additional float arraysblock_rewards_v6
andendorsement_rewards_v6
containing the new Carthage reward constants; the previous fieldsblock_reward
andendorsement_reward
remain unchanged and will contain the first elements from the corresponding v6 arrays- add network health estimation based on recent 128 blocks (priority, endorsements, reorgs)
- FIXES
- block operation list paging with offset/limit now properly counts internal and batch operations
- voting period start and end heights are no longer off by 1
- voting quorum, ema and eligible rolls calculations are corrected
- improved smart contract entrypoint detection so that annotated parent nodes in the parameter primitive tree are no longer shadowing valid entrypoints
- DEPRECATION NOTICES
2019-12-05
- FIXES
- account
is_revealed
is now correctly reset when account balance becomes zero (in this case a Tezos node will remove all account data including a revealed pubkey from storage) - eligible voting rolls are now taken after cycle start block is processed
- counting duplicate proposal votes has been corrected
- annualized supply calculation has been fixed to use 365 instead of 364 days
- fixed vote table
period_start_height
andperiod_end_height
field names - fixed empty fields in some CSV results
- numeric filters on tables now fully support range, in and not-in argument lists
- corrected
income.missed_baking_income
when prio 0 blocks are lost - corrected
supply.circulating
to contain all coins that can move next block (= total - unvested)
- account
- NEW EXPLORER FEATURES
- added config field
deployment
that contains a serial counter of protocol activations on the chain - changed config field
version
to show the protocol implementation version (ie. 4 for Athens, 5 for Babylon, etc) - added block field
successor
- added op fields
branch_id
,branch_height
,branch_depth
,branch
- extended op fields
paramaters
,storage
andbig_map_diff
to include unboxed types and values and made prim tree optional - added new contract endpoints
/explorer/contract/{addr}/calls
to list smart contract calls/explorer/contract/{addr}/manager
current manager account (originator in v005)/explorer/contract/{addr}/script
code, storage & parameter types/explorer/contract/{addr}/storage
current storage state
- added contract field
bigmap_ids
to list ids of bigmaps owned by this contract - added bigmap endpoints
/explorer/bigmap/{id}
bigmap metadata/explorer/bigmap/{id}/type
bigmap type definition/explorer/bigmap/{id}/keys
list bigmap keys/explorer/bigmap/{id}/values
list bigmap key/value pairs/explorer/bigmap/{id}/updates
list bigmap updates/explorer/bigmap/{id}/{key}
single bigmap value/explorer/bigmap/{id}/{key}/updates
list updates for a single bigmap value
- listing account ops supports
order
,block
andsince
query arguments
- added config field
- NEW TABLE FEATURES
- added op table fields
branch_id
,branch_height
,branch_depth
- added bigmap table
/tables/bigmap
to access raw bigmap updates - changed CSV timestamps to RFC3339 (from UNIX milliseconds)
- added op table fields
- DEPRECATION NOTICES
- removed deprecated income table fields
efficiency_percent
,slashed_income
andlost_baking_income
- contract field
ops
and endpoint/explorer/contract/{addr}/op
will be removed (use/explorer/account/{addr}/op
endpoint instead) - contract fields
delegate
,manager
,script
will be removed (new endpoints or related account)
- removed deprecated income table fields
2019-11-01
- DEPRECATION NOTICE: income field
efficiency_percent
will be removed with the next release - replaced income field
efficiency_percent
withperformance_percent
(value range[-Inf,+Inf]
) to avoid confusion with existing benchmarking metrics that define baker efficiency as percentage or rights utilized - added new income field
contribution_percent
to measure a baker’s contribution to consensus in terms of baking/endorsing rights utilized (value range[0,100]
, baking/endorsing misses will lower contribution, steals will increase it) - cycle
n_double_baking
andn_double_endorsement
count events instead of accusation operations now
2019-10-26
- renamed income table field
lost_baking_income
intomissed_baking_income
to align its name withmissed_endorsing_income
- renamed income table field
slashed_income
intototal_lost
because it includes not only income but also deposits that may be slashed - added new income fields
lost_accusation_fees
,lost_accusation_rewards
,lost_accusation_deposits
,lost_revelation_fees
,lost_revelation_rewards
to differentiate losses - added new supply field
burned_seed_miss
to capture supply burned by missed seed nonce revelations
2019-10-24
- add
n_endorsed_slots
to block table, series and explorer endpoint - support bigint in smart contract params, code, bigmaps and storage
2019-10-20
- changed some supply fields from
mined_*
tominted_*
- add new supply field
minted_airdrop
for invoices and protocol upgrade airdrops - support Babylon airdrop of 1 mutez to manager accounts