Getting Started

Historically, Aptos Labs hosted APIs have been accessible without the need for an API key. While anonymous access is still permitted, it is subject to lower rate limits to ensure fair and reliable use of our services. Over time, these limits may be reduced further to maintain optimal performance and prevent abuse. For developers needing consistent and higher levels of access, you must create an API Gateway account and attach an API key to all requests you make to Labs hosted APIs. This will provide you with greater reliability, higher rate limits, and useful metrics to track your usage.

1. Create an API Gateway account here.
2. Create a new application. See the guidance about application types to decide which to use.
3. Attach API keys to all requests made from your application. On the application page you will see code snippets demonstrating how to attach an API key to your requests.

If you know the free tier quotas (see below) are too low for your use case, before step 3 you can take out a billing plan that will grant you higher quotas. You can do this here.

Rate limits

Two key functions of API Gateway are authentication and rate limiting. API Keys are how your clients authenticate, but rate limiting applies on a per-application basis (they do not apply on a per-key basis). With this in mind, you should strive to use an application for a single purpose. For example, you might have applications named “Chess Processor Testnet” or “Chess Frontend Mainnet”. If one application begins to use more than its alloted Compute Units in a 5-minute window, some requests will be rejected with HTTP 429 errors. Other applications will not be affected, usage doesn’t “overflow” to another application’s quota.

Each account by default has an account-wide quota of 1,000,000 Compute Units. Each account is allowed to create up to 4 applications. By default, each time you create an application, 1/4th of your quota is assigned to that application. You can adjust how the quota is assigned to each application here.

As a general rule, you should only use one API key at a time. API Gateway supports multiple keys per application mostly to support things like key rotation in case a key is leaked.

Ratelimiting for frontend applications is more complex than for backend applications. Users of dapps using a frontend application are ratelimited in two ways:

• Application limit: The entire application has a CU limit, just like a backend application. For example, if the application has a limit of 1,000,000 CUs per 5-minute window and each user uses on average 20,000 CUs per 5-minute window, the application can support on average 50 concurrent users.
• Per-IP limit: You can configure a per-IP limit, to ensure no single user can consume too much of the application limit.

Note: For now, there is no way to set the per IP limit, by default it is 1,000,000 CUs. If you would like to change this, reach out to your contact at Aptos Labs.

Compute Units

Requests through API Gateway are measured in terms of Compute Units (CUs). CUs measure the relative cost of a request. For example, a given call to /v1/accounts/0x1 (the Node API) might cost 250 CUs while a call to /v1/graphql (the Indexer API) might cost 500 CUs, indicating that the resource cost of the second request is 2x higher than the first. Compared to just rate limiting based on request count, Compute Units allow us to capture that some requests are more resource intensive than others.

The method for calculating the CUs used by a request differs per upstream type (e.g. Node API vs. indexer API) and endpoint (e.g. /v1/view vs. /v1/accounts), but as a general rule of thumb, the more complex a request is (gas used, time taken, etc.), the more CUs it will consume. We use a variety of factors to calculate the cost of a request, and our approach is subject to change at any time. Broadly speaking, the behaviour is as described below.

Indexer API

The current approach for this upstream is quite simple.

In other words, cost is just a function of how long the upstream takes to process the request. In general, indexer API requests are dominated by I/O time on the database. The more complex a query is, the longer it takes, the higher the cost in CUs.

Node API (VM Endpoints)

Requests to endpoints that involve execution with the Move VM (e.g. /v1/transactions/simulate or /v1/transactions/view ) return the cost of that execution in terms of gas. We use this gas cost and some multiplier to get the final gas cost:

Node API (Other Endpoints)

We use the same formula as with the Indexer API, albeit with a different multiplier.

Application Types

When creating an application, you will be prompted to select an application type:

• Backend: If your application runs in an environment where you can keep an API key secret, select this type. This is generally anything that runs in a backend such as an indexer processor or fee payer server.
• Web App: If your application is a frontend web app (dapp), select this type. These apps include a public ID with their requests, an ID type that is okay to expose publicly. You need to provide the URL of your dapp when creating an application of this type.
• Browser Extension: If your application is a browser extension, select this type. Often this means wallets. Similar to web apps you provide a public ID instead of an API key. Unlike web apps, you provide the extension ID rather than a URL.

There is no dedicated type for mobile apps at the moment, just use the Web App type with your usual website as the URL.

Frontend applications are subject to more complex rate limiting than backend applications. See here.

Key Types

• Confidential key: Used with the backend application type. They look like aptoslabs_aXjFX8fDdZv_AXMynDZvp711WTBpSBmqLyj12RV9RFA6B. Keep these secret.
• Public ID: Used with the web app and browser extension application types. They look like AG-FL4PYMZ1YX1LGAJCWP2R1ACYTYRCBY1GB. We perform additional checks and analytics to ensure the use of these IDs is authentic.