Skip to Content
docs

Aave V3 GraphQL Quickstart

AaveKit API is a GraphQL API to query market data and user positions and to prepare transactions. Use it where the TypeScript SDK does not fit.

Getting Started

AaveKit API for Aave V3 is available at https://api.v3.aave.com/graphql.

The URL above is also a GraphQL playground for testing queries.

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

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

Query Operations

AaveKit API has two types of queries:

  • Read queries – queries that return data from the Aave Protocol.
  • Transaction 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, AaveKit 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 hasProcessedKnownTransaction 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: hasProcessedKnownTransaction(
    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).

After sending a transaction, poll this query until it returns true before fetching updated positions or balances, so your UI does not show cached data.

Scalars

A non-exhaustive list of the custom scalars used in AaveKit API.

ScalarDescriptionExample
BlockchainDataA string representing binary data as a hex string.0x0000000000000000000000000000000000000000000000000000000000000020
BigIntA string representing a big integer in decimal format.1000000000000000000000
BigDecimalA string representing a decimal number with arbitrary precision.1.0000000000000000001
ChainIdA number representing a Chain ID.1, 8453, 42161
EvmAddressA string representing an EVM address.0x0000000000000000000000000000000000000000
TxHashA string representing an EVM transaction hash.0x0000000000000000000000000000000000000000000000000000000000000000
DateTimeA string representing a date and time.2021-01-01T00:00:00Z

Common Types

Some of the common types used in AaveKit API.

A Currency object represents an ERC-20 token.

GraphQL
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!
}

A DecimalValue object represents a decimal value with arbitrary precision.

GraphQL
type DecimalValue {
  """
  The raw unformatted value
  """
  raw: BigInt!

  """
  The decimals the value formatted into
  """
  decimals: Int!

  """
  The formatted value
  """
  value: BigDecimal!
}

A TokenAmount object represents an amount of a token.

GraphQL
type TokenAmount {
  """
  The USD exchange rate for the token
  """
  usdPerToken: BigDecimal!

  """
  The amount
  """
  amount: DecimalValue!

  """
  The amount in USD
  """
  usd: BigDecimal!
}

A PercentValue object represents a percentage value with precision and formatting.

GraphQL
type PercentValue {
  """
  The raw unnormalized percentage (the value that lives onchain)
  """
  raw: BigInt!

  """
  The decimals representing the precision of the onchain raw value
  """
  decimals: Int!

  """
  The normalized percentage (1.0 = 100%)
  """
  value: BigDecimal!

  """
  The human-readable formatted value you can render on a UI straight away.
  For example, this will turn `0.01232343` to `1.23`, it will always round to `2` decimal points.
  """
  formatted: BigDecimal!
}

A Chain object represents a blockchain network supported by the Aave Protocol.

GraphQL
type Chain {
  """
  The chain name
  """
  name: String!

  """
  The chain icon
  """
  icon: String!

  """
  The chain id
  """
  chainId: ChainId!
}

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