NAV
Shell

Introduction

API Endpoints

Mainnet: https://api.tzstats.com
Zeronet: https://api.zeronet.tzstats.com
Babylonnet: https://api.babylonnet.tzstats.com

TzStats provides a powerful API to access fully indexed raw data and statistics collected from the Tezos blockchain. You may use this API free of charge and without limits for non-commercial projects. To inquire about commerial use send an email to info@tzstats.com.

This API reference provides information on all public API endpoints and the different schemes of calling them. Access to the API does not require authentication and we do not enforce daily rate limits right now, but we monitor usage and may apply limits later to guarantee fair usage for everybody.

The API supports three different endpoint flavors to access the same underlying data in different ways:

Calling the API

TzStats Data API is read-only, i.e. the only supported HTTP methods are GET and HEAD. Query parameters must be properly URL encoded and appended as query arguments.

Table and time-series endpoints stream data, 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.

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, v1.2 and v1.1 with Perfect Forward Secrecy based on Eliptic Curves and Diffie Helman key exchange. Insecure HTTP requests to port 80 are automatically redirected to HTTPS on port 443.

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 info@tzstats.com 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.

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

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 datapoints. The inner arrays contain lists of requested columns in requested order when using the columns query parameter or a fixed pre-defined order.

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 of 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 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:

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.

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 Endpoints

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:

Some endpoints support a simple pagination scheme to walk lists of result (i.e. for related operations or accounts). To paginate append limit and offset, both are positive integers. Limit defaults to 20 and is capped to a maximum value of 100. Results are always sorted by row_id of the underlying table. If you require a different sort order, you have to do this client-side.

List of supported endpoints

Endpoint Is Paged Filter Comment
GET /explorer/status indexer status
GET /explorer/config/{head,height} blockchain config at head or height
GET /explorer/tip blockchain tip info
GET /explorer/block/{head,hash,height} block info
GET /explorer/block/{head,hash,height}/op x type list block operations
GET /explorer/op/{hash} operation info
GET /explorer/account/{hash} account info
GET /explorer/account/{hash}/managed x list of contracts managed by this account
GET /explorer/account/{hash}/op x type account info with embedded list of related operations
GET /explorer/account/{hash}/ballots x list proposals and ballots
GET /explorer/contract/{hash} smart contract metadata
GET /explorer/contract/{hash}/calls x type list contract calls
GET /explorer/contract/{hash}/manager contract manager (pre-babylon) or originator
GET /explorer/contract/{hash}/script smart contract code, storage and parameter spec
GET /explorer/contract/{hash}/storage smart contract storage
GET /explorer/bigmap/{id} bigmap metadata
GET /explorer/bigmap/{id}/type bigmap type specification
GET /explorer/bigmap/{id}/keys x list of bigmap keys
GET /explorer/bigmap/{id}/values x list of bigmap key/value pairs
GET /explorer/bigmap/{id}/updates x list of bigmap updates
GET /explorer/bigmap/{id}/{key} single bigmap value
GET /explorer/bigmap/{id}/{key}/updates x list of bigmap updates related to a key
GET /explorer/cycle/{head,num} active cycle or cycle N info
GET /explorer/election/{head,num,height} election info (num ::= [1,1024]
GET /markets list of known exchanges and markets
GET /markets/tickers list of 24h market tickers
GET /markets/{exchange} exchange status
GET /markets/{exchange}/{market} market status
GET /markets/{exchange}/{market}/ticker single market ticker

Accounts

Example request.

curl "https://api.tzstats.com/explorer/account/tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m"

Example response.

{
  "address": "tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m",
  "address_type": "secp256k1",
  "delegate": "tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m",
  "manager": "",
  "pubkey": "sppk7bn9MKAWDUFwqowcxA1zJgp12yn2kEnMQJP3WmqSZ4W8WQhLqJN",
  "first_in": 360996,
  "first_out": 360997,
  "last_in": 627433,
  "last_out": 627433,
  "first_seen": 360996,
  "last_seen": 627433,
  "delegated_since": 0,
  "delegate_since": 361000,
  "first_in_time": "2019-03-20T23:10:52Z",
  "first_out_time": "2019-03-20T23:11:52Z",
  "last_in_time": "2019-09-28T14:43:06Z",
  "last_out_time": "2019-09-28T14:43:06Z",
  "first_seen_time": "2019-03-20T23:10:52Z",
  "last_seen_time": "2019-09-28T14:43:06Z",
  "delegated_since_time": "0001-01-01T00:00:00Z",
  "delegate_since_time": "2019-03-20T23:14:52Z",
  "total_received": 4129917.992,
  "total_sent": 1241985.094354,
  "total_burned": 0,
  "total_fees_paid": 0.041097,
  "total_rewards_earned": 463712.421526,
  "total_fees_earned": 51.817584,
  "total_lost": 0,
  "frozen_deposits": 2777472,
  "frozen_rewards": 86384.999996,
  "frozen_fees": 10.252118,
  "unclaimed_balance": 0,
  "spendable_balance": 487829.843545,
  "total_balance": 3265312.095663,
  "delegated_balance": 28092992.436557,
  "total_delegations": 13,
  "active_delegations": 8,
  "is_funded": true,
  "is_activated": false,
  "is_vesting": false,
  "is_spendable": true,
  "is_delegatable": false,
  "is_delegated": false,
  "is_revealed": true,
  "is_delegate": true,
  "is_active_delegate": true,
  "is_contract": false,
  "blocks_baked": 5867,
  "blocks_missed": 40,
  "blocks_stolen": 127,
  "blocks_endorsed": 97968,
  "slots_endorsed": 185547,
  "slots_missed": 332,
  "n_ops": 98177,
  "n_ops_failed": 0,
  "n_tx": 38,
  "n_delegation": 1,
  "n_origination": 0,
  "n_proposal": 1,
  "n_ballot": 1,
  "token_gen_min": 2,
  "token_gen_max": 4875,
  "grace_period": 159,
  "staking_balance": 31358304.53222,
  "rolls": 3919,
  "rich_rank": 25,
  "traffic_rank": 0,
  "flow_rank": 0,
  "last_bake_height": 627422,
  "last_bake_block": "BLeU7pnXhFRKsjvc3XYQ2gByCqwAALpKc7vZSoTeVNeUgHWDZ3V",
  "last_bake_time": "2019-09-28T14:32:01Z",
  "last_endorse_height": 627433,
  "last_endorse_block": "BLapVsFS7DB9H76njHSoFyGTTSfMn7ZJvUzB1KekUvtUk8KeXMy",
  "last_endorse_time": "2019-09-28T14:43:06Z",
  "next_bake_height": 627464,
  "next_bake_priority": 0,
  "next_bake_time": "2019-09-28T15:14:06Z",
  "next_endorse_height": 627434,
  "next_endorse_time": "2019-09-28T14:44:06Z"
}

Provides information about the most recent state of implicit and smart contract accounts.

HTTP Request

GET https://api.tzstats.com/explorer/account/{hash}

HTTP Response

Field Description
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).
delegate hash Current delegate (may be self when registered as delegate).
manager hash Contract manager account.
pubkey hash Revealed public key.
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.
delegate_since int64 Block height of registration as delegate.
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.
delegated_since_time datetime Block time of most recent delegation.
delegate_since_time datetime Block time of registration as delegate.
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 tz.
total_fees_paid money Lifetime fees paid in tz.
total_rewards_earned money Lifetime rewards earned in tz.
total_fees_earned money Lifetime fees earned in tz.
total_lost money Lifetime total tokens lost in tz.
frozen_deposits money Currently frozen deposits
frozen_rewards money Currently frozen rewards.
frozen_fees money Currently frozen fees.
unclaimed_balance money Currently unclaimed balance (for vesting contracts and commitments).
spendable_balance money Currently spendable balance.
total_balance money Currently spendable and frozen balances (except frozen rewards).
delegated_balance money (delegate only) Current incoming delegations.
staking_balance money (delegate only) Current delegated and own total balance.
total_delegations int64 (delegate only) Lifetime count of delegations.
active_delegations int64 (delegate only) Currently active and non-zero delegations.
is_funded bool Flag indicating the account is funded.
is_activated bool Flag indicating the account was activated from a commitment.
is_vesting bool Flag indicating the account is a vesting contract.
is_spendable bool Flag indicating the account balance is spendable.
is_delegatable bool Flag indicating the account is delegatable.
is_delegated bool Flag indicating the account is currently delegated.
is_revealed bool Flag indicating the account has a revealed public key .
is_delegate bool Flag indicating the account is a registered delegate.
is_active_delegate bool Flag indicating the account is a registered and active delegate.
is_contract bool Flag indicating the account is a smart contract.
blocks_baked int64 Lifetime total blocks baked.
blocks_missed int64 Lifetime total block baking missed.
blocks_stolen int64 Lifetime total block baked at priority > 0.
blocks_endorsed int64 Lifetime total blocks endorsed.
slots_endorsed int64 Lifetime total endorsemnt slots endorsed.
slots_missed int64 Lifetime total endorsemnt slots missed.
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_proposal int64 Lifetime total number of proposals (operations) sent.
n_ballot int64 Lifetime total number of ballots sent.
token_gen_min int64 Minimum generation number of all tokens owned.
token_gen_max int64 Maximum generation number of all tokens owned.
grace_period int64 (delegate only) Current grace period before deactivation.
rolls int64 (delegate only) Currently owned rolls.
rich_rank int64 Global rank on rich list by total balance.
traffic_rank int64 Global rank on 24h most active accounts by transactions sent/received.
flow_rank int64 Global rank on 24h most active accounts by volume sent/received.
last_bake_height int64 Height of most recent block baked.
last_bake_block hash Hash of most recent block baked.
last_bake_time datetime Timestamp of most recent block baked.
last_endorse_height int64 Height of most recent block endorsed.
last_endorse_block hash Hash of most recent block endorsed.
last_endorse_time datetime Timestamp of most recent block endorsed.
next_bake_height int64 Height of next block baking right.
next_bake_priority int64 Priority of next baking right (fixed at zero currently).
next_bake_time datetime Approximate time of next block baking right.
next_endorse_height int64 Height of next block endorsing right.
next_endorse_time datetime Approximate time of next block endorsing right.

Bigmaps

Bigmaps are key-value stores where smart contracts can store large amounts of data. Values in bigmaps are accessed by unique keys. The TzStats bigmap index supports different key encodings: a key_hash (script expression hash), the binary representation of a key and the natural typed version of a key. For convenience, all three variants are present in responses.

In Tezos a bigmap is defined by a key_type and a value_type. While the key type must be a simple comparable type (int, string, bytes, address, etc), the value can have a complex type structure. API results always contain an unboxed version of the value type by default. Unboxing uses the types and annotations defined in value_type to decompose a complex value into a nested JSON object. Use the optional request parameter prim=1 to include the native Michelson value representation (a tree of primitives).

Bigmap ownership is 1:N, ie. smart contracts can own multiple bigmaps, but each bigmap has only one owner.

Bigmap Metadata

Example request.

curl "https://api.tzstats.com/explorer/bigmap/1"

Example response.

{
  "address": "KT1WRUe3csC1jiThN9KUtaji2bd412upfn1E",
  "bigmap_id": 1,
  "key_encoding": "int",
  "key_type": "nat",
  "n_updates": 545,
  "n_keys": 544,
  "alloc_height": 41835,
  "alloc_time": "2018-07-31T09:13:57Z",
  "height": 42398,
  "time": "2018-07-31T19:06:57Z"
}

Returns metadata about a bigmap.

HTTP Request

GET https://api.tzstats.com/explorer/bigmap/{id}

HTTP Response

Field Description
address hash Contract that owns the bigmap.
bigmap_id int64 Unique on-chain id of this bigmap.
key_encoding enum Encoding used for keys (e.g. string, bytes, int).
key_type enum Michelson type for keys (any comparable Michelson type).
n_updates int64 Total update count.
n_keys int64 Current number of keys in bigmap.
alloc_height int64 Height when the bigmap was allocated.
alloc_time datetime Timestamp when the bigmap was allocated.
height int64 Last update height.
time datetime Last update timestamp.

Bigmap Type

Example request.

curl "https://api.tzstats.com/explorer/bigmap/1/type"

Example response.

{
  "key_type": {
    // ...
  },
  "value_type": {
    // ...
  }
}

Returns bigmap type description in Michelson JSON format, both for keys and values. Keys are always simple scalar types and values can have a simple or complex type.

HTTP Request

GET https://api.tzstats.com/explorer/bigmap/{id}/type

HTTP Response

Field Description
key_type object Michelson type for keys (i.e. any comparable Michelson type) as JSON encoded Michelson primitives.
value_type object Michelson type for values as JSON encoded Michelson primitives.

List Bigmap Keys

Example request.

curl "https://api.tzstats.com/explorer/bigmap/382/keys"

Example response.

[{
    "key_type": "key_hash",
    "key_encoding": "bytes",
    "key_hash": "expruUBFeTjjbsfCajJrpWANdA4eyaw1ZbDNECXkxVpB1krGW5P6N1",
    "key": "tz1P2Po7YM526ughEsRbY4oR9zaUPDZjxFrb",
    "encoded_key": "002523250b271e153be6c2668954114be101d04d3d",
    "time": "2019-11-08T05:00:20Z",
    "height": 79571
  },
  // ...
]

Lists keys contained in bigmap. This endpoint supports paging with limit and offset and also allows locking paginated calls to a specific height (int64).

HTTP Request

GET https://api.tzstats.com/explorer/bigmap/{id}/keys

HTTP Response

Field Description
key_type enum Michelson type of keys (any allowed Michelson type).
key_encoding enum Encoding used for keys (e.g. string, bytes, int).
key_hash hash A script expression hash.
key string The original key, e.g. an address or integer.
encoded_key string The encoded (binary) version of the key as hex.
time datetime Timestamp of last update.
height int64 Height of last update.

List Bigmap Keys and Values

Example request.

curl "https://api.tzstats.com/explorer/bigmap/382/values"

Example response.

[
  {
    "key": {
      "key_type": "key_hash",
      "key_encoding": "bytes",
      "key_hash": "exprvKTxtJMTa4jD3RW8YZtjMapBCv6sG592coBC1xr9qFzRfjMAnA",
      "key": "tz1KfEsrtDaA1sX7vdM4qmEPWuSytuqCDp5j",
      "encoded_key": "00003a96709901319a5da2968782279dae581b9ba4",
      "time": "2019-11-08T05:00:20Z",
      "height": 79571
    },
    "prim": {
      // ...
    },
    "value": {
      // ...
    }
  }
]

Lists key/value pairs contained in bigmap. This endpoint supports paging with limit and offset and also allows locking paginated calls to a specific height. Use prim (boolean) to embed Michelson prim trees in addition to unboxed values. Returns an array of objects.

HTTP Request

GET https://api.tzstats.com/explorer/bigmap/{id}/values

Lists all values currently contained in the bigmap. With optional height (int64) parameter, returns the contents of the bigmap at the specified height.

GET https://api.tzstats.com/explorer/bigmap/{id}/{key}

Returns a single bigmap value stored at key. Key can be a key hash (script expr hash), the native key representation (i.e. an address or integer) or the encoded binary version of the the key. Use the optional height (int64) parameter to lookup the key’s value at a specific block in the past.

HTTP Response

Field Description
key object The bigmap key as defined above.
prim object Native Michelson JSON encoded value as prim tree (hidden by default, use prim to enable).
value object An unboxed version of the bigmap value using Michelson types and type annotations to map value to JSON. Works for simple values and complex nested structures such as scalar types, lists, sets, maps, and bigmaps.

List Bigmap Updates

Example request.

curl "https://api.tzstats.com/explorer/bigmap/382/updates"

Example response.

[
  {
    "action": "update",
    "bigmap_id": 382,
    "key": {
      "key_type": "key_hash",
      "key_encoding": "bytes",
      "key_hash": "exprvKTxtJMTa4jD3RW8YZtjMapBCv6sG592coBC1xr9qFzRfjMAnA",
      "key": "tz1KfEsrtDaA1sX7vdM4qmEPWuSytuqCDp5j",
      "encoded_key": "00003a96709901319a5da2968782279dae581b9ba4",
      "time": "2019-11-08T05:00:20Z",
      "height": 79571
    },
    "prim": {
      // ...
    },
    "value": {
      // ...
    }
  }
]

List historic updates to the bigmap in chronological order, including keys that have been deleted. This endpoint supports paging with limit and offset. Use the optional since (int64) parameter to return updates newer or equal to a specific height and prim (boolean) to embed Michelson prim trees in addition to unboxed values. Returns an array of objects.

HTTP Request

GET https://api.tzstats.com/explorer/bigmap/{id}/updates

Lists all updates across the entire bigmap.

GET https://api.tzstats.com/explorer/bigmap/{id}/{key}/updates

Lists updates for a specific key. Key can be a key hash (script expr hash), the native key representation (i.e. an address or integer) or the encoded binary version of.

HTTP Response

Field Description
key object The bigmap key as defined above.
prim object Native Michelson JSON encoded value as prim tree.
value object An unboxed version of the bigmap value using Michelson types and type annotations to map value to JSON. Works for simple values and complex nested structures such as scalar types, lists, sets, maps, and bigmaps.

Blocks

Example request.

curl "https://api.tzstats.com/explorer/block/627341"

Example response.

{
  "hash": "BLWT4x43zqzbtRzWNShkuU1DaTjU9fX34Qs4V3Hku2ZgYxiEpPW",
  "predecessor": "BKqv8SBNabXEMXV9fsy21yx9BNsqWBKVVp9ca4KTMpGsF2Wi8Uj",
  "successor": "BLFjwCUTebnhw6ZWpQNxa9VjZgGLgnp1Zazb21T1356VFEnxPrZ",
  "baker": "tz1cZfFQpcYhwDp7y1njZXDsZqCrn2NqmVof",
  "height": 627342,
  "cycle": 153,
  "is_cycle_snapshot": false,
  "time": "2019-09-28T13:11:51Z",
  "solvetime": 60,
  "version": 4,
  "validation_pass": 4,
  "fitness": 19846458,
  "priority": 0,
  "nonce": 11996642917503807005,
  "voting_period_kind": "promotion_vote",
  "endorsed_slots": 4294965247,
  "n_endorsed_slots": 31,
  "n_ops": 24,
  "n_ops_failed": 0,
  "n_ops_contract": 0,
  "n_tx": 1,
  "n_activation": 0,
  "n_seed_nonce_revelation": 0,
  "n_double_baking_evidence": 0,
  "n_double_endorsement_evidence": 0,
  "n_endorsement": 23,
  "n_delegation": 0,
  "n_reveal": 0,
  "n_origination": 0,
  "n_proposal": 0,
  "n_ballot": 0,
  "volume": 2.434174,
  "fees": 0.00142,
  "rewards": 80,
  "deposits": 2560,
  "unfrozen_fees": 0,
  "unfrozen_rewards": 0,
  "unfrozen_deposits": 0,
  "activated_supply": 0,
  "burned_supply": 0,
  "n_accounts": 26,
  "n_new_accounts": 0,
  "n_new_implicit": 0,
  "n_new_managed": 0,
  "n_new_contracts": 0,
  "n_cleared_accounts": 0,
  "n_funded_accounts": 0,
  "gas_limit": 10300,
  "gas_used": 10200,
  "gas_price": 0.13922,
  "storage_size": 0,
  "days_destroyed": 0.003381,
  "pct_account_reuse": 100,
  "endorsers": [
    "tz1LLNkQK4UQV6QcFShiXJ2vT2ELw449MzAA",
    "tz1isXamBXpTUgbByQ6gXgZQg4GWNW7r6rKE",
    "tz1gk3TDbU7cJuiBRMhwQXVvgDnjsxuWhcEA",
    "tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m",
    "tz1MXFrtZoaXckE41bjUCSjAjAap3AFDSr3N",
    "tz1dZhK4HMbGTPUucpKy1rNG1WfYLqdRMs6Z",
    "tz3bvNMQ95vfAYtG8193ymshqjSvmxiCUuR5",
    "tz1KtvGSYU5hdKD288a1koTBURWYuADJGrLE",
    "tz1TaLYBeGZD3yKVHQGBM857CcNnFFNceLYh",
    "tz3RB4aoyjov4KEVRbuhvQ1CKJgBJMWhaeB8",
    "tz3bTdwZinP8U1JmSweNzVKhmwafqWmFWRfk",
    "tz1Ukm38BsGU58drCoJ31u3w6kgPo4oda4gL",
    "tz1TzaNn7wSQSP5gYPXCnNzBCpyMiidCq1PX",
    "tz1UHxJUMWHY4FxK3RxgbSdwMXAhEzmoLVWA",
    "tz3bTdwZinP8U1JmSweNzVKhmwafqWmFWRfk",
    "tz1NPbgLoqoct15RfrGu29DhUw41sVvTmqjP",
    "tz1VQnqCCqX4K5sP3FNkVSNKTdCAMJDd3E1n",
    "tz1T7duV5gZWSTq4YpBGbXNLTfznCLDrFxvs",
    "tz3RB4aoyjov4KEVRbuhvQ1CKJgBJMWhaeB8",
    "tz3NExpXn9aPNZPorRE4SdjJ2RGrfbJgMAaV",
    "tz3bTdwZinP8U1JmSweNzVKhmwafqWmFWRfk",
    "tz3VEZ4k6a4Wx42iyev6i2aVAptTRLEAivNN",
    "tz3VEZ4k6a4Wx42iyev6i2aVAptTRLEAivNN",
    "tz1LmaFsWRkjr7QMCx5PtV6xTUz3AmEpKQiF",
    "tz1VmiY38m3y95HqQLjMwqnMS7sdMfGomzKi",
    "tz1ajgycuHmd2z2JbTSJxKv7x6cok2KuNSk1",
    "tz1bHzftcTKZMTZgLLtnrXydCm6UEqf4ivca",
    "tz3bTdwZinP8U1JmSweNzVKhmwafqWmFWRfk",
    "tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m",
    "tz1irJKkXS2DBWkU1NnmFQx1c1L7pbGg4yhk",
    "tz1cmvE9SbB63z9GB1h64P3YawsMqiBmQpCG",
    "tz3VEZ4k6a4Wx42iyev6i2aVAptTRLEAivNN"
  ]
}

Fetches information about the specified block. Takes either a block hash, a block height or the string head as argument.

HTTP Request

GET https://api.tzstats.com/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.
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.
validation_pass int64 Block validation pass.
fitness int64 Block fitness used to determine longest chain.
priority int64 Baking priority.
nonce uint64 Block nonce
voting_period_kind enum Current voting period proposal, testing_vote, testing, promotion_vote.
endorsed_slots uint64 32bit big-endian bitmask indicating which slots have been endorsed. (Note this field will be set from endorsements published in the subsequent block.)
n_endorsed_slots int64 Count of endorsed slots. (Note this field will be set from endorsements published in the subsequent block.)
n_ops int64 Count of operations contained in this block.
n_ops_failed int64 Count of failed operations.
n_ops_contract int64 Count of smart contract operations (transactions sent to contracts and internal operations sent by contracts).
n_tx int64 Count of transaction operations.
n_activation int64 Count of activate_account operations.
n_seed_nonce_revelation int64 Count of seed_nonce_revelation operations.
n_double_baking_evidence int64 Count of double_baking_evidence operations.
n_double_endorsement_evidence int64 Count of double_endorsement_evidence operations.
n_endorsement int64 Count of endorsement operations.
n_delegation int64 Count of delegation operations.
n_reveal int64 Count of reveal operations.
n_origination int64 Count of origination operations.
n_proposal int64 Count of proposals operations.
n_ballot int64 Count of ballot operations.
volume money Total amount of tokens moved between accounts.
fees money Total fees paid (and frozen) by all operations.
rewards money Total rewards earned (and frozen) by baker and endorsers.
deposits money Total deposits frozen by baker and endorsers.
unfrozen_fees money Total unfrozen fees (at end of a cycle).
unfrozen_rewards money Total unfrozen rewards (at end of a cycle).
unfrozen_deposits money Total unfrozen deposits (at end of a cycle).
activated_supply money Total amount of commitments activated in tz.
burned_supply money Total amount of tokens burned by operations in tz.
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_implicit int64 Count of created implicit accounts (tz1/2/3).
n_new_managed int64 Count of created managed accounts (KT1 without code or manager.tz script).
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.
gas_price float Avergae price of one gas unit in mutez.
storage_size int64 Total sum of new storage allocated by operations.
days_destroyed float Token days destroyed (tokens transfered * token idle time).
pct_account_reuse float Portion of seen accounts that existed before.
endorsers array[hash] List of delegates with rights to endorse this block in slot order.

Blockchain Config

Example request.

curl "https://api.tzstats.com/explorer/config/head"

Example response.

{
  "name": "Tezos",
  "network": "Mainnet",
  "symbol": "XTZ",
  "chain_id": "NetXdQprcVkpaWU",
  "version": 5,
  "deployment": 6,
  "protocol": "PsBabyM1eUXZseaJdmXFApDSBqj8YBfwELoxZHHW77EMcAbbwAS",
  "start_height": -1,
  "end_height": -1,
  "no_reward_cycles": 0,
  "security_deposit_ramp_up_cycles": 0,
  "decimals": 6,
  "units": 1000000,
  "block_reward": 16,
  "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": 1000,
  "endorsement_reward": 2,
  "endorsement_security_deposit": 64,
  "endorsers_per_block": 32,
  "hard_gas_limit_per_block": 8000000,
  "hard_gas_limit_per_operation": 800000,
  "hard_storage_limit_per_operation": 60000,
  "max_operation_data_length": 16384,
  "max_proposals_per_delegate": 20,
  "max_revelations_per_block": 32,
  "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
}

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 https://api.tzstats.com/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, Sandbox).
chain_id hash Chain hash.
version int64 Protocol version number.
deployment int64 Number of deployed protocols on this network.
protocol hash Protool 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 tz.
block_security_deposit money Baker security deposit in tz.
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 tz.
endorsement_security_deposit money Endorser security deposit per slot in tz.
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 Minimum quorum to accept proposals in centile (i.e. 5% = 500).
quorum_min int64 Minimum threshold for voting period quorum in centile.
quorum_max int64 Maximum threshold for voting period quorum in centile.

Blockchain Tip

Example request.

curl "https://api.tzstats.com/explorer/tip"

Example response.

{
  "name": "Tezos",
  "symbol": "XTZ",
  "network": "Mainnet",
  "chain_id": "NetXdQprcVkpaWU",
  "genesis_time": "2018-06-30T16:07:32Z",
  "block_hash": "BL326wcsdVU2Gp1PqnEgbP26dzM1crnevoTJXDQnPPJ1LAqVwv3",
  "timestamp": "2019-09-27T21:23:47Z",
  "height": 626408,
  "cycle": 152,
  "total_accounts": 333538,
  "funded_accounts": 298038,
  "total_ops": 15059205,
  "delegators": 17007,
  "delegates": 481,
  "rolls": 71897,
  "roll_owners": 459,
  "new_accounts_30d": 9848,
  "cleared_accounts_30d": 2195,
  "funded_accounts_30d": 9326,
  "inflation_1y": 39223088.146111,
  "inflation_rate_1y": 5.098069887192244,
  "health": 100,
  "supply": {
    "height": 626408,
    "cycle": 152,
    "time": "2019-09-27T21:23:47Z",
    "total": 810708076.643151,
    "activated": 526825268.109869,
    "unclaimed": 84629610.300311,
    "vested": 27582743.42817,
    "unvested": 125280976.17435,
    "circulating": 536764651.120734,
    "delegated": 457179960.469034,
    "staking": 580619999.307627,
    "active_delegated": 455871344.805448,
    "active_staking": 576682219.775331,
    "inactive_delegated": 1308615.663586,
    "inactive_staking": 3937779.532296,
    "minted": 46545468.745557,
    "minted_baking": 9685699.106655,
    "minted_endorsing": 36857356.263902,
    "minted_seeding": 2413.375,
    "minted_airdrop": 100,
    "burned": 155990.115106,
    "burned_double_baking": 103509.825621,
    "burned_double_endorse": 31838.219485,
    "burned_origination": 6574.002,
    "burned_implicit": 14068.068,
    "burned_seed_miss": 2576.671187,
    "frozen": 64032839.047756,
    "frozen_deposits": 62097662,
    "frozen_rewards": 1934957.146609,
    "frozen_fees": 219.901147
  },
  "status": {
    "status": "synced",
    "blocks": 626408,
    "indexed": 626408,
    "progress": 1
  }
}

Returns info about the most recent block as well as some on-chain and supply statistics.

HTTP Request

GET https://api.tzstats.com/explorer/tip

HTTP Response

Field Description
name string Blockchain name (Tezos).
symbol string Ticker symbol (XTZ).
network string Network name (e.g. Mainnet, Zeronet, 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 Total number of on-chain accounts in existence.
funded_accounts int64 Total number on funded (non-zero) accounts.
total_ops int64 Total number of on-chain operations.
delegators int64 Current number of delegators (updated each block).
delegates int64 Current number of active delegates (updated each block).
rolls int64 Current number of network-wide rolls (updated each block).
roll_owners int64 Current number of network-wide roll owners (updated each block).
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 tz.
inflation_rate_1y float Relative annualized inflation in percent.
health int64 Blockchain and consensus health indicator with range [0..100].
supply object Coin supply statistics at current block height.
status object Indexer status, embedded for efficiency.

Contracts

Example request.

curl "https://api.tzstats.com/explorer/contract/KT1QuofAgnsWffHzLA7D78rxytJruGHDe7XG"

Example response.

{
  "address": "KT1QuofAgnsWffHzLA7D78rxytJruGHDe7XG",
  "manager": "",
  "delegate": "tz3RDC3Jdn4j15J7bBHZd29EUee9gVB1CxD9",
  "height": 1,
  "fee": 0,
  "gas_limit": 0,
  "gas_used": 0,
  "gas_price": 0,
  "storage_limit": 0,
  "storage_size": 0,
  "storage_paid": 0,
  "is_funded": true,
  "is_vesting": true,
  "is_spendable": false,
  "is_delegatable": false,
  "is_delegated": true,
  "first_in": 30,
  "first_out": 30,
  "last_in": 30,
  "last_out": 30,
  "first_seen": 1,
  "last_seen": 30,
  "delegated_since": 1,
  "first_in_time": "2018-06-30T18:11:27Z",
  "first_out_time": "2018-06-30T18:11:27Z",
  "last_in_time": "2018-06-30T18:11:27Z",
  "last_out_time": "2018-06-30T18:11:27Z",
  "first_seen_time": "2018-06-30T17:39:57Z",
  "last_seen_time": "2018-06-30T18:11:27Z",
  "delegated_since_time": "2018-06-30T17:39:57Z",
  "n_ops": 3,
  "n_ops_failed": 0,
  "n_tx": 3,
  "n_delegation": 0,
  "n_origination": 0,
  "token_gen_min": 0,
  "token_gen_max": 0,
  "bigmap_ids": []
}

Provides information about a smart contract with embedded code and initial storage.

HTTP Requests

Get Contract Metadata

GET https://api.tzstats.com/explorer/contract/{hash}

Returns metadata about the smart contract. For more details call the explorer account endpoint using the contract’s KT1 address.

Get Contract Manager (or Originator when >= Babylon)

GET https://api.tzstats.com/explorer/contract/{hash}/manager

Returns the manager of the contract (before Babylon) or the originator (Babylon and later).

Get Contract Delegate (if any)

GET https://api.tzstats.com/explorer/contract/{hash}/delegate

Returns the current delegate the contract is delegating to.

Get Contract Script

GET https://api.tzstats.com/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.

Get Contract Storage

GET https://api.tzstats.com/explorer/contract/{hash}/storage

Returns the most recent content of the contract’s storage or, when using the optional height argument, a prior state at or before a specified height. Use the optional prim (boolean) argument to embed Michelson JSON primitives.

List Contract Calls

GET https://api.tzstats.com/explorer/contract/{hash}/calls

Returns calls (transactions) sent to the contract with embedded praramters, storage and bigmap updates. Use the optional prim (boolean) argument to embed Michelson primitive trees in addition to unboxed call data.

HTTP Response

Field Description
address hash Contract address.
manager hash Manager account (deprecated in v005 Babylon).
delegate hash Delegate (may be empty).
height int64 Origination block height.
fee money Fee paid on contract origination.
gas_limit int64 Gas limit on contract origination.
gas_used int64 Gas used on contract origination.
gas_price float Gas price on contract origination.
storage_limit int64 Storage limit defined on contract origination op.
storage_size int64 Storage size allocated in bytes.
storage_paid int64 Storage bytes paid for in bytes.
is_funded bool Flag indicating the contract is funded.
is_vesting bool Flag indicating the contract is a vesting contract.
is_spendable bool Flag indicating the contract balance is spendable.
is_delegatable bool Flag indicating the contract is delegatable.
is_delegated bool Flag indicating the contract is currently delegated.
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.
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.
delegated_since_time datetime Block time of most recent delegation.
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.
token_gen_min int64 Minimum generation number of all tokens owned.
token_gen_max int64 Maximum generation number of all tokens owned.
bigmap_ids []int64 Array of bigmap ids owned by this contract.

Unboxed Call Parameters

Example call parameters.

// ...
"parameters": {
  "entrypoint": "default",
  "prim": {
    // ...
  },
  "value": {
  //...
  }
},
// ...
Field Description
entrypoint string Call function or entrypoint into the smart contract.
prim object Michelson JSON encoded representation of call parameters (hidden by default, enable with prim=true).
value object Unboxed parameters mapped using parameter type and annotations.

Unboxed Contract Storage

Example storage update.

// ...
"storage": {
  "prim": {
    // ...
  },
  "value": {
  //...
  }
},
// ...
Field Description
prim object Michelson JSON encoded representation of contract storage after the call (hidden by default, enable with prim=true).
value object Unboxed storage content mapped using parameter type and annotations.

Unboxed BigMap Updates

Example storage update.

// ...
"big_map_diff": [{
  "action": "update",
  "bigmap_id": 444,
  "key": {
    "key_type": "bytes",
    "key_encoding": "bytes",
    "key_hash": "expruDLN1rQemarRkrDCAd4S39oKfN2vnaQXpsATbaZoa9NeVKVYEC",
    "key": "000caf7e100ecc49dd684621a257f6a92e5cd5a40b",
    "encoded_key": "000caf7e100ecc49dd684621a257f6a92e5cd5a40b",
    "time": "2019-11-12T03:32:46Z",
    "height": 86052
  },
  "prim": {
    // ...
  },
  "value": {
  //...
  }
}]
// ...
Field Description
action enum Update kind, one of alloc, update, remove, copy.
bigmap_id int64 Unique on-chain id of the bigmap.
key object Key of the updated bigmap entry. Only present on update and remove.
key_type enum Michelson type of the key.
key_encoding enum Michelson encoding of the key (string, bytes, int).
key_hash hash The script expression hash for this key.
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).
encoded_key string Hex string containing the binary representation of the key as stored on-chain.
time datetime Update timestamp, same as for call (transaction).
height int64 Update height, same as for call (transaction).
prim object Michelson JSON encoded representation of the updated bigmap value (hidden by default, enable with prim=true). Only present on update and remove.
value object Unboxed bigmap value mapped using parameter type and annotations. Only present on update and remove.
key_type object Michelson JSON encoded representation of bigmap key type. Only present on alloc and copy.
value_type object Michelson JSON encoded representation of bigmap value type. Only present on alloc and copy.
source_big_map int64 Source bigmap id. Only present on copy.
destination_big_map int64 Source bigmap id. Only present on copy.

Cycles

Example request.

curl "https://api.tzstats.com/explorer/cycle/head"

Example response.

{
  "cycle": 153,
  "start_height": 626689,
  "end_height": 630784,
  "start_time": "2019-09-28T02:13:20Z",
  "end_time": "2019-09-30T22:53:57Z",
  "progress": 58.935546875,
  "is_complete": false,
  "is_snapshot": false,
  "is_active": true,
  "snapshot_height": -1,
  "snapshot_index": -1,
  "rolls": 71965,
  "roll_owners": 458,
  "staking_supply": 581115775.293209,
  "staking_percent": 71.66191388216313,
  "active_bakers": 200,
  "active_endorsers": 421,
  "missed_priorities": 22,
  "missed_endorsements": 459,
  "n_double_baking": 0,
  "n_double_endorsement": 0,
  "n_orphans": 0,
  "solvetime_min": 60,
  "solvetime_max": 285,
  "solvetime_mean": 60.72990886495457,
  "priority_min": 0,
  "priority_max": 3,
  "priority_mean": 0.009113504556752305,
  "endorsement_rate": 99.4055636137588,
  "endorsements_min": 25,
  "endorsements_max": 32,
  "endorsements_mean": 31.80978035640282,
  "seed_rate": 168,
  "worst_baked_block": 626689,
  "worst_endorsed_block": 626689,
  "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 who’s rights are deterined by the current cycle. This endpoint accepts head and a cycle number as path parameters.

HTTP Request

GET https://api.tzstats.com/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.
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 Percent of total supply staked at selected snapshot block or most recent snapshot block.
active_bakers int64 Number of unique bakers seen.
active_endorsers int64 Number of unique endorsers seen.
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 expectd 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": 13,
  "num_periods": 4,
  "num_proposals": 2,
  "start_time": "2019-07-16T19:02:34Z",
  "end_time": "2019-10-18T00:29:57Z",
  "start_height": 524288,
  "end_height": 655359,
  "is_empty": false,
  "is_open": true,
  "is_failed": false,
  "no_quorum": false,
  "no_majority": false,
  "no_proposal": false,
  "voting_period": "promotion_vote",
  "proposal": {
    "voting_period": 15,
    "voting_period_kind": "proposal",
    "period_start_time": "2019-07-16T19:02:34Z",
    "period_end_time": "2019-08-09T06:46:57Z",
    "period_start_block": 524288,
    "period_end_block": 557055,
    "eligible_rolls": 70159,
    "eligible_voters": 461,
    "quorum_pct": 0,
    "quorum_rolls": 0,
    "turnout_rolls": 43133,
    "turnout_voters": 225,
    "turnout_pct": 6147,
    "turnout_ema": 0,
    "yay_rolls": 0,
    "yay_voters": 0,
    "nay_rolls": 0,
    "nay_voters": 0,
    "pass_rolls": 0,
    "pass_voters": 0,
    "is_open": false,
    "is_failed": false,
    "is_draw": false,
    "no_proposal": false,
    "no_quorum": false,
    "no_majority": false,
    "proposals": [
      {
        "hash": "PsBABY5nk4JhdEv1N1pZbt6m6ccB9BfNqa23iKZcHBh23jmRS9f",
        "source": "tz1eEnQhbwf6trb8Q8mPb2RaPkNk2rN7BKi8",
        "block_hash": "BLkbt55K5YZMPtjrSfo3ericxRaeXcwEwawfE5BkT9H5ZbZnLQV",
        "op_hash": "op4mZHRe1xTmYG34xYRwpGaGMAfTp6S82eeebgNZmdtNW6szeeX",
        "height": 537802,
        "time": "2019-07-26T13:20:04Z",
        "rolls": 19964,
        "voters": 146
      },
      {
        "hash": "PsBABY5HQTSkA4297zNHfsZNKtxULfL18y95qb3m53QJiXGmrbU",
        "source": "tz1eEnQhbwf6trb8Q8mPb2RaPkNk2rN7BKi8",
        "block_hash": "BLzSKKWp9NyrNrZrZgWin3m2zjPVUJfxNn1QkCzt9aZy7ZLWgJJ",
        "op_hash": "ooDAtGzFBeRUJcEK3QRBHU3kzk31CAp2RARYE3kmU3qsrvgs8JN",
        "height": 547386,
        "time": "2019-08-02T09:42:56Z",
        "rolls": 66302,
        "voters": 304
      }
    ]
  },
  "testing_vote": {
    "voting_period": 16,
    "voting_period_kind": "testing_vote",
    "period_start_time": "2019-08-09T06:48:02Z",
    "period_end_time": "2019-09-01T17:52:51Z",
    "period_start_block": 557056,
    "period_end_block": 589823,
    "eligible_rolls": 70585,
    "eligible_voters": 464,
    "quorum_pct": 7291,
    "quorum_rolls": 51463,
    "turnout_rolls": 57818,
    "turnout_voters": 179,
    "turnout_pct": 8191,
    "turnout_ema": 0,
    "yay_rolls": 37144,
    "yay_voters": 171,
    "nay_rolls": 0,
    "nay_voters": 0,
    "pass_rolls": 20674,
    "pass_voters": 8,
    "is_open": false,
    "is_failed": false,
    "is_draw": false,
    "no_proposal": false,
    "no_quorum": false,
    "no_majority": false,
    "proposals": [
      {
        "hash": "PsBABY5HQTSkA4297zNHfsZNKtxULfL18y95qb3m53QJiXGmrbU",
        "source": "tz1eEnQhbwf6trb8Q8mPb2RaPkNk2rN7BKi8",
        "block_hash": "BLzSKKWp9NyrNrZrZgWin3m2zjPVUJfxNn1QkCzt9aZy7ZLWgJJ",
        "op_hash": "ooDAtGzFBeRUJcEK3QRBHU3kzk31CAp2RARYE3kmU3qsrvgs8JN",
        "height": 547386,
        "time": "2019-08-02T09:42:56Z",
        "rolls": 0,
        "voters": 0
      }
    ]
  },
  "testing": {
    "voting_period": 17,
    "voting_period_kind": "testing",
    "period_start_time": "2019-09-01T17:53:51Z",
    "period_end_time": "2019-09-25T04:30:36Z",
    "period_start_block": 589824,
    "period_end_block": 622591,
    "eligible_rolls": 71053,
    "eligible_voters": 469,
    "quorum_pct": 0,
    "quorum_rolls": 0,
    "turnout_rolls": 0,
    "turnout_voters": 0,
    "turnout_pct": 0,
    "turnout_ema": 0,
    "yay_rolls": 0,
    "yay_voters": 0,
    "nay_rolls": 0,
    "nay_voters": 0,
    "pass_rolls": 0,
    "pass_voters": 0,
    "is_open": false,
    "is_failed": false,
    "is_draw": false,
    "no_proposal": false,
    "no_quorum": false,
    "no_majority": false,
    "proposals": [
      {
        "hash": "PsBABY5HQTSkA4297zNHfsZNKtxULfL18y95qb3m53QJiXGmrbU",
        "source": "tz1eEnQhbwf6trb8Q8mPb2RaPkNk2rN7BKi8",
        "block_hash": "BLzSKKWp9NyrNrZrZgWin3m2zjPVUJfxNn1QkCzt9aZy7ZLWgJJ",
        "op_hash": "ooDAtGzFBeRUJcEK3QRBHU3kzk31CAp2RARYE3kmU3qsrvgs8JN",
        "height": 547386,
        "time": "2019-08-02T09:42:56Z",
        "rolls": 0,
        "voters": 0
      }
    ]
  },
  "promotion_vote": {
    "voting_period": 18,
    "voting_period_kind": "promotion_vote",
    "period_start_time": "2019-09-25T04:32:51Z",
    "period_end_time": "2019-10-18T00:28:57Z",
    "period_start_block": 622592,
    "period_end_block": 655359,
    "eligible_rolls": 71840,
    "eligible_voters": 463,
    "quorum_pct": 7471,
    "quorum_rolls": 53671,
    "turnout_rolls": 11895,
    "turnout_voters": 79,
    "turnout_pct": 1655,
    "turnout_ema": 0,
    "yay_rolls": 11044,
    "yay_voters": 71,
    "nay_rolls": 844,
    "nay_voters": 6,
    "pass_rolls": 7,
    "pass_voters": 2,
    "is_open": true,
    "is_failed": false,
    "is_draw": false,
    "no_proposal": false,
    "no_quorum": false,
    "no_majority": false,
    "proposals": [
      {
        "hash": "PsBABY5HQTSkA4297zNHfsZNKtxULfL18y95qb3m53QJiXGmrbU",
        "source": "tz1eEnQhbwf6trb8Q8mPb2RaPkNk2rN7BKi8",
        "block_hash": "BLzSKKWp9NyrNrZrZgWin3m2zjPVUJfxNn1QkCzt9aZy7ZLWgJJ",
        "op_hash": "ooDAtGzFBeRUJcEK3QRBHU3kzk31CAp2RARYE3kmU3qsrvgs8JN",
        "height": 547386,
        "time": "2019-08-02T09:42:56Z",
        "rolls": 0,
        "voters": 0
      }
    ]
  }
}

Shows full detail about a past or current election including up to four voting periods and detailed results. 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. Votes represent on-chain voting periods, proposals represent individual proposals that are submitted by a source and upvoted by other bakers, ballots represent the individual ballot operations sent by bakers during votes.

HTTP Request

GET https://api.tzstats.com/explorer/election/{head,number}

HTTP Response

Field Description
election_id int64 Sequence number of the election.
num_periods int64 Number of voting periods activated durin 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 beeing submitted.
is_open bool Flag indicating the election is onging.
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, testing_vote, testing, promotion_vote.
proposal object Vote object for the proposal period 1 (see below).
testing_vote object Vote object for the testing vote period 2 (see below).
testing object Vote object for the testing period 3 (see below).
promotion_vote object Vote object for the promotion vote period 4 (see below).

Voting Period Object

Field Description
voting_period int64 Protocol-level voting period counter.
voting_period_kind enum Period kind proposal, testing_vote, testing, promotion_vote.
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_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.
turnout_rolls int64 Actual rolls who voted.
turnout_voters int64 Actual voters who voted.
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_voters int64 Number of Yay voters.
nay_rolls int64 Number of Nay rolls.
nay_voters int64 Number of Nay voters.
pass_rolls int64 Number of Pass rolls.
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 submotted 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.
voters int64 Count of voters voting for this proposal during the proposal period.

Indexer Status

Example request.

curl "https://api.tzstats.com/explorer/status"

Example response.

{
  "status": "synced",
  "blocks": 626399,
  "indexed": 626399,
  "progress": 1
}

Returns the current indexer status, useful to check of the indexer is in sync with the blockchain.

HTTP Request

GET https://api.tzstats.com/explorer/status

HTTP Response

Field Description
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.

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 https://api.tzstats.com/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 curreny.
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.

Operations

Example request.

curl "https://api.tzstats.com/explorer/op/ooxRwXAEM76NyMGyn4hHjS9D2Q8UkWVV6W2Esk2LZaq2tzFBH3p"

Example response.

[
  {
    "hash": "ooxRwXAEM76NyMGyn4hHjS9D2Q8UkWVV6W2Esk2LZaq2tzFBH3p",
    "type": "transaction",
    "block": "BKqv8SBNabXEMXV9fsy21yx9BNsqWBKVVp9ca4KTMpGsF2Wi8Uj",
    "time": "2019-09-28T13:10:51Z",
    "height": 627341,
    "cycle": 153,
    "counter": 1946527,
    "op_n": 26,
    "op_c": 0,
    "op_i": 0,
    "status": "applied",
    "is_success": true,
    "is_contract": false,
    "gas_limit": 10300,
    "gas_used": 10200,
    "gas_price": 0.98039,
    "storage_limit": 0,
    "storage_size": 0,
    "storage_paid": 0,
    "volume": 2047.9,
    "fee": 0.01,
    "reward": 0,
    "deposit": 0,
    "burned": 0,
    "is_internal": false,
    "has_data": false,
    "days_destroyed": 203.367847,
    "parameters": null,
    "storage": null,
    "data": null,
    "big_map_diff": null,
    "errors": null,
    "sender": "tz1bnaCyDdJNjD8TcZPLNc2kBfJsYhNe86Lm",
    "receiver": "tz1a6WGHRq16ENkxbJVHbtGX4D6mUkCGo5sA",
    "branch_id": 627341,
    "branch_height": 627340,
    "branch_depth": 1,
    "branch": "BKr3kjkbi5LndjDTDDSPUWubZjrdSBCWLJudmuGYuiVuG2j8fvj"
  }
]

Returns info about a single operation or a list of related operations. Because Tezos supports batch operations (multiple operatiosn 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.

HTTP Request

GET https://api.tzstats.com/explorer/op/{hash}

HTTP Response

Field Description
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 Operation position in block. (Tezos defines 4 arrays used for the different op verification steps. The op_n value represents the global operation position across all these arrays.)
op_c int64 Bulk operation list position.
op_i int64 Internal operation list position.
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.
gas_price float Effective price per gas unit in mutez.
storage_limit int64 Caller-defined storage limit.
storage_size int64 Actual storage size allocated.
storage_paid int64 Part of the storage the operation paid for.
volume money Amount of tokens transferred in tz.
fee money Fees paid in tz.
reward money Rewards earned in tz.
deposit money Amount of deposited tokens in tz.
burned money Amount of burned tokens in tz.
is_internal bool Flag indicating if this operation was sent be a smart contract.
has_data bool Flag indicating if extra data or parameters are present.
data polymorph Extra type-dependent operation data. See below.
parameters object Call parameters as embedded JSON object, contract-only.
storage object Updated contract storage as embedded JSON object, contract-only.
big_map_diff object Inserted, updated or deleted bigmap entries as embedded JSON object, contract-only.
errors object When failed, contains details about the reason as JSON object.
days_destroyed float Token days destroyed by this operation (tokens transfered * token idle time).
parameters object Contract call parameters.
storage object Updated version of contract storage after call.
data object Extra operation data (see below for content encoding).
big_map_diff array List of bigmap updates.
errors object Embedded native Tezos RPC error object.
sender hash Operation sender, always set.
receiver hash Transaction receiver, may be empty.
delegate hash New Delegate, only used by origination and delegation. When empty for a delegation the operation was a delegate withdrawal.
manager hash Contract manager, origination only.
branch_id uint64 Row id of the branch block this op refers to.
branch_height int64 Height of the branch block this op refers to.
branch_depth int64 Count of blocks between branch block and block including this op.
branch hash Block hash of the branch this op refers to.

List of supported operation types

Decoding Operation Data

Some operations contain extra data in the polymorphic data field. This field exists when the has_data flag is true. Decoding the data depends on the operation type.

Operation Data Type Specification
activate_account 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
seed_nonce_revelation string level,hex(nonce)
double_baking_evidence object JSON array of double signed block headers
double_endorsemnt_evidence object JSON array of double signed endorsements
transaction - unused, see parameters, storage and big_map_diff

List Operations

Example request to list block operations.

curl "https://api.tzstats.com/explorer/block/head/op"

Example response.

{
  "hash": "BLFjwCUTebnhw6ZWpQNxa9VjZgGLgnp1Zazb21T1356VFEnxPrZ",
  "predecessor": "BLWT4x43zqzbtRzWNShkuU1DaTjU9fX34Qs4V3Hku2ZgYxiEpPW",
  "baker": "tz1S1Aew75hMrPUymqenKfHo8FspppXKpW7h",
  "height": 627343,
  "cycle": 153,
  // ...
  "ops": [{
      "hash": "oozRTWSPr2M2rr1EQKaU4uVgu4kP28UnTu1tMS24DoTAZiC3kx3",
      "type": "endorsement",
      "block": "BLFjwCUTebnhw6ZWpQNxa9VjZgGLgnp1Zazb21T1356VFEnxPrZ",
      "time": "2019-09-28T13:12:51Z",
      "height": 627343,
      "cycle": 153,
      "counter": 0,
      "op_n": 0,
      "op_c": 0,
      "op_i": 0,
      "status": "applied",
      "is_success": true,
      "is_contract": false,
      "gas_limit": 0,
      "gas_used": 0,
      "gas_price": 0,
      "storage_limit": 0,
      "storage_size": 0,
      "storage_paid": 0,
      "volume": 0,
      "fee": 0,
      "reward": 2,
      "deposit": 64,
      "burned": 0,
      "is_internal": false,
      "has_data": true,
      "days_destroyed": 0,
      "data": "524288",
      "sender": "tz3NExpXn9aPNZPorRE4SdjJ2RGrfbJgMAaV",
      "branch_id": 627343,
      "branch_height": 627342,
      "branch_depth": 1,
      "branch": "BLWT4x43zqzbtRzWNShkuU1DaTjU9fX34Qs4V3Hku2ZgYxiEpPW"
    },
    // ...
  ]
}

Block and account info can be extended with an embeded list of operations. This endpoint is an optimization to fetch both the operation list and the related resource in one call. Use limit and offset (both integers) to page through operation lists. Operations are sorted by row_id in ascending order.

HTTP Request

List Block Operations

GET https://api.tzstats.com/explorer/block/{hash,height,head}/op

List Account Operations

GET https://api.tzstats.com/explorer/account/{hash}/op

Table Endpoints

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

List of supported tables

Endpoint Table Content
GET /tables/chain running blockchain totals
GET /tables/supply running supply totals
GET /tables/block blocks (including orphans)
GET /tables/op operations (only final)
GET /tables/account most recent account balances and state
GET /tables/contract smart contracts state at creation
GET /tables/flow balance, freezer and delegation flows
GET /tables/rights baking and endorsing rights
GET /tables/snapshot balances of active delegates & delegators at all snapshot blocks
GET /tables/income per-cycle statistics on baker income, efficiency, etc
GET /tables/election election metadata (i.e. entire governance cycles)
GET /tables/proposal individual proposals
GET /tables/vote voting period metadata
GET /tables/ballot ballots and proposal operations

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 who’s value is strictly greater than the filter value.
.gte= Greater than or equal. matches columns who’s value is greater than or equal to the filter value.
.lt= Less than. matches columns who’s value is strictly smaller than the filter value.
.lte= Less than or equal. matches columns who’s value is strictly smaller than or equal to the filter value.
.in= Inclusion in list. matches columns who’s value is equal to one of the filter values. Multiple values must be separated by comma.
.nin= Not included in list. matches columns who’s value is not equal to one of the filter values. Multiple values may be separated by comma.
.rg= Range. matches columns who’s 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 who’s 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"

Example response (comments added for explanation).

[
  [
    278469,             // row_id
    278469,             // delegate_id
    0,                  // manager_id
    "secp256k1",        // address_type
    360996,             // first_in
    360997,             // first_out
    633203,             // last_in
    633203,             // last_out
    360996,             // first_seen
    633203,             // last_seen
    0,                  // delegated_since
    361000,             // delegate_since
    4129917.992000,     // total_received
    1241985.094354,     // total_sent
    0.000000,           // total_burned
    0.041097,           // total_fees_paid
    488373.754858,      // total_rewards_earned
    53.292001,          // total_fees_earned
    0.000000,           // total_lost
    3029056.000000,     // frozen_deposits
    94254.999996,       // frozen_rewards
    10.405040,          // frozen_fees
    0.000000,           // unclaimed_balance
    253038.498372,      // spendable_balance
    28092993.766577,    // delegated_balance
    13,                 // total_delegations
    8,                  // active_delegations
    1,                  // is_funded
    0,                  // is_activated
    0,                  // is_vesting
    1,                  // is_spendable
    0,                  // is_delegatable
    0,                  // is_delegated
    1,                  // is_revealed
    1,                  // is_delegate
    1,                  // is_active_delegate
    0,                  // is_contract
    6165,               // blocks_baked
    41,                 // blocks_missed
    129,                // blocks_stolen
    102793,             // blocks_endorsed
    195539,             // slots_endorsed
    332,                // slots_missed
    103002,             // n_ops
    0,                  // n_ops_failed
    38,                 // n_tx
    1,                  // n_delegation
    0,                  // n_origination
    1,                  // n_proposal
    1,                  // n_ballot
    2,                  // token_gen_min
    4875,               // token_gen_max
    160,                // grace_period
    "tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m", // address
    "tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m", // delegate
    null,               // manager
    "sppk7bn9MKAWDUFwqowcxA1zJgp12yn2kEnMQJP3WmqSZ4W8WQhLqJN", // pubkey
    1553123452000,      // first_seen_time
    1570032391000,      // last_seen_time
    1553123452000,      // first_in_time
    1570032391000,      // last_in_time
    1553123512000,      // first_out_time
    0,                  // delegated_since_time
    1553123692000,      // delegate_since_time
    0,                  // rich_rank
    0,                  // flow_rank
    0                   // traffic_rank
  ]
]

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.
delegate_id uint64 Account delegate unique row_id.
manager_id uint64 Account manager unique row_id.
address_type enum Account address type ed25519 (tz1), secp256k1 (tz2), p256 (tz3), contract (KT1) or blinded (btz1)
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.
delegate_since int64 Block height of registration as delegate.
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 tz.
total_fees_paid money Lifetime fees paid in tz.
total_rewards_earned money Lifetime rewards earned in tz.
total_fees_earned money Lifetime fees earned in tz.
total_lost money Lifetime total tokens lost in tz.
frozen_deposits money Currently frozen deposits
frozen_rewards money Currently frozen rewards.
frozen_fees money Currently frozen fees.
unclaimed_balance money Currently unclaimed balance (for vesting contracts and commitments).
spendable_balance money Currently spendable balance.
delegated_balance money (baker only) Current incoming delegations.
total_delegations int64 (baker only) Lifetime count of delegations.
active_delegations int64 (baker only) Currently active and non-zero delegations.
is_funded bool Flag indicating the account is funded.
is_activated bool Flag indicating the account was activated from a commitment.
is_vesting bool Flag indicating the account is a vesting contract.
is_spendable bool Flag indicating the account balance is spendable.
is_delegatable bool Flag indicating the account is delegatable.
is_delegated bool Flag indicating the account is currently delegated.
is_revealed bool Flag indicating the account has a revealed public key .
is_delegate bool Flag indicating the account is a registered delegate.
is_active_delegate bool Flag indicating the account is a registered and active delegate.
is_contract bool Flag indicating the account is a smart contract.
blocks_baked int64 Lifetime total blocks baked.
blocks_missed int64 Lifetime total block baking missed.
blocks_stolen int64 Lifetime total block baked at priority > 0.
blocks_endorsed int64 Lifetime total blocks endorsed.
slots_endorsed int64 Lifetime total endorsemnt slots endorsed.
slots_missed int64 Lifetime total endorsemnt slots missed.
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_proposal int64 Lifetime total number of proposals (operations) sent.
n_ballot int64 Lifetime total number of ballots sent.
token_gen_min int64 Minimum generation number of all tokens owned.
token_gen_max int64 Maximum generation number of all tokens owned.
grace_period int64 (baker only) Current grace period before deactivation.
address hash Account address base58check encoded.
delegate hash Account delegate address base58check encoded.
manager hash Account manager address base58check encoded.
pubkey hash Revealed public key base58check encoded.
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.
delegate_since_time datetime Block time of registration as delegate.
rich_rank int64 Global rank on rich list by total balance.
flow_rank int64 Global rank on 24h most active accounts by transactions sent/received.
traffic_rank int64 Global rank on 24h most active accounts by volume sent/received.

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
    "testing_vote", // 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, testing_vote, testing, promotion_vote.
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.
ballot enum The actual ballot yay, nay, pass.
source hash Address of the ballot sender account, base58check encoded.
op hash Hash of the ballot operation, base58check encoded.
proposal hash Hash of the proposal that is voted on, if any.

Bigmap Table

Example request.

curl "https://api.tzstats.com/tables/bigmap?action=alloc&limit=1&order=desc"

Example response (comments added for explanation).

[
    [
        861,            // row_id
        0,              // prev_id
        343647,         // account_id
        117,            // contract_id
        16616273,       // op_id
        682374,         // height
        1573054617000,  // time
        15,             // bigmap_id
        "alloc",        // action
        "",             // key_hash
        "bytes",        // key_encoding
        "address",      // key_type
        "",             // key
        "036a",         // value
        0,              // is_replaced
        0,              // is_deleted
        0,              // is_copied
        "KT1AajLnzG5EyJSZfpSsn44iaHhwdm5AK85b", // address hash
        "oor9UypoAjKYei6miVWhxKVeBhkJV1WH3k1VvzdEBnQFmpPUMaK" // op hash
    ]
]

Lists individual bigmap update operations found in smart contract call results. Use this table to search of filter updates or efficiently access updated data. You can also use the results to reconstruct bigmap state at the client from a sequence of updates. For convenience, the current or past state of a bigmap is available as a set of explorer endpoints.

HTTP Request

GET https://api.tzstats.com/tables/bigmap?args

HTTP Response

Field Description
row_id uint64 Unique row identifier.
prev_id uint64 Unique row identifier of previous value that has been replaced by this row.
account_id uint64 Unique row_id of the account that owns the updated bigmap.
contract_id uint64 Unique row_id of the contract that owns the updated bigmap.
op_id uint64 Unique row_id of the operation that contains this update.
height int64 Height at which the update was included on-chain.
time datetime Timestamp at which the update was included on-chain.
bigmap_id int64 Unique on-chain id of the bigmap.
action enum Update action, one of alloc, update, remove, copy.
key_hash string Script expression hash of the key that was updated. Empty on alloc and copy.
key_encoding enum Michelson encoding of the key (string, bytes, int).
key_type enum Michelson type of the key.
key string 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).
value string Binary encoding of the Micheline primitives in Babylon format. Wrapped into a hex string.
is_replaced bool Flag indicating this entry has been replaced by a newer entry.
is_deleted bool Flag indicating this key has been deleted by this update.
is_copied bool Flag indicating this key has been copied by this update.
address hash Address of the bigmap owner.
op hash Operation hash where this updated appeared on-chain.

Block Table

Example request.

curl https://api.tzstats.com/tables/block?time.gte=today&limit=1

Example response (comments added for explanation).

[
  [
    632250,             // row_id
    632249,             // parent_id
    "BMapnMicyiqFsWU9NdqXvfQJQcpFfzWHMicRRjALEMNngkefd7B", // hash
    0,                  // is_orphan
    632249,             // height
    154,                // cycle
    0,                  // is_cycle_snapshot
    1569974422000,      // time
    60,                 // solvetime
    4,                  // version
    4,                  // validation_pass
    20007610,           // fitness
    0,                  // priority
    14737939769,        // nonce
    "promotion_vote",   // voting_period_kind
    35034,              // baker_id
    4294967295,         // endorsed_slots
    32,                 // n_endorsed_slots
    30,                 // n_ops
    0,                  // n_ops_failed
    0,                  // n_ops_contract
    2,                  // n_tx
    0,                  // n_activation
    0,                  // n_seed_nonce_revelation
    0,                  // n_double_baking_evidence
    0,                  // n_double_endorsement_evidence
    27,                 // n_endorsement
    0,                  // n_delegation
    1,                  // n_reveal
    0,                  // n_origination
    0,                  // n_proposal
    0,                  // n_ballot
    10529.635160,       // volume
    0.004140,           // fees
    80.000000,          // rewards
    2560.000000,        // deposits
    0.000000,           // unfrozen_fees
    0.000000,           // unfrozen_rewards
    0.000000,           // unfrozen_deposits
    0.000000,           // activated_supply
    0.000000,           // burned_supply
    31,                 // n_accounts
    0,                  // n_new_accounts
    0,                  // n_new_implicit
    0,                  // n_new_managed
    0,                  // n_new_contracts
    0,                  // n_cleared_accounts
    0,                  // n_funded_accounts
    32100,              // gas_limit
    30414,              // gas_used
    0.136,              // gas_price
    0,                  // storage_size
    58.567415,          // days_destroyed
    100,                // pct_account_reuse
    "tz1hThMBD8jQjFt78heuCnKxJnJtQo9Ao25X" // baker
  ]
]

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.
is_orphan bool Flag indicating the block is an orphan, i.e. not on main chain.
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).
validation_pass int64 Block validation pass.
fitness int64 Block fitness used to determine longest chain.
priority int64 Baking priority.
nonce uint64 Block nonce.
voting_period_kind enum Current voting period proposal, testing_vote, testing, promotion_vote.
baker_id uint64 Unique row id of the block’s baker account.
endorsed_slots uint64 32bit big-endian bitmask indicating which slots have been endorsed. (Note this field will be set from endorsements published in the subsequent block.)
n_endorsed_slots int64 Count of endorsed slots. (Note this field will be set from endorsements published in the subsequent block.)
n_ops int64 Count of operations contained in this block.
n_ops_failed int64 Count of failed operations.
n_ops_contract int64 Count of smart contract operations (transactions sent to contracts and internal operations sent by contracts).
n_tx int64 Count of transaction operations.
n_activation int64 Count of activate_account operations.
n_seed_nonce_revelation int64 Count of seed_nonce_revelation operations.
n_double_baking_evidence int64 Count of double_baking_evidence operations.
n_double_endorsement_evidence int64 Count of double_endorsement_evidence operations.
n_endorsement int64 Count of endorsement operations.
n_delegation int64 Count of delegation operations.
n_reveal int64 Count of reveal operations.
n_origination int64 Count of origination operations.
n_proposal int64 Count of proposals operations.
n_ballot int64 Count of ballot operations.
volume money Total amount of tokens moved between accounts.
fees money Total fees paid (and frozen) by all operations.
rewards money Total rewards earned (and frozen) by baker and endorsers.
deposits money Total deposits frozen by baker and endorsers.
unfrozen_fees money Total unfrozen fees (at end of a cycle).
unfrozen_rewards money Total unfrozen rewards (at end of a cycle).
unfrozen_deposits money Total unfrozen deposits (at end of a cycle).
activated_supply money Total amount of commitments activated in tz.
burned_supply money Total amount of tokens burned by operations in tz.
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_implicit int64 Count of created implicit accounts (tz1/2/3).
n_new_managed int64 Count of created managed accounts (KT1 without code or manager.tz script).
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.
gas_price float Avergae price of one gas unit in mutez.
storage_size int64 Total sum of new storage allocated by operations.
days_destroyed float Token days destroyed (tokens transfered * token idle time).
pct_account_reuse float Portion of seen accounts that existed before.
baker hash Address of the block baker account, base58check encoded.

Chain Table

Example request.

curl "https://api.tzstats.com/tables/chain?time.gte=today&limit=1"

Example response (comments added for explanation).

[
  [
    632250,         // row_id
    632249,         // height
    154,            // cycle
    1569974422000,  // time
    334414,         // total_accounts
    309308,         // total_implicit
    25074,          // total_managed
    108,            // total_contracts
    15227175,       // total_ops
    7139,           // total_contract_ops
    20774,          // total_activations
    19559,          // total_seed_nonces
    13113009,       // total_endorsements
    127,            // total_double_baking_evidences
    24,             // total_double_endorsement_evidences
    29354,          // total_delegations
    223262,         // total_reveals
    26863,          // total_originations
    1793082,        // total_transactions
    404,            // total_proposals
    725,            // total_ballots
    8747841,        // total_storage_bytes
    167308,         // total_paid_bytes
    0,              // total_used_bytes
    0,              // total_orphans
    298796,         // funded_accounts
    10751,          // unclaimed_accounts
    17567,          // total_delegators
    17105,          // active_delegators
    462,            // inactive_delegators
    3889,           // total_delegates
    483,            // active_delegates
    3406,           // inactive_delegates
    3,              // zero_delegates
    135,            // self_delegates
    78,             // single_delegates
    270,            // multi_delegates
    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_implicit int64 Total count of implicit (tz1/2/3) accounts.
total_managed int64 Total count of managed accounts (KT1) used for delegation (without code / using manager.tz script).
total_contracts int64 Total count of deployed smart contracts.
total_ops int64 Total count of on-chain operations.
total_contract_ops int64 Total count of smart contract calls (sent to or originated from contracts).
total_activations int64 Total count of activate_account operations.
total_seed_nonces int64 Total count of seed_nonce_revelation operations.
total_double_endorsement_evidences int64 Total count of endorsement operations.
total_double_baking_evidences 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_storage_bytes int64 Total count of storage bytes allocated.
total_paid_bytes int64 Total count of storage bytes paid.
total_used_bytes int64 Total count of storage used.
total_orphans int64 Total count of orphaned blocks.
funded_accounts int64 Current number of funded accounts.
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 delegate.
inactive_delegators int64 Total count of non-zero delegators who delegate to an inactive delegate.
total_delegates int64 Current number of registered bakers (active and inactive).
active_delegates int64 Current number of active bakers.
inactive_delegates int64 Current number of inactive bakers (note: inactive bakers can still have future rights, but won’t get any new rights).
zero_delegates int64 Current number of active bakers with zero staking balance.
self_delegates int64 Current number of active bakers who self-bake only and have no incoming delegations.
single_delegates int64 Current number of active bakers who potentially self-bake and have only a single incoming delegation.
multi_delegates 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.

Contract Table

Example | request.

curl "https://api.tzstats.com/tables/contract?address=KT1REHQ183LzfoVoqiDR87mCrt7CLUH1MbcV"

Example response (comments added for explanation).

[
  [
    80,          // row_id
    289810,      // account_id
    289790,      // manager_id
    438378,      // height
    0.013587,    // fee
    96082,       // gas_limit
    95982,       // gas_used
    0.142,       // gas_price
    4082,        // storage_limit
    3805,        // storage_size
    3805,        // storage_paid
    "000008b002000008...",  // script
    0,           // is_spendable
    0,           // is_delegatable
    "KT1REHQ183LzfoVoqiDR87mCrt7CLUH1MbcV", // address
    "tz1N74dH3VSeRTeKobbXUbyU82G8pqT2YYEM"  // delegate
  ]
]

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.
account_id uint64 Unique row_id of related account entry.
manager_id uint64 Manager account row_id (deprecated in v005 Babylon).
height int64 Origination block height.
fee money Fee paid on contract origination.
gas_limit int64 Gas limit on contract origination.
gas_used int64 Gas used on contract origination.
gas_price float Gas price on contract origination.
storage_limit int64 Storage limit defined on contract origination op.
storage_size int64 Storage size allocated in bytes.
storage_paid int64 Storage bytes paid for in bytes.
script bytes Binary encoded Michelson script and initial contract storage.
is_spendable bool Flag indicating the contract balance is spendable (deprecated in v005 Babylon).
is_delegatable bool Flag indicating the contract is delegatable (deprecated in v005 Babylon).
address hash Contract address base58check encoded.
delegate hash Contract delegate address base58check encoded.

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 Unqiue 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, testing_vote, testing, promotion_vote.

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
    278469,        // account_id
    31922,         // origin_id
    "secp256k1",   // address_type
    "balance",     // category
    "transaction", // operation
    2.000000,      // amount_in
    0.000000,      // amount_out
    0,             // is_fee
    0,             // is_burned
    0,             // is_frozen
    0,             // is_unfrozen
    1,             // token_gen_min
    1194,          // token_gen_max
    60,            // token_age
    "tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m", // address
    "tz1Yju7jmmsaUiG9qQLoYv35v5pHgnWoLWbt"  // origin
  ]
]

List balance updates on all sub-accounts and different categories. Our categories go beyond on-chain types and include baking, denounciations, 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.
account_id uint64 Unique row_id of the account this flow relates to.
origin_id uint64 Unique row_id of the source account that initiated the flow.
address_type enum Account address type ed25519 (tz1), secp256k1 (tz2), p256 (tz3), contract (KT1) or blinded (btz1).
category enum Flow category (i.e. sub-account) rewards, deposits, fees, balance, delegation.
operation enum Operation creating this flow activation, denounciation, transaction, origination, delegation, reveal, endorsement, baking, noncerevelation, internal, vest, pour, invoice, airdrop.
amount_in money Incoming amount in tz.
amount_out money Outgoing amount in tz.
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.
token_gen_min int64 Minimum generation number of tokens moved.
token_gen_max int64 Maximum generation number of tokens moved.
token_age float Age of tokens moved in days.
address hash Address of the related account.
origin hash Address of the flow initiating account.

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
    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
    0,                // n_blocks_lost
    2,                // n_blocks_stolen
    6507,             // n_slots_endorsed
    0,                // n_slots_missed
    15,               // n_seeds_revealed
    16198.000000,     // expected_income
    518336.000000,    // expected_bonds
    16176.875000,     // total_income
    519360.000000,    // total_bonds
    3216.000000,      // baking_income
    12959.000000,     // endorsing_income
    0.000000,         // double_baking_income
    0.000000,         // double_endorsing_income
    1.875000,         // seed_income
    1.680381,         // fees_income
    0.000000,         // missed_baking_income
    0.000000,         // missed_endorsing_income
    32.000000,        // stolen_baking_income
    0.000000,         // total_lost
    0.000000,         // lost_accusation_fees
    0.000000,         // lost_accusation_rewards
    0.000000,         // lost_accusation_deposits
    0.000000,         // lost_revelation_fees
    0.000000,         // lost_revelation_rewards
    "tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m"  // address
  ]
]

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).
balance money Staking balance (at snapshot block).
delegated money Delegated balance (at snapshot block).
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 denounciations. 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.
n_blocks_lost int64 Number of blocks lost in this cycle.
n_blocks_stolen int64 Number of blocks stolen in this cycle.
n_slots_endorsed int64 Number of slots endorsed in this cycle.
n_slots_missed int64 Number of endorsement slots missed 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.
expected_bonds money Total expected deposits 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_bonds 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.
double_baking_income money Total income from denouncing double baking.
double_endorsing_income money Total income from denouncing double endorsing.
seed_income money Total income from publishing seed nonces.
fees_income money Total income from fees.
missed_baking_income money Missed income from lost blocks.
missed_endorsing_income money Missed income due to missed endorsements.
stolen_baking_income money Extra income from stolen blocks.
total_lost money Total lost income due to denounciations or unpublished seed nonces. NOTE: This does not automatically reduce total_income above.
lost_accusation_fees money Lost fees due to a denounciation.
lost_accusation_rewards money Lost rewards due to a denounciation.
lost_accusation_deposits money Lost income due to a denounciation.
lost_revelation_fees money Lost fees due to an unpublished seed nonce.
lost_revelation_rewards money Lost block rewards due to an unpublished seed nonce.
address hash Account address base58check encoded.

Operation Table

Example request.

curl "https://api.tzstats.com/tables/op?time.gte=today&limit=1"

Example response (comments added for explanation).

[
  [
    16848289,         // row_id
    1573516812000,    // time
    689942,           // height
    168,              // cycle
    "opGz2Sg1QiXchJMyz9v1rV9VN7mQadmkL81KVwteANQWZpgV5ew", // hash
    0,                // counter
    0,                // op_n
    0,                // op_c
    0,                // op_i
    "endorsement",    // type
    "applied",        // status
    1,                // is_success
    0,                // is_contract
    0,                // gas_limit
    0,                // gas_used
    0.000,            // gas_price
    0,                // storage_limit
    0,                // storage_size
    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,                // manager_id
    0,                // delegate_id
    0,                // is_internal
    1,                // has_data
    "128",            // data
    null,             // parameters
    null,             // storage
    null,             // big_map_diff
    null,             // errors
    0,                // days_destroyed
    689942,           // branch_id
    689941,           // branch_height
    1,                // branch_depth
    "tz1Z2jXfEXL7dXhs6bsLmyLFLfmAkXBzA9WE",  // sender
    null,             // receiver
    null,             // manager
    null              // delegate
  ]
]

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.
time datetime Block time at which the operation was included on-chain.
height int64 Block height.
cycle int64 Cycle in which the operation was included on-chain.
hash hash Operation hash.
counter int64 Unique sender account ‘nonce’ value.
op_n int64 Operation position in block. (Tezos defines 4 arrays used for the different op verification steps. The op_n value represents the global operation position across all these arrays.)
op_c int64 Bulk operation list position.
op_i int64 Internal operation list position.
type enum Operation type, one of activate_account, double_baking_evidence, double_endorsement_evidence, seed_nonce_revelation, transaction, origination, delegation, reveal, endorsement, proposals, ballot.
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.
gas_limit int64 Caller-defined gas limit.
gas_used int64 Gas used by the operation.
gas_price float Effective price per gas unit in mutez.
storage_limit int64 Caller-defined storage limit.
storage_size int64 Actual storage size allocated.
storage_paid int64 Part of the storage the operation paid for.
volume money Amount of tokens transferred in tz.
fee money Fees paid in tz.
reward money Rewards earned in tz.
deposit money Amount of deposited tokens in tz.
burned money Amount of burned tokens in tz.
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.
delegate_id uint64 Unique row id of the new delegate account, may be zero.
is_internal bool Flag indicating if this operation was sent be a smart contract.
has_data bool Flag indicating if extra data or parameters are present.
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 bytes Updated contract storage as hex-encoded binary data serialized according to Micheline serialization for protocol v005 Babylon, contract-only.
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 transfered * token idle time).
branch_id uint64 Row id of the branch block this op refers to.
branch_height int64 Height of the branch block this op refers to.
branch_depth int64 Count of blocks between branch block and block including this op.
sender hash Address of the operation sender, always set.
receiver hash Address of the receiver of a transaction, may be empty.
manager hash Address of the new contract manager account, may be empty.
delegate hash Address of the new delegate account, may be empty.

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
    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.
voters int64 Number of voters who voted for this proposal in the proposal period.
source hash Address of the sender account, base58check encoded.
op hash Hash of the proposal operation, base58check encoded.

Rights Table

Example request.

curl "https://api.tzstats.com/tables/rights?address=tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m&cycle=154&limit=1"

Example response (comments added for explanation).

[
  [
    60555268,     // row_id
    "baking",     // type
    630785,       // height
    154,          // cycle
    3,            // priority
    278469,       // account_id
    0,            // is_lost
    0,            // is_stolen
    0,            // is_missed
    0,            // is_seed_required
    0,            // is_seed_revealed
    "tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m", // address
    1569885537000 // time
  ]
]

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.
type enum Right type, either baking or endorsing.
height int64 Block height this right relates to.
cycle int64 Cycle this right relates to.
priority int64 Baking priority of this right.
account_id uint64 Unique row_id of the baker who owns this right.
is_lost bool Flag indicating a baking right was lost to another baker. This flag appears when a baker fails to produce a block at the designated priority and another baker bakes the block at higher priority.
is_stolen bool Flag indicating a baking right was stolen from another baker. This flag appears on the right relating to the actual baking priority.
is_missed bool Flag indicating an endorser missed endorsing a slot.
is_seed_required bool Flag indicating a baker is required to publish a seed_nonce_revelation in the next cycle.
is_seed_revealed bool Flag indicating whether the baker actualy revealed the required seed nonce.
address hash Address of the baker who owns this right.
time datetime Past or estimated future block time for this right.

Snapshot Table

Example request.

curl "https://api.tzstats.com/tables/snapshot?address=tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m&cycle=150&is_selected=1&limit=1"

Example response (comments added for explanation).

[
  [
    25384634,         // row_id
    616960,           // height
    150,              // cycle
    1,                // is_selected
    1569042994000,    // time
    9,                // index
    3915,             // rolls
    278469,           // account_id
    278469,           // delegate_id
    1,                // is_delegate
    1,                // is_active
    3216395.662038,   // balance
    28104896.167331,  // delegated
    7,                // n_delegations
    361000,           // since
    "tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m", // address
    "tz2TSvNTh2epDMhZHrw73nV9piBX7kLZ9K9m", // delegate
    1553123692000     // since_time
  ]
]

List network-wide staking status across all bakers and delegators at snapshot blocks. this table contains all snapshots regardless of them beeing later chosen as cycle snapshot or not.

HTTP Request

GET https://api.tzstats.com/tables/snaphsot?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 delegate.
account_id uint64 Unique row_id of the account this snapshot relates to.
delegate_id uint64 Unique row_id of the baker this account delegates to.
is_delegate 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.
delegate 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).

[
  [
    632250,             // row_id
    632249,             // height
    154,                // cycle
    1569974422000,      // time
    811171614.329775,   // total
    527007757.439372,   // activated
    84447120.970808,    // unclaimed
    27582743.428170,    // vested
    125280976.174350,   // unvested
    543541320.887682,   // circulating
    457526565.844116,   // delegated
    581437025.036545,   // staking
    456454601.645863,   // active_delegated
    578069662.395001,   // active_staking
    1071964.198253,     // inactive_delegated
    3367362.641544,     // inactive_staking
    47009247.412181,    // minted
    9779155.106655,     // minted_baking
    37227647.430526,    // minted_endorsing
    2444.875000,        // minted_seeding
    100,                // minted_airdrop
    156231.095106,      // burned
    103509.825621,      // burned_double_baking
    31838.219485,       // burned_double_endorse
    6599.299000,        // burned_origination
    14283.751000,       // burned_implicit
    0,                  // burned_seed_miss
    57902196.296935,    // frozen
    56149246.000000,    // frozen_deposits
    1752733.604963,     // frozen_rewards
    216.691972          // frozen_fees
  ]
]

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 Acitivated fundraiser supply.
unclaimed money Unclaimed fundraiser supply.
vested money Vested genesis supply, i.e. spendable supply owned by vesting contracts.
unvested money Unvested genesis supply, i.e. supply that is still locked in vesting contracts.
circulating money Circulating supply, i.e. all immediatly spendable supply.
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.
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).
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_implicit money Total supply burned due to implicit account creation.
burned_seed_miss money Total supply burned due to implicit account creation.
frozen money Currently frozen supply.
frozen_deposits money Currently frozen bonds.
frozen_rewards money Currently frozen rewards.
frozen_fees money Currently frozen fees.

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
    "testing_vote",    // voting_period_kind
    1565333282000,     // period_start_time
    1565333282000,     // period_end_time
    557056,            // period_start_block
    589823,            // period_end_block
    70585,             // eligible_rolls
    464,               // eligible_voters
    7291,              // quorum_pct
    51463,             // quorum_rolls
    57818,             // turnout_rolls
    179,               // turnout_voters
    8191,              // turnout_pct
    0,                 // turnout_ema
    37144,             // yay_rolls
    171,               // yay_voters
    0,                 // nay_rolls
    0,                 // nay_voters
    20674,             // pass_rolls
    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, testing_vote, testing, promotion_vote.
period_start_time datetime Block time of vote start block.
period_end_time datetime Block time of vote end block.
period_start_block int64 Block height of vote start block.
period_end_block int64 Block height of vote end block.
eligible_rolls int64 Number of eligible rolls 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.
turnout_rolls int64 Actual vote participation in rolls.
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_voters int64 Count of yay voting voters.
nay_rolls int64 Count of nay voting rolls.
nay_voters int64 Count of nay voting voters.
pass_rolls int64 Count of pass voting rolls.
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 submotted 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 Endpoints

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.

List of supported time-series

Endpoint Time-Series Content
GET /series/block aggregated block data
GET /series/flow aggregated balances, freezer and delegation flows
GET /series/op aggregated operations data
GET /series/{exchange}/{market}/ohlcv OHLCV candles

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, 3Mand 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.

Block Series

Example request.

curl "https://api.tzstats.com/series/block.json?start_date=today&collapse=1d"

Example response.

[
  [
    1570060800000,      // time
    25002,              // n_ops
    6,                  // n_ops_failed
    2,                  // n_ops_contract
    674,                // n_tx
    2,                  // n_activation
    0,                  // n_seed_nonce_revelation
    0,                  // n_double_baking_evidence
    0,                  // n_double_endorsement_evidence
    24188,              // n_endorsement
    19,                 // n_delegation
    95,                 // n_reveal
    18,                 // n_origination
    0,                  // n_proposal
    6,                  // n_ballot
    1489819.569887,     // volume
    2.223532,           // fees
    79822.000000,       // rewards
    2565504.000000,     // deposits
    0.000000,           // unfrozen_fees
    0.000000,           // unfrozen_rewards
    0.000000,           // unfrozen_deposits
    8522.749680,        // activated_supply
    42.148000,          // burned_supply
    152,                // n_new_accounts
    134,                // n_new_implicit
    18,                 // n_new_managed
    0,                  // n_new_contracts
    46,                 // n_cleared_accounts
    164,                // n_funded_accounts
    8167612,            // gas_used
    214,                // storage_size
    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.
n_ops int Count of all operations.
n_ops_failed int Count of failed operations.
n_ops_contract int Count of smart-contract operations.
n_tx int Count of transaction operations.
n_activation int Count of activate_account operations.
n_seed_nonce_revelation int Count of seed_nonce_revelation operations.
n_double_baking_evidence int Count of double_baking_evidence operations.
n_double_endorsement_evidence int Count of double_endorsement_evidence operations.
n_endorsement int Count of endorsement operations.
n_delegation int Count of delegation operations.
n_reveal int Count of reveal operations.
n_origination int Count of origination operations.
n_proposal int Count of proposals operations.
n_ballot int Count of ballot operations.
volume int Count of amount of tokens moved between accounts.
fees float Total fees paid (and frozen) by all operations.
rewards float Total rewards earned (and frozen) by baker and endorsers.
deposits float Total deposits frozen by baker and endorsers.
unfrozen_fees float Total unfrozen fees (at end of a cycle).
unfrozen_rewards float Total unfrozen rewards (at end of a cycle).
unfrozen_deposits float Total unfrozen deposits (at end of a cycle).
activated_supply float Total amount of commitments activated in tz.
burned_supply float Total amount of tokens burned by operations in tz.
n_new_accounts int Count of new accounts created regardless of type.
n_new_implicit int Count of created implicit accounts (tz1/2/3).
n_new_managed int Count of created managed accounts (KT1 without code or manager.tz script).
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_size 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
  ]
]

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.

In 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 tz.
amount_out float Outgoing amount during interval in tz.

Operation Series

Example request.

curl "https://api.tzstats.com/series/op?start_date=today&collapse=1d"

Example response.

[
  [
    1570060800000,      // time
    8187812,            // gas_used
    214,                // storage_size
    0,                  // storage_paid
    1493221.154887,     // volume
    2.228532,           // fee
    63790.000000,       // reward
    2052480.000000,     // deposit
    42.148000,          // burned
    17867317.80054702   // days_destroyed
  ]
]

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_size int Total storage size allocated by all operations.
storage_paid int Total storage paid by all operations.
volume float Total amount of tokens transferred by all operations in tz.
fee float Fees paid by all operation in tz.
reward float Rewards earned in by all operation tz.
deposit float Amount of deposited tokens by all operation in tz.
burned float Amount of burned tokens by all operation in tz.
days_destroyed float Total token days destroyed by all operation.

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.

2019-11-14

2019-11-01

2019-10-26

2019-10-24

2019-10-20