Fullnode REST API

This API ships with every fullnode. It is a simple, low-latency, low-level way to read state, submit transactions, and simulate transactions on Aptos. For NFTs, objects, historical activity, and aggregated tables, use the Indexer GraphQL API instead.

Base URL (Aptos Labs): https://api.{network}.aptoslabs.com/v1 — for example https://api.mainnet.aptoslabs.com/v1. fullnode.{network}.aptoslabs.com is an alias of the same service.

Spec and explorers

The Node API is OpenAPI 3.0 (Aptos Node API 1.2.0). This site publishes the spec and a generated reference; each network also hosts a live Swagger UI.

REST API reference Browsable docs generated from aptos-spec.json

OpenAPI spec (JSON) Machine-readable Aptos Node API specification

Mainnet explorer Live Swagger UI for Mainnet

Testnet explorer Live Swagger UI for Testnet

Devnet explorer Live Swagger UI for Devnet

The spec YAML on a node is GET /v1/spec.yaml. Health is GET /v1/-/healthy. Ledger info (chain ID, version, epoch, role) is GET /v1. Node identity is GET /v1/info.

curl "https://api.mainnet.aptoslabs.com/v1"

Authentication and rate limits

Anonymous access is limited per IP. Attach a Geomi API key for higher limits:

curl "https://api.mainnet.aptoslabs.com/v1/accounts/0x1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Labs-hosted Node and Indexer APIs bill in compute units and also enforce HTTP rate limits. See the Geomi billing docs.

Common operations

Operation	Method and path	Reference
Ledger info	GET /v1	get_ledger_info
Health	GET /v1/-/healthy	healthy
Account	GET /v1/accounts/{address}	get_account
Coin or FA balance	GET /v1/accounts/{address}/balance/{asset_type}	get_account_balance
View function	POST /v1/view	view
Submit transaction	POST /v1/transactions	submit_transaction
Simulate transaction	POST /v1/transactions/simulate	simulate_transaction
Transaction by version	GET /v1/transactions/by_version/{txn_version}	get_transaction_by_version
Account transactions	GET /v1/accounts/{address}/transactions	get_account_transactions
Events by handle	GET /v1/accounts/{address}/events/{event_handle}/{field_name}	get_events_by_event_handle

asset_type for get_account_balance can be a coin type such as 0x1::aptos_coin::AptosCoin or a fungible asset metadata address such as 0xa (APT). After the Fungible Asset migration, prefer this endpoint (or SDK helpers such as getAccountAPTAmount) over reading a CoinStore resource.

Viewing current and historical state

Most integrations need both current and historical state. Aptos provides historical transactions, state, and events as the result of transaction execution.

• Historical transactions include execution status, output, and related events. Each transaction has a unique version that is its global sequential position in the ledger.
• State at a version is the accumulation of all transaction outputs up to and including that version.
• Executing transactions may emit events, which hint at on-chain data changes.

Note

The fullnode you query must have reached the version that contains your data. Public fullnodes lag validator fullnodes, which follow validator nodes.

Nodes prune old ledger history (and can prune state) to bound disk use. The default window keeps the most recent 150 million transactions; almost all Mainnet and Testnet nodes use that default. Disable or resize pruning only if you run your own node — see Data Pruning. For historical data beyond a pruned window, use the Indexer.

Account transaction queries return sequence-number transactions from that account. They do not return orderless transactions sent from the account.

Reading state with the View function

View functions do not modify blockchain state when you call them through the API. A view function and its arguments can compute complex on-chain state in Move — for example, the highest bid in an auction. The REST operation is POST /view.

The call looks like simulation, but it has no side effects and returns the function output. You pass the module, function name, type arguments, and values. A function does not have to be immutable to use #[view]; if it is mutable, the API still will not commit state. Prefer making such functions private so they cannot be called as entry functions at runtime.

Framework modules already expose view functions, so you do not need to publish a module to try the endpoint:

curl -X POST "https://api.mainnet.aptoslabs.com/v1/view" \
  -H "Content-Type: application/json" \
  -d '{"function":"0x1::chain_id::get","type_arguments":[],"arguments":[]}'

aptos move view --function-id 0x1::chain_id::get

import { Aptos, AptosConfig, Network, type InputViewFunctionData } from "@aptos-labs/ts-sdk";

const aptos = new Aptos(new AptosConfig({ network: Network.MAINNET }));
const payload: InputViewFunctionData = {
  function: "0x1::chain_id::get",
};
const [chainId] = await aptos.view<[number]>({ payload });

For your own module, publish it with the Aptos CLI, then call aptos move view --function-id <address>::<module>::<function>.

The response is a JSON array of return values. You can also request Binary Canonical Serialization (BCS) by setting the appropriate Accept / content type on the REST call.