Tezos API

Current Version

v013-2022-06-15

API Endpoints

Mainnet: https://api.tzstats.com
Mainnet Staging: https://api.staging.tzstats.com
Jakartanet: https://api.jakarta.tzstats.com
Ghostnet: https://api.ghost.tzstats.com

RPC Endpoints

Mainnet: https://rpc.tzstats.com
Mainnet Staging: https://rpc.staging.tzstats.com
Jakartanet: https://rpc.jakarta.tzstats.com
Ghostnet: https://rpc.ghost.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:   v013-2022-06-15

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

# Tezos Block Height
X-Chain-Height: 2467106

# Tezos Protocol (protocol hash)
X-Protocol-Hash: Psithaca2MLRFYargivpo7YvUr7wUDqyxrdhC5CQq78mRvimz6A

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
}

JSON Bulk 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.

JSON Bulk Arrays

Large JSON results such as lists and time-series use a more optimized (less verbose) formatting. Instead of regular JSON objects with named key/value pairs we use bulk arrays, i.e. two levels of nested JSON arrays without keys. An outer array contains result rows or data points. The inner arrays contain lists of columns. To control which columns are returned and their order use the columns query parameter.

Note: 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.

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 and 1536246000000 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, or yesterday 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 or now/d-30d for start of day 30 days ago (expressions support s, 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 Success
400 Bad Request Missing required fields of malformed request data, your fault
404 Not Found No such object
405 Method Not Allowed Unsupported request method
409 Conflict Resource state conflict
429 Too Many Requests Request limit exceeded
500 Internal Server Something went wrong, not your fault
502 Bad Gateway Your request has reached a timeout and was canceled, try to reduce the range of data in your request
504 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} **NEW**           |    | 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 the row_id of the last result as argument to efficiently skips to the next available object
offset + limit is similar, but 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": 7,
  "version": 7,
  "protocol": "PsDELPH1Kxsxt8f9eWbxQeRxkjfbxoqM52jvs5Y5fBxWWh4ifpo",
  "start_height": 1212417,
  "end_height": -1,
  "no_reward_cycles": 0,
  "security_deposit_ramp_up_cycles": 0,
  "decimals": 6,
  "units": 1000000,
  "block_reward": 40,
  "block_security_deposit": 512,
  "blocks_per_commitment": 32,
  "blocks_per_cycle": 4096,
  "blocks_per_roll_snapshot": 256,
  "blocks_per_voting_period": 32768,
  "cost_per_byte": 250,
  "endorsement_reward": 1.25,
  "endorsement_security_deposit": 64,
  "endorsers_per_block": 32,
  "hard_gas_limit_per_block": 10400000,
  "hard_gas_limit_per_operation": 1040000,
  "hard_storage_limit_per_operation": 60000,
  "max_operation_data_length": 16384,
  "max_proposals_per_delegate": 20,
  "max_revelations_per_block": 0,
  "michelson_maximum_type_size": 1000,
  "nonce_length": 32,
  "origination_burn": 0,
  "origination_size": 257,
  "preserved_cycles": 5,
  "proof_of_work_nonce_size": 8,
  "proof_of_work_threshold": 70368744177663,
  "seed_nonce_revelation_tip": 0.125,
  "time_between_blocks": [
    60,
    40
  ],
  "tokens_per_roll": 8000,
  "test_chain_duration": 1966080,
  "min_proposal_quorum": 500,
  "quorum_min": 2000,
  "quorum_max": 7000,
  "block_rewards_v6": [
    1.25,
    0.1875
  ],
  "endorsement_rewards_v6": [
    1.25,
    0.833333
  ],
  "max_anon_ops_per_block": 132,
  "num_voting_periods": 4
}

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`, `Zeronet`, `Babylonnet`, `Labnet`, `Sandbox`).
`chain_id` hash	Chain hash.
`version` int64	Protocol version number.
`deployment` int64	Number of deployed protocols on this network.
`protocol` hash	Protocol hash.
`start_height` int64	Activation height of the protocol.
`end_height` int64	Deactivation height of the protocol (0 if undefined).
`no_reward_cycles` int64	Number of initial cycles that pay no block rewards.
`security_deposit_ramp_up_cycles` int64	Number of initial cycles before full deposits are required.
`decimals` int64	Decimal points of one coin unit.
`units` int64	Number of atomic units in one coin (i.e. mutez).
`block_reward` money	Block baking reward in tez.
`block_security_deposit` money	Baker security deposit in tez.
`blocks_per_commitment` int64	Number of blocks between seed nonce commitments.
`blocks_per_cycle` int64	Number of blocks per consensus cycle.
`blocks_per_roll_snapshot` int64	Number of blocks between roll snapshots.
`blocks_per_voting_period` int64	Number of blocks per voting period.
`cost_per_byte` int64	Gas costs per data byte.
`endorsement_reward` money	Block endorsing reward per slot in tez.
`endorsement_security_deposit` money	Endorser security deposit per slot in tez.
`endorsers_per_block` int64	Max number of endorsing slots.
`hard_gas_limit_per_block` int64	Max gas limit per block.
`hard_gas_limit_per_operation` int64	Max gas limit per single operation.
`hard_storage_limit_per_operation` int64	Max gas limit for storage spent be an operation.
`max_operation_data_length` int64	Max data bytes per operation.
`max_proposals_per_delegate` int64	Max proposals per single delegate and proposals operation.
`max_revelations_per_block` int64	Maximum number of seed nonce revelation operations per block.
`michelson_maximum_type_size` int64	Maximum type size Michelson type definition.
`nonce_length` int64	Nonce length
`origination_burn` money	Amount of Tezos burned per origination.
`origination_size` int64	Origination storage requirement in bytes.
`preserved_cycles` int64	Number of cycles for freezing security deposits and rewards.
`proof_of_work_nonce_size` int64	Nonce size for P2P messages.
`proof_of_work_threshold` int64	Threshold for message nonce complexity.
`seed_nonce_revelation_tip` money	Rewards for publishing a seed nonce.
`time_between_blocks` array[int64]	Target time between blocks in seconds.
`tokens_per_roll` int64	Amount of Tezos per roll.
`test_chain_duration` int64	Test chain lifetime in seconds.
`min_proposal_quorum` int64	(Babylon, v005) Minimum quorum to accept proposals in centile (i.e. 5% = 500).
`quorum_min` int64	(Babylon, v005) Minimum threshold for voting period quorum in centile.
`quorum_max` int64	(Babylon, v005) Maximum threshold for voting period quorum in centile.
`block_reward_v6` [2]money	(Carthage, v006) Block reward per included endorsement for prio 0 blocks [0] or >prio 0 blocks [1].
`endorsement_reward_v6` [2]money	(Carthage, v006) Reward per endorsement for a prio 0 block [0] or >prio 0 block [1].
`max_anon_ops_per_block` int64	(Delphi, v007) Max number of anonymous ops like seed nonces.
`num_voting_periods`int64	(Edo, v008) Number of voting epochs, Edo introduced a 5th adoption period.
`liquidity_baking_escape_ema_threshold` int64	(Granada, v010) Threshold to disable liquidity baking.
`liquidity_baking_subsidy` int64	(Granada, v010) Subsidy amount.
`liquidity_baking_sunset_level` int64	(Granada, v010) Block at which liquidity baking stops.
`minimal_block_delay` int	(Granada, v010) Actual expected time between blocks, `time_between_blocks` stays unchanged.

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.

{
    "bakers": 402,
    "block_hash": "BMegjt86PJ3g45QAV2sYf7KxsESxbpHNewFxDqVuYbgjbkTNDEX",
    "chain_id": "NetXdQprcVkpaWU",
    "cleared_accounts_30d": 10485,
    "cycle": 495,
    "delegators": 176269,
    "dust_accounts": 600308,
    "dust_delegators": 13465,
    "funded_accounts": 2102354,
    "funded_accounts_30d": 38503,
    "genesis_time": "2018-06-30T16:07:32Z",
    "health": 96,
    "height": 2467118,
    "inflation_1y": 40349272.98719,
    "inflation_rate_1y": 4.584620098665697,
    "name": "Tezos",
    "network": "Mainnet",
    "new_accounts_30d": 34091,
    "protocol": "Psithaca2MLRFYargivpo7YvUr7wUDqyxrdhC5CQq78mRvimz6A",
    "status": {
        "blocks": 2467119,
        "finalized": 2467118,
        "indexed": 2467118,
        "mode": "sync",
        "progress": 1,
        "status": "synced"
    },
    "supply": {
        "activated": 742754433.250126,
        "active_delegated": 551439874.299836,
        "active_stake": 689457213.466999,
        "active_staking": 690610690.868684,
        "burned": 1292818.931016,
        "burned_absence": 36011.947884,
        "burned_allocation": 261443.787,
        "burned_double_baking": 228687.464089,
        "burned_double_endorse": 31838.219485,
        "burned_explicit": 199099.722815,
        "burned_origination": 12855.97525,
        "burned_rollup": 0,
        "burned_seed_miss": 103780.550674,
        "burned_storage": 618199.9695,
        "circulating": 898885795.278996,
        "cycle": 495,
        "delegated": 555914321.500882,
        "frozen": 70572916.889058,
        "frozen_bonds": 0,
        "frozen_deposits": 70552151.597504,
        "frozen_fees": 0,
        "frozen_rewards": 20765.291554,
        "height": 2467118,
        "inactive_delegated": 4474447.201046,
        "inactive_staking": 6161722.976939,
        "liquid": 828312878.389938,
        "minted": 157424180.959886,
        "minted_airdrop": 600.007321,
        "minted_baking": 58496839.131322,
        "minted_endorsing": 96629433.594935,
        "minted_seeding": 7861.625,
        "minted_subsidy": 2194677.5,
        "row_id": 2467118,
        "shielded": 5.312,
        "staking": 696772413.845623,
        "time": "2022-06-20T13:01:14Z",
        "total": 920449960.04157,
        "unclaimed": 21564164.762574
    },
    "symbol": "XTZ",
    "timestamp": "2022-06-20T13:01:14Z",
    "total_accounts": 2324044,
    "total_contracts": 87853,
    "total_ops": 233296521,
    "total_rollups": 0
}

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`, Jakartanet`,` 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.
`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.
`dust_accounts` int64	Number of funded accounts with balance < 0.01tez.
`total_ops` int64	Total number of on-chain operations.
`delegators` int64	Current number of delegators.
`dust_delegators` int64	Current number of delegators with balance <0.01 tez.
`bakers` int64	Current number of active bakers.
`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,
  "spendable_balance": 11375.324796,
  "is_funded": true,
  "is_activated": false,
  "is_delegated": false,
  "is_revealed": true,
  "is_baker": false,
  "is_contract": false,
  "n_ops": 87719,
  "n_ops_failed": 14,
  "n_tx": 87718,
  "n_delegation": 0,
  "n_origination": 0,
  "n_constants": 0,
  "token_gen_min": 0,
  "token_gen_max": 182059,
  "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.
`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_ops` int64	Lifetime total number of operations sent and received.
`n_ops_failed` int64	Lifetime total number of operations sent that failed.
`n_tx` int64	Lifetime total number of transactions sent and received.
`n_delegation` int64	Lifetime total number of delegations sent.
`n_origination` int64	Lifetime total number of originations sent.
`n_constant` int64	Lifetime total number of global constants created.
`token_gen_min` int64	Minimum generation number of all tokens owned.
`token_gen_max` int64	Maximum generation number of all tokens owned.
`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.GetAccount(
  context.Background(),
  tezos.MustParseAddress("tz3RDC3Jdn4j15J7bBHZd29EUee9gVB1CxD9"),
  tzstats.NewAccountParams().WithMeta(),
)

Example response for accounts.

{
    "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`	Baker address
`baker_since_time`	Most recent registration timestamp
`grace_period`	Grace period cycle at which the baker gets deactivated when inactive.
`baker_version`	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`	Current stake counting towards baking rights, may be lower than staking balance when deposits limit is active.
`total_balance`	Total own balance, locked and spendable.
`spendable_balance`	Spendable balance
`frozen_balance`	Sum of frozen balances (deposit, reward, fee)
`delegated_balance`	Sum of all incoming delegations.
`staking_balance`	Own plus delegated balance.
`staking_capacity`	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`	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`	A baker’s staking share in percent as fraction of all the network wide staking.
`active_delegations`	Number of funded delegators.
`is_full`	Flag indcating the baker’s capacity is reached.
`is_active`	Flag indicating the baker is actively participating in consensus and earning rewards.

Baker event fields

Field	Description
`last_bake_height`	latest baked block height
`last_bake_block`	latest baked block hash
`last_bake_time`	latest baked block timestamp
`last_endorse_height`	latest endorsed block height
`last_endorse_block`	latest endorsed block hash
`last_endorse_time`	latest endorsed block timestamp
`next_bake_height`	next round 0 baking opportunity as block height
`next_bake_time`	next round 0 baking opportunity as estimated timestamp
`next_endorse_height`	next endorsing opportunity as block height
`next_endorse_time`	next endorsing opportunity as estimated timestamp

Baker statistics fields

Field	Description
`total_rewards_earned`	Sum of lifetime rewards earned
`total_fees_earned`	Sum of lifetime fees earned
`total_lost`	Sum of lifetime coins lost in punishments
`blocks_baked`	Sum of lifetime blocks baked
`blocks_proposed`	Sum of lifetime blocks proposed (in Ithaca+ baker and proposer may differ)
`blocks_not_baked`	Number of blocks not baked although rights existed (previously called `lost`).
`blocks_endorsed`	Number of blocks endorsed.
`blocks_not_endorsed`	Number of blocks not endorsed although rights existed (previously called `missed`).
`slots_endorsed`	Sum of lifetime slots endorsed
`avg_luck_64`	Average 64-cycle luck, consensus rights received below/above fair share relative to staking balance.
`avg_performance_64`	Average 64-cycle performance, realized rewards + fee income relative to expected max possible income based on rights allocated.
`avg_contribution_64`	Average 64-cycle contribution, i.e. number of consensus rights sucessfully used (participation in consensus).
`n_baker_ops`	Number of baker operations sent.
`n_proposals`	Voting proposals sent.
`n_ballots`	Voting ballots sent.
`n_endorsements`	Endorsements sent.
`n_preendorsements`	Preendorsements sent (Ithaca+).
`n_nonce_revelations`	Seed nonces sent.
`n_double_bakings`	Double baking punishments received.
`n_double_endorsements`	Double (pre)endorsing punishments received.
`n_accusations`	Number of 2bake/2endorse ops sent as accusor.
`n_set_limits`	Number of deposit limit ops sent.

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.
`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.
`is_internal` bool	Flag indicating if this operation was sent be a smart contract.
`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_rollup` bool	Flag indicating this is a rollup related operation.
`data` polymorph	Extra type-dependent operation data. See below.
`parameters` object	Call parameters as embedded JSON object, contract and rollup only.
`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.
`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`.
`errors` array	Native Tezos RPC errors.
`source` hash	In internal operations, source is the original signer of the outer transaction.
`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.
`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.
`creator` hash	Contains contract creator on `origination`. For `nonce_revelation` the actual seed publisher is referenced.
`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.
`metadata` object	Use `meta=1` to embed optional account metadata for sender, receiver, delegate, creator. May be empty if no account has metadata defined.
`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).
`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.

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 event
unfreeze event
seed_slash event
airdrop event
invoice event
migration event
subsidy event
deposit event Ithaca+
reward event Ithaca+
bonus event Ithaca+
rollup_origination Jakarta+
rollup_transaction Jakarta+

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

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 and cursor / 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 and cursor / 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 and cursor / 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": "BLhRjTFhk37a8vgE2M5DU2cCbtV3qJHaBBPvTboHfyLYV74hM99",
  "predecessor": "BKjZfegUTsCD3eURHPur6L6zRmS6c6D9cdwLKoFDU9DcmJmWnaY",
  "successor": "BMKvd7HhwnhCTSWGG2YkDrsWSugcZefo1V5i9gZ2Khz87S3e98k",
  "baker": "tz1bTpviNnyx2PXsNmGpCQTMQsGoYordkUoA",
  "proposer": "tz1bTpviNnyx2PXsNmGpCQTMQsGoYordkUoA",
  "height": 1342853,
  "cycle": 327,
  "is_cycle_snapshot": false,
  "time": "2021-02-13T10:16:55Z",
  "solvetime": 60,
  "version": 7,
  "round": 0,
  "nonce": "6102c808a62a0100",
  "voting_period_kind": "promotion",
  "n_endorsed_slots": 31,
  "n_ops_applied": 28,
  "n_ops_failed": 0,
  "n_events": 1,
  "n_contract_calls": 1,
  "n_rollup_calls": 0,
  "volume": 98233.072783,
  "fee": 0.019784,
  "reward": 38.75,
  "deposit": 512,
  "activated_supply": 0,
  "minted_supply": 77.5,
  "burned_supply": 0.19275,
  "n_accounts": 32,
  "n_new_accounts": 1,
  "n_new_contracts": 0,
  "n_cleared_accounts": 0,
  "n_funded_accounts": 3,
  "gas_limit": 113904,
  "gas_used": 15466,
  "storage_paid": 0,
  "pct_account_reuse": 96.875,
  "lb_esc_vote": false,
  "lb_esc_ema": 0,
  "protocol": "PsDELPH1Kxsxt8f9eWbxQeRxkjfbxoqM52jvs5Y5fBxWWh4ifpo",
  "metadata": {
    "tz1KfEsrtDaA1sX7vdM4qmEPWuSytuqCDp5j": {
      "alias": {
        "name": "XTZ Master",
        "kind": "validator",
        "logo": "tz1KfEsrtDaA1sX7vdM4qmEPWuSytuqCDp5j.png"
      },
      "baker": {
        "status": "public",
        "fee": 0.08,
        "payout_delay": true
      },
      "location": {
        "country": "AU"
      },
      "social": {
        "twitter": "Xtzmastercom"
      }
    },
    // ...
  },
  "rights": [
    {
      "type": "baking",
      "round": 0,
      "address": "tz1bTpviNnyx2PXsNmGpCQTMQsGoYordkUoA",
      "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.
`baker` hash	Baker address.
`proposer` hash	Payload proposer address, from Ithaca+ this may differ from baker.
`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_contract_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 and cursor / offset for paging
order with asc or descfor 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": 818425,
  "address": "KT1Puc9St8wdNoGtLiD2WXaHbWU7styaxYhD",
  "creator": "tz1P7A3YFgeSsGgopKN9vUU86W3psgTMdtcJ",
  "baker": "tz1WCd2jm4uSt4vntk4vSuUWoZQGhLcDuR9q",
  "storage_size": 89,
  "storage_paid": 35957,
  "first_seen": 1149672,
  "last_seen": 1855764,
  "first_seen_time": "2020-09-29T16:18:45Z",
  "last_seen_time": "2021-11-11T22:15:18Z",
  "n_calls_success": 14719,
  "n_calls_failed": 208,
  "bigmaps": {
    "accounts":124
  },
  "iface_hash": "cf9361e19e152667",
  "code_hash": "666dcc0163791250",
  "storage_hash": "e14ab82acf5a4115",
  "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": ["DEXTER"]
}

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.
`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_success` int64	Lifetime total number of successful calls received.
`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 **NEW** | 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) to time.lte=2019-08-31 (inclusive) and returns columns time and height. The same effect can be achieved with the range operator time.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_ops
    0,                  // n_ops_failed
    38,                 // n_tx
    1,                  // n_delegation
    0,                  // n_origination
    0,                  // n_constant
    2,                  // token_gen_min
    4875,               // token_gen_max
    "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_ops` int64	Lifetime total number of operations sent and received.
`n_ops_failed` int64	Lifetime total number of operations sent that failed.
`n_tx` int64	Lifetime total number of transactions sent and received.
`n_delegation` int64	Lifetime total number of delegations sent.
`n_origination` int64	Lifetime total number of originations sent.
`n_constnat` int64	Lifetime total number of global constants created.
`token_gen_min` int64	Minimum generation number of all tokens owned.
`token_gen_max` int64	Maximum generation number of all tokens owned.
`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
    1,  // valid_until
    "tz3RDC3Jdn4j15J7bBHZd29EUee9gVB1CxD9", // address
    0,  // valid_from_time
    1530380397000, // valid_until_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.
`valid_until` int64	Block height where the balance changed again.
`address` hash	Account address
`valid_from_time` datetime	Block time where the balance updated to the current value.
`valid_until_time` datetime	Block time where the balance changed again.

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.

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`.
`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
  ]
]

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`.
`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.
`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.

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 **NEW**           | 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
    17867256.383035008, // days_destroyed
  ]
]

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.
`days_destroyed` float	Token days destroyed.

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
    17867317.80054702   // days_destroyed
    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.
`days_destroyed` float	Total token days destroyed by all operation.
`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_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
    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/op?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)
`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, // liqid
    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.

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
baker model
- new active_stake
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
block model
- new counter n_rollup_calls
chain model
- new total_ops_failed, total_rollup_calls and total_rollups
contract model
- new storage_burn counter
flow model
- new balance category bond
- new operations types rollup_origination, rollup_transaction, rollup_reward, rollup_penalty
income model
- add lost_accusation_fees, lost_accusation_rewards, lost_accusation_deposits, lost_seed_fees, lost_seed_rewards,
- renamed total_bonds to total_deposits to avoid name conflict with rollup bonds
- contribution_percent and avg_contribution_64 are now counted up until position in cycle, formerly this was end of cycle which skewed numbers for the current cycle
op model
- new types rollup_origination and rollup_transaction
- rollup op arguments are packed into parameters
- new parameter fields l2_address, method and arguments
- different rollup op types are represented as method names
- new is_rollup flag
snapshot model
- new active_stake
supply model
- new active_stake, frozen_bonds and burned_rollup (for penalties)
tip model
- removed rolls and roll_owners
- added total_contracts and total_rollups
vote model
- new eligible_stake, quorum_stake, turnout_stake, yay_stake, nay_stake, pass_stake

2022-04-18

baker model
- added blocks_not_baked, blocks_endorsed and blocks_not_endorsed counters
- fixed output for deposits_limit
- added is_funded state to delegator data
- added income fields to snapshot data
income model
- added n_blocks_not_baked, n_blocks_endorsed and n_blocks_not_endorsed counters
- fixed expected_income and active_stake numbers for the first 6 Ithaca cycles
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 to merge (used for nesting internal and batch operations)
- renamed all occurences of delegateto baker
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 as n_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 to round
  - storage_size to storage_paid
  - n_ops to n_ops_applied
  - n_ops_implicit to n_events
operation model
- renamed implicit operations to events
- new global stable/unique id instead of row_id
- unique op_n event counter inside each block (before, batch and internal operations shared the same op_n)
- switched sender and creator 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)
- 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 and offender instead of sender and receiver
- internal ops now use source instead of creator 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), use order=asc for previous behaviour)
- renamed fields
  - is_implicit to is_event
  - block_hash to block
  - delegate_id and delegate to baker_id and baker
- renamed operation types
  - seed_nonce_revelation to nonce_revelation
  - double_baking_evidence to double_baking
  - double_endorsement_evidence to double_endorsement
- added new operation and event types for Tenderbake
  - preendorsement for preendorsements (only visible when block round > 0)
  - double_preendorsement for double signatures on preendorsements
  - deposits_limit for explicit baker deposit limit ops
  - deposit for explicit deposit freeze and unfreeze events
  - reward for endorsement reward payments
  - bonus for baker bonus payments (i.e. including more than threshold endorsements)
  - subsidy for minting liquidity baking subsidy (was type transaction before)
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 and token_gen_min
- added new types bonus, deposit and deposits_limit for Ithaca
chain model
- dropped field total_paid_bytes (duplicate of total_storage_bytes)
- added fields total_set_limits and total_preendorsements
- renamed fields *_delegates to *_bakers
- renamed total_double_baking_evidences to total_double_bakings
- renamed total_double_endorsement_evidences to total_double_endorsements
- renamed total_seed_nonce_revelations to total_nonce_revelations
cycle model
- renamed missed_priorities into missed_rounds
- renamed priority_min|max|mean into round_min|max|mean
- dropped n_orphans
tip
- moved deployments from to separate endpoint /explorer/protocols
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 with accusation_income
- replaced fields lost_accusation_fees, lost_accusation_rewards, lost_accusation_deposits with accusation_loss
- replaced lost_revelation_fees, lost_revelation_rewards with seed_loss
- removed fields n_blocks_lost, n_blocks_stolen, n_slots_missed, expected_bonds, missed_endorsing_income without replacement
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
bigmap model
- renamed key_hash to hash in bigmap keys and bigmap update table

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
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 and dust_delegators for accounts with balance <1tez
API: supply table and series
- renamed burned_implicit to burned_allocation
- new burned_storage (storage fees) and burned_explicit (sent to burn address)

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 and time 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 to branch_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 tables bigmaps (allocs), bigmap_updates (updates only, not indexed) and bigmap_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 and is_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) with slot_mask (hex string) on explorer and table endpoints, it remains a bitset (32 or 256 bits)
API: replaced block field rights.slot to rights.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 and lb_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
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 and circulating, added liquid (= 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) with bigmaps 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 informative rights list (use new query arg rights=1)
api/account: renamed /explorer/account/{hash}/managed to /explorer/account/{hash}/contracts
api/account: removed deprecated fields is_delegatable, is_spendable and is_vesting
api/account: renamed field manager to creator
api/op: renamed field manager to creator
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 arg meta=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 and features 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 and is_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 embedded ops array will be removed in the next API release
api/block: listing operations with /explorer/block/{hash}/ops and the embedded ops 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} to working_{bakers|endorsers}, also note the change in meaning of active_bakers as described below
api/account: renamed explorer and table field flow_rank to volume_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 embedded ballots 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 have volume field set to the initial delegated balance
api/operation: new fields is_batch and batch_volume on first operation in an explorer batch list
api/operation: added new implicit activation and delegation operations from genesis bootstrap
api/operation: bake and unfreeze implicit operations now contain the baker as sender and receiver to allow listing bake/endorse/unfreeze ops with a single operation table call
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 and delegate_until_time
api/cycle: new explorer fields snapshot_time, active_bakers and active_delegators for a total number of all registered bakers and funded delegators at cycle snapshot
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 for ballot
api/rights: new table filter modes ne, in, nin for type
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 unused receiver field
etl: seed_nonce_revelation operation now stores actual seed publisher in formerly unused receiver 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 for op_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 and unpack 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 operation parameters 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 and op_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 and end_time to baker income (estimated when start or end is in the future)
api/series: new time-series endpoints for chain and supply 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, and is_implicit for non-operation events as well as entrypoint_id

BREAKING CHANGES

block: replaced fields deposits, fees, rewards (plural) which included total sums of all baking and endorsing activity in a block with deposit, fee, reward (singular form) to only cover baking activity
flow: replaced fields origin_id and origin with counterparty_id and counterparty; 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 in reward, fee, and deposit as negative values, reward for the accuser is stored in volume 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 and endorsement_reward in the Tezos RPC
- updated expected income based on new rewards formula
NEW EXPLORER FEATURES
- /explorer/config/{height} now returns two additional float arrays block_rewards_v6 and endorsement_rewards_v6 containing the new Carthage reward constants; the previous fields block_reward and endorsement_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
- removed deprecated contract field ops and endpoint /explorer/contract/{addr}/op (use /explorer/account/{addr}/op endpoint instead)
- removed deprecated contract fields delegate, manager, script (use new endpoints or related account endpoints instead)

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 and period_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)
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 and big_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 and since query arguments
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)
DEPRECATION NOTICES
- removed deprecated income table fields efficiency_percent, slashed_income and lost_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)

2019-11-01

DEPRECATION NOTICE: income field efficiency_percent will be removed with the next release
replaced income field efficiency_percent with performance_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 and n_double_endorsement count events instead of accusation operations now

2019-10-26

renamed income table field lost_baking_income into missed_baking_income to align its name with missed_endorsing_income
renamed income table field slashed_income into total_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_* to minted_*
add new supply field minted_airdrop for invoices and protocol upgrade airdrops
support Babylon airdrop of 1 mutez to manager accounts