GraphQL

The Aave Protocol exposes a comprehensive GraphQL API that allows you to query market data, user positions, and execute transactions. This low-level API is perfect for custom integrations, data analysis, and building integrations for which the TypeScript SDK is not suitable.

Getting Started

The Aave Protocol GraphQL API is available at:

https://api.v3.aave.com/graphql

The URL above works also as a GraphQL playground you can use to test your queries.

You can query the API directly using any HTTP client. Here's a basic example using curl:

curl -X POST https://api.v3.aave.com/graphql \  -H "Content-Type: application/json" \  -d '{    "query": "query Chains { chains { name chainId icon } }"  }'

Query Operations

The Aave GraphQL API is constituted by just two types of queries:

  • Read queries – queries that return data from the Aave Protocol.

  • Transactions queries – queries that prepare transactions to be executed on the Aave Protocol.

The transactions queries are in turn divided into two categories:

  • Simple transactions – single-step transactions that can be sent directly to the wallet.

  • Complex transactions – transactions that may require prior approvals before they can be executed.

Simple Transactions

Simple transactions query returns a TransactionRequest object that can be used to send the transaction to the wallet.

TransactionRequest
type TransactionRequest {  to: EvmAddress!  from: EvmAddress!  data: BlockchainData!  value: BigInt!  chainId: ChainId!  operation: OperationType}

Complex Transactions

Complex transactions query returns an ExecutionPlan union.

The ExecutionPlan union represents the different scenarios that can occur when preparing a transaction:

  • TransactionRequest: The transaction can be executed directly.

  • ApprovalRequired: An approval transaction must be sent first, then the original transaction can be executed.

  • InsufficientBalanceError: The user doesn't have enough balance of the token to be used in the transaction.

union ExecutionPlan =    TransactionRequest  | ApprovalRequired  | InsufficientBalanceError

Transaction Monitoring

After sending a transaction, the Aave API may take a short time to process and reflect the new state in its responses due to caching and background invalidation. To reliably know when your transaction has been processed and data is up to date, use the hadProcessedKnownTransaction query.

This query lets you check if a transaction (by hash and operation type) has been indexed and processed by the API, so you can safely fetch updated user or market data. Note that this can only be used with transactions where the TransactionRequest has a non-null operation field.

query {  value: hadProcessedKnownTransaction(    request: { operation: SUPPLY, txHash: "0x1234…" }  )}

  • Returns true if the transaction has been processed and data is fresh.

  • Returns false if the transaction is not yet processed (wait and retry).

When to use:

  • After sending a transaction, poll this query until it returns true before fetching updated positions or balances.

  • This avoids race conditions with cached data and ensures your UI reflects the latest state.

Scalars

A non comprehensive list of the custom scalars used in the Aave Protocol GraphQL API.

A string representing binary data as a hex string.

0x0000000000000000000000000000000000000000000000000000000000000020

Common Types

Some of the common types used in the Aave Protocol GraphQL API.

A Currency object represents an ERC20 token.

type Currency {  """  The token address  """  address: EvmAddress!
  """  The chain id  """  chainId: ChainId!
  """  The token name  """  name: String!
  """  The token image  """  imageUrl: String!
  """  The token symbol  """  symbol: String!
  """  The token decimals  """  decimals: Int!}

Utility Queries

Supported Chains

Use the chains query to list the chains supported by the Aave Protocol v3.

query Chains {  chains {    __typename    name    chainId    icon  }}

USD Exchange Rates

Use the usdExchangeRates query to get the USD exchange rate for a list of tokens.

query UsdExchangeRates($request: UsdExchangeRatesRequest!) {  usdExchangeRates(request: $request) {    __typename    currency {      symbol      name      address      decimals    }    rate  }}

Next Steps