General
The TzPro API provides flexible and efficient access to all historic on-chain data and advanced statistics collected from the Tezos blockchain. This API reference contains information on all TzPro API endpoints, explains how to call them and how to read the results.
Mainnet: https://api.tzpro.io
Staging: https://stage.tzpro.io
Ghostnet: https://api.ghost.tzpro.io
Mainnet: https://rpc.tzpro.io
Ghostnet: https://rpc.ghost.tzpro.io
TzPro API Overview
The TzPro API is with a few exceptions read-only and supports HTTP methods
GET
, HEAD
and OPTIONS
. Most endpoints take optional query parameters which must be properly URL encoded. The TzPro API exclusively uses TLS encrypted connections. All our certificates are signed by LetsEncrypt Authority X3 certificate. The API supports secure connections via TLS v1.3 and v1.2 with Perfect Forward Secrecy based on Elliptic Curves and Diffie-Hellman key exchange. Insecure HTTP requests to port 80 are automatically redirected to HTTPS on port 443.
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
All our API responses contain HTTP response headers with an API version, call runtime and request id headers to aid debugging, headers to identify the Tezos network and protocol as well as rate limit headers for unprivileged requests.
# API version
X-Api-Version: v015-2022-12-06
# Tezos Network (chain id)
X-Network-Id: NetXdQprcVkpaWU
# Tezos Block Height
X-Chain-Height: 2968198
# Tezos Protocol (protocol hash)
X-Protocol-Hash: PtKathmankSpLLDALzWw7CGD2j2MtyveTwboEYokqUCP4a1LxMg
# Unique request identifier
X-Request-Id: db4cf7d9-7a24-45d6-b37d-ac2fdab6e17c
# Backend runtime
X-Runtime: 0.000131
# Rate limit information
X-Rate-Limit-Group: M
X-Rate-Limit-Limit: 10000
X-Rate-Limit-Remaining: 9994
X-Rate-Limit-Reset: 1638021248
The TzPro API supports cross-origin HTTP requests, commonly referred to as CORS. This means that you can call the API using Javascript from any browser. CORS support is automatically activated on your TzPro API key. You can optionally whitelist your domain with your API key via your TzPro account dashboard.
Our free API plan includes 10,000 calls per month per API key or domain. Paid plans allow unlimited access unless you optionally set a voluntary call limit for cost control reasons. If a rate limit is active, we include limit response headers to inform about its status. Learn more about available plans and pricing on the tzpro.io website and manage your subscription on your TzPro account dashboard.
CSV files always include a header containing the requested column names in the requested order. Columns are separated by comma (ASCII 44, UTF-8 0x2C).
When downloading a CSV file you may add an optional
filename
query argument (ASCII only, 128 characters max, no path separators) which will be used in the Content-Disposition header. Filename suffix .csv
is automatically appended if missing.Results on Table and Time Series APIs use an optimized JSON array format that omits objects and their keys to save bandwidth and time. The outer array contains result rows or time points, the inner arrays represent result columns in the order requested by the
columns
query parameter.[
[
"BMRdcMqU63QiXmU8vLE7a2qBES1kRX46mTDEGYEUsFV8uL4PDkd",
"tz1isXamBXpTUgbByQ6gXgZQg4GWNW7r6rKE",
626160,
152
],[
"BLhhgCSR8Avhbc7hrqQ9uSsB9Adfts2NwqZbzrGS5VCjxQdLX5N",
"tz1coHzgoQYRu1Ezn5QChfFEjwTrBzGNQT6U",
626159,
152
],[
"BLPUNqkikFAbNDekUhiqJrCaao86o6sPNq5YrcGobHMzSPi4XWr",
"tz1XfAjZyaLdceHnZxbMYop7g7kWKPut4PR7",
626158,
152
]
]
Note: As we keep adding new fields to tables and time-series the default order of JSON bulk arrays may change over time. Use the
columns
query argument to ensure the API always returns the expected fields in the specified order.We use the following data types and encoding conventions throughout the API:
string | unstructured ASCII/UTF-8 text |
bytes | binary data encoded as hex string |
datetime | UTC timestamps as UNIX milliseconds, e.g. 1536246000000 or ISO 8601/RFC3339 strings 2018-09-06T15:00:00Z |
duration | signed 64bit integers with second precision |
boolean | a binary value, either as string or number true (1) or false (0) |
float64 | an IEEE-754 64-bit floating-point number |
int64 | a signed 64-bit integer (Range: -9,223,372,036,854,775,807 through 9,223,372,036,854,775,807) |
uint64 | an unsigned 64-bit integer (Range: 0 through 18,446,744,073,709,551,615) |
enum | enumerable values expressed as strings, usually used for types |
hash | on-chain hashes encoded as base58-check strings |
money | monetary quantities are expressed as float64 with 6 decimal points (the Tezos coin unit precision); market endpoints use 5 or more decimal points depending on the fiat or crypto pairs |
For efficiency reasons, timestamps in JSON arrays are encoded as UNIX time at millisecond resolution. That is, value
0
represents Jan 1, 1970 00:00:00 UTC
. Timestamps in explorer responses and CSV output are encoded according to RFC 3339 (2018-09-06T08:07:38Z
) for convenience and human readability.Timestamps in queries can be expressed in multiple ways:
- as RFC3339 string with any timezone
- as UNIX timestamp in seconds or milliseconds, so
1536246000
and1536246000000
are equal - as date without time, i.e.
2018
,2018-09
,2018-09-06
represents midnight at the first day of month and/or month of year - as static string such as
now
,today
, oryesterday
to reference a relative point in time - as static string expression with truncation and offset arguments against
now
, eg.now/d
for start of today ornow/d-30d
for start of day 30 days ago (expressions supports
,m
,h
,d
)
The TzPro API responds with regular HTTP status codes in the
2xx
range to indicate success, in the 4xx
range to indicate client-side errors and in the 5xx
range to indicate backend errors. The response body contains additional information encoded as JSON object.200 OK
Success400 Bad Request
Missing required fields of malformed request data, your fault404 Not Found
No such object (block, operation or account has not yet been included in a finalized block)405 Method Not Allowed
Unsupported request method409 Conflict
Resource state conflict, may happen after reorgs when using a stale block hash as anchor429 Too Many Requests
Request limit exceeded500 Internal Server
Something went wrong on our end, not your fault502 Bad Gateway
Our backend is overloaded or down for maintenance, wait a while before retry503 Service Unavailable
Our backend is overloaded or down for maintenance, wait a while before retry504 Gateway Timeout
Your request has reached a timeout and was canceled, try to reduce limit or time range in your request
{
"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. |
Last modified 4d ago