GraphQL API Overview

Coming soon: Need support for this? Email support@dwellir.com and we will enable it for you.

The Aptos GraphQL indexer gives you indexed, filterable access to transaction history, token activity, account state, and aggregate analytics without having to stitch together multiple REST requests yourself. Once GraphQL access is enabled for your API key, use https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/graphql for mainnet queries.

When to Use GraphQL

GraphQL is the better fit when you need:

• multi-table reads such as balances plus token metadata in one request
• server-side filtering, ordering, and pagination for dashboards or explorers
• aggregate queries for counts, sums, and activity rollups
• a predictable response shape driven by the exact fields your UI needs

For canonical ledger reads, transaction submission, or account-specific REST workflows, use the Aptos REST endpoints. For indexed history and analytics, GraphQL is usually the faster path.

Request Shape

Every request is a standard GraphQL POST with a query string and optional variables object:

{
  "query": "query LedgerInfo($limit: Int!) { ledger_infos(limit: $limit, order_by: { version: desc }) { chain_id version timestamp } }",
  "variables": {
    "limit": 1
  }
}

That lets you keep queries reusable and move environment-specific inputs, such as account addresses or time windows, into variables instead of string interpolation.

Starter Query

query LedgerInfo($limit: Int!) {
  ledger_infos(limit: $limit, order_by: { version: desc }) {
    chain_id
    version
    timestamp
  }
}

curl -X POST https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query LedgerInfo($limit: Int!) { ledger_infos(limit: $limit, order_by: { version: desc }) { chain_id version timestamp } }",
    "variables": { "limit": 1 }
  }'

This is a good health check because it exercises filtering, ordering, and the latest indexed ledger state in one small response.

Common Query Patterns

Most production GraphQL usage falls into a few repeatable patterns:

• lookup by address or asset type with where filters
• latest-first activity feeds with order_by and limit
• portfolio views that fetch balances together with related metadata
• analytics panels that use _aggregate tables for counts and rollups

Start with a narrow filter and a low limit, then expand once you know the table and relation shape you need.

Operational Notes

• GraphQL access is enabled per account. If the endpoint is not provisioned for your key yet, request enablement before building against it.
• Prefer variables over string-built queries so clients stay type-safe and easier to cache.
• Ask only for the fields you render. Smaller selection sets reduce payload size and make caching more effective.
• Add order_by explicitly for paged queries so your client does not rely on implicit ordering.
• Use aggregate tables for metrics and dashboards rather than fetching large result sets just to count them client-side.

Related Guides

• User Transactions for indexed transaction history
• Fungible Assets for balances and token metadata
• Aggregations for counts and rollups
• Subscriptions for real-time GraphQL updates