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.

TzPro API URLs

Mainnet: https://api.tzpro.io
Staging: https://stage.tzpro.io
Ghostnet: https://api.ghost.tzpro.io

TzPro Tezos RPC Endpoints

Mainnet: https://rpc.tzpro.io
Ghostnet: https://rpc.ghost.tzpro.io
TzPro API Overview
  • explorer – current and historic on-chain data and statistics
  • tables – raw data access for bulk analytics on very large quantities of data
  • series – aggregate statistics for charting and reporting
  • metadata – curated off-chain and on-chain address labels and smart contract metadata
  • markets – off-chain Tezos fiat and crypto pairs and on-chain asset prices
  • events – real-time operations, account updates and market tickers over WebSocket and SSE

Calling the TzPro API

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.

Transport Security

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.

Available ciphers

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

Response Headers

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.

Current TzPro Mainnet Response Headers

# 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

CORS

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.

Rate Limits

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.

Data Formats

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. Without suffix, JSON is default.
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.

Compact JSON Arrays

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.

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 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 and 1536246000000 are equal
  • as date without time, i.e. 2018, 2018-09, 2018-09-06 represents midnight at the first day of month and/or month of year
  • as static string such as now, today, or yesterday to reference a relative point in time
  • as static string expression with truncation and offset arguments against now, eg. now/d for start of today or now/d-30d for start of day 30 days ago (expressions support s, m, h, d)

Status Codes

The 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 Success
  • 400 Bad Request Missing required fields of malformed request data, your fault
  • 404 Not Found No such object (block, operation or account has not yet been included in a finalized block)
  • 405 Method Not Allowed Unsupported request method
  • 409 Conflict Resource state conflict, may happen after reorgs when using a stale block hash as anchor
  • 429 Too Many Requests Request limit exceeded
  • 500 Internal Server Something went wrong on our end, not your fault
  • 502 Bad Gateway Our backend is overloaded or down for maintenance, wait a while before retry
  • 503 Service Unavailable Our backend is overloaded or down for maintenance, wait a while before retry
  • 504 Gateway Timeout Your request has reached a timeout and was canceled, try to reduce limit or time range in your request

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.