Introduction

Current Network Endpoints

Mainnet Network: mainnet
Conseil Indexer: https://indexer-mainnet.ateza.io
Tezos Node: https://rpc-mainnet.ateza.io

Testnet One Network: jakartanet
Conseil Indexer: https://indexer-testnet-one.ateza.io
Tezos Node: https://rpc-testnet-one.ateza.io

Testnet Two Network: jakartanet
Conseil Indexer: https://indexer-testnet-two.ateza.io
Tezos Node: https://rpc-testnet-two.ateza.io

Current Software Version

Mainnet:
Tezos node: v13.0
Conseil indexer: build 42b1148

Testnet One:
Tezos node: v13.0
Conseil indexer: build 42b1148

Testnet Two:
Tezos node: v13.0
Conseil indexer: build 42b1148

This application programming interface (API) provides free, reliable access to a load-balanced Tezos archive node and Conseil indexer. The API strictly utilizes open-source software and does not require a license for commercial use. The API utilizes both global and regional load balancers with end-to-end encryption. The API does not require an API key. API requests are rate limited using the client's IP address. An API key can be provided upon request to increase one's rate limit.

The API supports three networks:

1. Mainnet
2. Testnet One
3. Testnet Two

For each network, there are two API services:

1. Remote Procedure Calls (RPC) to an archive Tezos node
2. Conseil indexer.

ATEZA is grant recipient from the Tezos Foundation. All development and maintenance costs are paid by this grant in addition to personal time and effort.

About

The architecture of the API consists of two load balancers in series: 1) Global Load Balancer and 2) Regional Load Balancer. The global load balancer (LB) redirects client requests to the nearest regional LB for a given client. The regional LB will then either serve the request from cache or forward the request to an upstream indexer or RPC service. See below diagram for an illustration of the architecture.

Regional Load Balancers

The regional LBs are connected through a virtual private network in a hub and spoke topology utilizing Kong Gateway and WireGuard. The regional LBs synchronize approximately every thirty seconds, however, to minimize downtime the regional LBs will operate independently in the advent of network failure. The regional LBs are monitored to ensure uptime and, in the advent of failure, the global LB will redirect API requests to the nearest available regional LB for a given client's location

Regional Load Balancer Locations

• Frankfurt, Germany
• Iowa, United States
• São Paulo, Brazil
• Singapore

Indexer and Tezos Nodes

The API currently consists of six Tezos mainnet archive nodes (2 of which are backup nodes), four mainnet Conseil indexers, two Tezos testnet archive nodes, and two Tezos testnet Conseil indexers. Each regional LB is connected to every Tezos node and Conseil indexer. Regional LBs primarily forward requests to the Tezos node and/or indexer with the lowest latency. Regional LBs will, however, automatically load-balance requests to the other Tezos nodes and Conseil indexers in the setting of high demand or if the nearest Tezos node and/or indexer is unavailable.

Tezos Node and Conseil Indexer Locations

• Frankfurt, Germany
• Iowa, United States
• Dallas, United States
• São Paulo, Brazil
• Singapore

Hardware Specifications

Each Conseil indexer and Tezos node runs on a virtual machine with the following hardware specifications:

• 4 CPU Cores
• 32 GB of RAM
• 4 NVME SSDs RAID 0

Health Checks

This API performs frequent, automatic health checks on the regional LB, the upstream virtual machines, and on the Conseil indexer and the Tezos node itself. If a particular regional LB is down, a client's request will be routed to the next available regional LB with the lowest latency. The regional LB also performs frequent health checks on the upstream API services to ensure availability of the Conseil indexer and the Remote Procedure Call (RPC) service. Finally, an internal health check is performed between the Conseil indexer and the Tezos node on every virtual machine to ensure the Conseil indexer is in sync with a properly bootstrapped Tezos archive node. If a particular Tezos node and/or Conseil indexer are not bootstrapped, not in sync, and/or busy processing prior requests, the regional LB will automatically load-balance requests to other available Tezos nodes and/or Conseil indexers.

Monitoring

The status of the upstream services (RPC and Indexer) and total traffic for each regional LB can be monitored below.

• Regional LB Service Status
• Regional LB Total Traffic

Update Policy

The Conseil indexer and Tezos node will be assessed and updated on a regular monthly basis or sooner subject to Tezos protocol upgrades.

Terms

This API is free for all personal, research, educational, and commercial use cases. ATEZA does not currently offer technical support aside from the documentation posted on this site. While ATEZA is designed to be a reliable API service with minimal downtown, the user assumes all technical risks.

If your application or service utilizes the ATEZA API either directly on a front-end or indirectly on a back-end, we ask that you kindly give attribution on your website or application by placing a label stating "Powered by ATEZA" with a direct link to https://ateza.io.

Service Level Agreement

Plain English

Effective: July 1, 2021

ATEZA aims to provide 99.9% uptime of the application programming interface (API) for all users. Since we are providing the API as a free service, we will not be held responsible nor will we compensate users due to damage or harm, financial or otherwise, caused by technical, performance, or other downtime related problems due to our API. The ATEZA API is a free service, provided “AS-IS”.

Downtime

Downtime is defined as the number of minutes the entire, global mainnet API was unavailable for a given month. ATEZA monitors the API continuously using a combination of standard server monitoring tools and custom developed software. Please see the section on Health Checks for more information.

Downtime excludes the following:

• Performance problems
• Testnet networks
• Scheduled downtime for maintenance

Uptime

Uptime is defined as the percentage of total possible minutes the API was available for a given month. Our goal is to maintain at least 99.9% uptime defined as the following:

[(total minutes in a month – Downtime)/total minutes in a month] > 99.9%

Scheduled Downtime

All attempts to perform maintenance on the API will primarily be accomplished on each regional LB individually whenever possible to minimize the risk of downtime. If a regional LB is down in your geographic region due to maintenance, you may exhibit a slight increase in latency as your traffic will be routed to the next nearest regional LB. While we will do our best to perform maintenance on individual regional load balancers, there may be unforeseen occasions where our entire global API might be down.

Recovery Time Objective

The API was designed for maximum uptime due to the redundancy of various geographically placed regional load-balancers each running on different datacenters. We perform periodic monthly backups of our archive Tezos nodes, Conseil indexer database, and the Kong API datastore which can be used to restore our infrastructure. In addition, we also run backup archive Tezos nodes. In the rare case of total failure of our API, our objective is to restore the API within 48 hours.

Updates

We may update our Service Level Agreement as our business model evolves. Rest assured, our primary goal will always be to provide a free, basic service to all users. However, subject to commercial demand, we may consider creating a more premium service package with a more stringent Service Level Agreement. Users can review the most current version of our Service Level Agreement by visiting this page.

API

The API provides access to three networks: mainnet, testnet one, and testnet two. Each network provides access to two different services:

1. Remote Procedure Calls (RPC)
2. Conseil indexer

Requests

Example - API Response (application/json)

curl -X GET 'https://indexer-mainnet.ateza.io/v2/data/tezos/mainnet/blocks/head' \
-H 'accept: application/json' | jq

{
  "level": 1500131,
  "proto": 9,
  "predecessor": "BLomLQbcrXUrHEfHXGxZemsG5tBompcaNM5KtaTffw7tDhryGWu",
  "timestamp": 1622762722000,
  "fitness": "01,00000000000ce3e3",
  "context": "CoVZKip7KHC9ryoAbHbQCSeRd6aWySSNYxhFS4vbWPtNcnr7GMu1",
  "signature": "sigWR1ok1LgYqnzhfom9KjMemw1YjMSHsJvfRTjxH8BuEn9x4XR444xUBJJiKAxwJkojso6fDZWL5c6SxDneG4xDTzU46iEC",
  "protocol": "PsFLorenaUUuikDWvMDr6fGBRG8kt3e3D3fHoXK1j1BFRxeSH4i",
  "chainId": "NetXdQprcVkpaWU",
  "hash": "BLjuAS2GD5wEMQHU9UHqZx9vcA5nP5ZLtGrvojmP4sCjPbAxXzF",
  "operationsHash": "LLoaP84ztx8jsgZNToPoJSjQsYZFFBXM5twjGkgJSqDJ5zWL2GLCD",
  "periodKind": "proposal",
  "currentExpectedQuorum": 5326,
  "baker": "tz3gtoUxdudfBRcNY7iVdKPHCYYX6xdPpoRS",
  ...
}

All requests and responses are application/json content type and follow typical HTTP response status codes for success and failure. Please see example on the right for a simple request.

Encryption

Supported TLS Protocols and Cipher Suites

Protocols: TLS 1.2, TLS 1.3
Cipher suites (TLS 1.3): TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256
Cipher suites (TLS 1.2): ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:
ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384

The endpoints use HTTPS at the default port 443. All traffic is encrypted end-to-end and goes directly to our servers. HTTP is not supported nor recommended. Our certificates are signed by LetsEncrypt Authority X3 certificate. Our configuration mirrors Mozilla's section on intermediate compatibility.

Endpoints

Example - Request the head block hash from the indexer on the mainnet network

curl -X GET 'https://indexer-mainnet.ateza.io/v2/data/tezos/mainnet/blocks/head' \
-H 'accept: application/json' | jq '.hash'

"BMGziAF2KrNVoY2rMpGhs7c63eTvxybKkAG8BSYM2jNZV7uNKuD"

Example - Request the head block hash from the Tezos node on the mainnet network

curl -X GET 'https://rpc-mainnet.ateza.io/chains/main/blocks/head/hash' \
-H 'accept: application/json' | jq

"BLYxrZPYyYUUvMGi3AsE693QuFhLBRQuY9ofT5XEz97TWzzwLJ5"

Each network has a corresponding endpoint for the indexer and RPC service. Current supported testnets can be found at the introduction section of this documentation or at api.ateza.io.

Endpoint Syntax

<service>-<network>.ateza.io

Mainnet

https://indexer-mainnet.ateza.io

https://rpc-mainnet.ateza.io

Testnet-one

https://indexer-testnet-one.ateza.io

https://rpc-testnet-one.ateza.io

Testnet-two

https://indexer-testnet-two.ateza.io

https://rpc-testnet-two.ateza.io

Rate Limits

Rate limits are shown by the following response headers

curl -X GET 'https://rpc-mainnet.ateza.io/chains/main/blocks/head/hash' \
-H 'accept: application/json' -i

x-ratelimit-remaining-second: 29
x-ratelimit-remaining-minute: 898
x-ratelimit-remaining-hour: 24998
x-ratelimit-remaining-day: 99998
ratelimit-reset: 1
x-ratelimit-limit-second: 30
x-ratelimit-limit-minute: 900
x-ratelimit-limit-hour: 25000
x-ratelimit-limit-day: 100000
ratelimit-remaining: 29
ratelimit-limit: 30
...

Rate limits for anonymous API requests (i.e., no provided API key) are limited per IP address. Default IP address rate limits are the following:

Burst rate: 30 requests/second

Average allowed rate: 15 requests/second

Max allowed rate: 300,000 requests/day

Rate limits for clients using an API key are determined by the API key and not the IP address. Please contact us via email at [email protected] to request an API key.

Authentication

API Keys need to be passed as a header.

curl -X GET 'https://rpc-testnet-two.ateza.io/chains/main/blocks/head/hash' \
 --header 'apiKey: <key>'

Don't forget to replace <key> with your API key.

To access the API using an API key, please provide the API key as a header labeled apiKey as per the example on the right. An API key can be requested via email at [email protected] Please explain to us your use case and the desired rate limits (i.e., burst rate per second, average rate per second, max rate per day). We will make all attempts to approve reasonable requests.

To verify that you entered the correct API Key, please check the response header rate limits as per the above example under "Rate Limits."

For example, the following command:

curl https://rpc-mainnet.ateza.io/chains/main/blocks/head/hash -i --header 'apiKey: <key>'

will return x-ratelimit headers specific to that API Key.

Caching

Header responses indicate if the request was found in cache

x-cache-status: Hit
x-cache-status: Refresh
x-cache-status: Miss

Header response indicate the "age" of data in cache (seconds)

x-cache-status: Hit
age: 3

Regional load balancers cache both the indexer and RPC requests for all networks. The current set cache period is the following:

Cache TTL: 5 seconds

Success

A successful response is indicated by a HTTP status code 2XX and will generally return a message body.

Errors

Incorrect Path

curl -X GET 'https://rpc-mainnet.ateza.io/chains/main/blocks/head/hashs' \
-H 'accept: application/json' -i

HTTP/2 404

Non-permitted Path

curl -X GET 'https://rpc-mainnet.ateza.io/stats/memory' \
-H 'accept: application/json' -i

HTTP/2 404
x-frame-options: DENY

Rate Limit Exceeded

curl -X GET https://rpc-mainnet.ateza.io/chains/main/blocks/head/hash \
-H 'accept: application/json' -i

HTTP/2 429
{
  "message":"API rate limit exceeded"
}

Unless otherwise stated, errors to bad requests will respond with an HTTP 4xx/5xx status code. The response header may contain a message parameter indicating the cause. Common error codes include the following:

Attempts to access a non-permitted path will return an HTTP Status Code 404 with the following response header: x-frame-options: DENY. If you receive an HTTP Status Code 404 without this response header, it is likely you have entered an incorrect path (i.e., a typo). Please see section on RPC paths for more details.

Conseil Indexer Service

About

The indexer API service is powered by Conseil, an open-source REST API indexer developed by Cryptonomic. An overview of the Conseil indexer and API specification can be found at the following:

• Cryptonomic Indexer Overview
• OpenAPI Specification

When using the OpenAPI Specification above, enter mainnet for the <network> parameter. Again, an API key is not necessary.

Below are some examples on how to use the indexer service to help you get started.

Indexer Example #1

Example - Obtain the header of the head block

curl -X GET 'https://indexer-mainnet.ateza.io/v2/data/tezos/mainnet/blocks/head' \
-H 'accept: application/json' | jq

{
  "level": 1504094,
  "proto": 9,
  "predecessor": "BLbppmUquFCCgdLhgqvU4xvkV4TqixjxZ58T1FtCWt6mpfL2dkD",
  "timestamp": 1623003702000,
  "fitness": "01,00000000000cf35e",
  "context": "CoVA1zRYvq5Am2y3uahGDyxsGpHoyKLdqDgrBpAssmdrnkXm4Lvv",
  "signature": "sigRE13vLHVvHgLYZPmNWtwDryoQse9AM49vsY1BkCyF3X5dPZB1suiwdPXqvxrmaDPBuKJ6ahggHY4ESiTS2He8dg5SZCyu",
  "protocol": "PsFLorenaUUuikDWvMDr6fGBRG8kt3e3D3fHoXK1j1BFRxeSH4i",
  "chainId": "NetXdQprcVkpaWU",
  "hash": "BLtHCQwtTZfzd3XHZYt3aRxsXka9ftRnGRYyMdN8LqUGi1XY7HR",
  "operationsHash": "LLoaGpohJKE9WxfHMAXosweSu2s8gECiasgkU1hFGhppVra5xGXSq",
  "periodKind": "proposal",
  "currentExpectedQuorum": 5326,
  "baker": "tz1MQJPGNMijnXnVoBENFz9rUhaPt3S7rWoz",
  "consumedGas": 2548504777,
  "metaLevel": 1504094,
  "metaLevelPosition": 1504093,
  "metaCycle": 367,
  "metaCyclePosition": 861,
  "metaVotingPeriod": 48,
  "metaVotingPeriodPosition": 17246,
  "priority": 0,
  "utcYear": 2021,
  "utcMonth": 6,
  "utcDay": 6,
  "utcTime": "18:21:42",
  "forkId": "leader"
}

The syntax to query the indexer from command line is the following:

Simple Query

curl -X GET 'https://indexer-<network>.ateza.io/<path>' -H 'accept: application/json'

Complex Query

curl -X POST 'https://indexer-<network>.ateza.io/<path>' -H 'Content-Type: application/json' -d <data>

• <network> is replaced with either mainnet or one of the testnets
• <path> is found in the OpenAPI specification for the Conseil indexer.
• <data> is a JSON formatted data query

The example on the right illustrates a simple query to obtain the header of the head block.

Indexer Example #2

Example - Obtain metadata for entities

curl -X GET 'https://indexer-mainnet.ateza.io/v2/metadata/tezos/mainnet/entities' \
-H 'accept: application/json' | jq

[
  {
    "name": "accounts",
    "displayName": "Account",
    "count": 1512199,
    "displayNamePlural": "Accounts"
  },
  {
    "name": "accounts_history",
    "displayName": "Account History",
    "count": 17666666,
    "displayNamePlural": "Account History"
  },
  {
    "name": "baker_registry",
    "displayName": "Baker registry",
    "count": 104
  },
  {
    "name": "bakers",
    "displayName": "Baker",
    "count": 2478,
    "displayNamePlural": "Bakers"
  },
....
]

Complex data requests for the Conseil indexer are sent via the POST HTTP method with the following prefix: /v2/data/tezos/mainnet/<entity>. However, first we need to know which entities are available. One method is to use the OpenAPI specification. Another method, as demonstrated here, is to directly query the API from the command line. Note, that the item in the angle bracket <entity> should be replaced by the value listed for the name key in the metadata for entities.

For example, to obtain the metadata for <entity> we can use the path /v2/metadata/tezos/mainnet/entities as follows:

curl -X GET 'https://indexer-mainnet.ateza.io/v2/metadata/tezos/mainnet/entities' | jq

The truncated example on the right lists available entities. For the next example, we will use the value accounts from the name key to query the following path: /v2/data/tezos/mainnet/accounts.

Indexer Example #3

Example - What are the top 5 delegates (bakers) by total number of delegators?

curl -H 'Content-Type: application/json' \
-X POST 'https://indexer-mainnet.ateza.io/v2/data/tezos/mainnet/accounts' \
-d '{
    "fields": ["delegate_value", "account_id"],
    "predicates": [{ "field": "delegate_value", "set": [], "operation": "isnull", "inverse": true }],
    "aggregation": [{ "field": "account_id", "function": "count" }],
    "orderBy": [{ "field": "count_account_id", "direction": "desc" }],
    "limit": 5,
    "output": "csv"
}'

Response in "CSV" format

count_account_id,delegate_value
37902,tz1aRoaRhSpRYvFdyvgWLL6TGyRoGF51wDjM
6871,tz1WctSwL49BZtdWAQ75NY6vr4xsAx6oKdah
4921,tz1PWCDnz783NNGGQjEFFsHtrcK5yBW4E2rm
3585,tz1VQnqCCqX4K5sP3FNkVSNKTdCAMJDd3E1n
3435,tz2FCNBrERXtaTtNX6iimR1UJ5JSDxvdHM93

Now that we have a list of available entities, we can perform more complex queries to extract fine grained data. This will require using the HTTP method POST and sending a JSON formatted data query.

At a minimum, a JSON formatted data query needs the following key/value pairs:

{ "fields": [], "predicates": [], "limit": 5, }

where fields represents the information of interest in the query, predicates are essentially the operations to perform on those fields, and limit is the number of results to return.

Let's perform a query to list the top 5 delegates (bakers) by the total number of delegators. To do this we will query the entity accounts found in the previous example at the path /v2/data/tezos/mainnet/accounts to count the number of accounts delegated to a particular delegate. The fields of interest are account_id (account addresses) and delegate_value (baker address).

The fields account_id and delegate_value are found by performing an attribute query for the accounts path using the following command:

curl -X GET 'https://indexer-mainnet.ateza.io/v2/metadata/tezos/mainnet/accounts/attributes' -H 'accept: application/json' | jq

This returns a JSON formatted response showing all available fields under accounts including data types, descriptions, etc.

Next, we want to query all accounts that are delegated to a baker. This is realized in predicates by setting { "field": "delegate_value", "set": [], "operation": "isnull", "inverse": true }. This means we want all account wallets where the delegation field is NOT null. In other words, wallets that are delegated to a baker.

The aggregation is used to count the number of accounts delegated to a particular baker. Here, we set the field to account_id and function to count.

To display the results in descending order, we use orderBy and set the field to count_account_id and direction to desc. Note, that the syntax for the field in orderBy is function_fieldname where "count" is the "function" and "account_id" is the "fieldname" from aggregation.

The response output can be formatted in either CSV or JSON. In the example on the right, CSV is selected.

Indexer Example #4

Example - What is the baker balance for the baker ATEZA at block level 1502894?

curl -H 'Content-Type: application/json' \
-X POST 'https://indexer-mainnet.ateza.io/v2/data/tezos/mainnet/bakers_history' \
-d '{ 
    "predicates": [{"field": "pkh", "operation": "eq", "set": ["tz1ZcTRk5uxD86EFEn1vvNffWWqJy7q5eVhc"]}],
    "snapshot": {"field": "block_level", "value": 1502894},
    "fields": ["pkh", "asof", "block_level", "balance", "frozen_balance", "delegated_balance","staking_balance"],
    "output": "json"
}' | jq

Response in "JSON" format

[
  {
    "pkh": "tz1ZcTRk5uxD86EFEn1vvNffWWqJy7q5eVhc",
    "block_level": 1502878,
    "delegated_balance": 1224439094482,
    "asof": 1622929886000,
    "balance": 172114190029,
    "staking_balance": 1392691409523,
    "frozen_balance": 137293930713,
    "r": 1
  }
]

In this example, we will determine the XTZ balance, staking balance, and frozen balance for a baker at a specific block level. This can be realized through the snapshot key in the JSON formatted data query.

The below query can be used to obtain attributes for the bakers_history entity. This query helps us determine which fields are available for the bakers_history entity.

curl -X GET 'https://indexer-mainnet.ateza.io/v2/metadata/tezos/mainnet/bakers_history/attributes' -H 'accept: application/json' | jq

The results of this query show that the following fields are available:

"pkh", "asof", "block_level", "balance", "frozen_balance", "delegated_balance", "staking_balance"

Note, that the field asof is a Unix Epoch Timestamp in milliseconds.

To query the indexer at a specified block level, we specify the following nested object for the snapshot key:

snapshot": {"field": "block_level", "value": 1502894}

See the example on the right for an implementation of this query. Note, the output response is set to json.

Tezos Node Service

About

ATEZA provides RPC access to an archive Tezos node. The OpenAPI Shell RPCs below are generic in that the paths and functionality are generally independent of the current running mainnet protocol. The OpenAPI Protocol Specific RPCs, however, are more highly dependent upon the current running mainnet protocol and may occasionally change when the mainnet protocol updates.

OpenAPI Specifications

• Shell RPCs
• Protocol Specific RPCs

References

• Tezos Developer Resources

When using the above OpenAPI specification, enter main for the chain_id parameter.

OpenAPI Specifications are actively maintained and updated in accordance with the latest mainnet protocol.

Paths

The following HTTP methods and paths are available for mainnet and testnets:

RPC Example #1

Example - Request the head block hash from the Tezos node on the mainnet network

curl -X GET 'https://rpc-mainnet.ateza.io/chains/main/blocks/head/hash' \
-H 'accept: application/json' | jq

"BLZWor1LTQHfiKe4SCYUB8sZeeRbXosfgvVsLSvnFrNrsJrymHo"

The example on the right gets the hash of the head block from the Tezos archive node.