Aave V4 GraphQL Quickstart
AaveKit API is a GraphQL interface to query liquidity data and user positions and to prepare transactions. Use it for custom integrations and data analysis where the TypeScript SDK does not fit.
Getting Started
AaveKit API for Aave V4 is available at https:/.
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 to query supported chains:
curl -X POST https://api.v4.aave.com/graphql \
-H "Content-Type: application/json" \
-d '{
"query": "query Chains { chains(request: { query: { filter: ALL } }) { 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.
Transaction 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 Transaction object that can be used to send the transaction to the wallet.
type TransactionRequest {
to: EvmAddress!
from: EvmAddress!
data: BlockchainData!
value: BigInt!
chainId: ChainId!
operations: [OperationType!]
}
Complex Transactions
Complex transactions query returns an Execution union.
The Execution union represents the different scenarios that can occur when preparing a transaction:
Transaction: The transaction can be executed directly.Request Erc20: One or more ERC-20 approvals are required first, then the original transaction can be executed.Approval Required Pre: A pre-contract action must be sent first, then the original transaction can be executed.Contract Action Required Insufficient: The user doesn’t have enough balance of the token to be used in the transaction.Balance Error
union ExecutionPlan =
| TransactionRequest
| Erc20ApprovalRequired
| PreContractActionRequired
| InsufficientBalanceError
type Erc20ApprovalRequired {
approvals: [Erc20Approval!]!
reason: String!
requiredAmount: DecimalNumber!
currentAllowance: DecimalNumber!
originalTransaction: TransactionRequest!
}
type Erc20Approval {
byTransaction: TransactionRequest!
bySignature: PermitTypedData
}
type PermitTypedData {
types: JSON!
primaryType: String!
domain: DomainData!
message: JSON!
signedAmount: BigDecimal!
}
type PreContractActionRequired {
transaction: TransactionRequest!
reason: String!
originalTransaction: TransactionRequest!
}
type InsufficientBalanceError {
required: DecimalNumber!
available: DecimalNumber!
}
Multiple Approvals: Some tokens, like USDT, don’t allow raising an existing allowance. For these, the API returns two approvals: reset to 0, then set the required amount.
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 has query.
This query lets you check if a transaction (by hash and operations 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 Transaction has a non-null operations field.
query {
value: hasProcessedKnownTransaction(
request: { operations: [SPOKE_SUPPLY], txHash: "0x1234…" }
)
}
{
"data": {
"value": true
}
}
- Returns
trueif the transaction has been processed and data is fresh. - Returns
falseif 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. This avoids race conditions with cached data.
Scalars
A non-exhaustive list of custom scalars used in the AaveKit API.
A string representing binary data as a hex string.
0x0000000000000000000000000000000000000000000000000000000000000020
A string representing a big integer in decimal format.
1000000000000000000000
A string representing a decimal number with arbitrary precision.
1.0000000000000000001
A number representing a Chain ID.
1
8453
42161
A string representing an EVM address.
0x0000000000000000000000000000000000000000
A string representing an EVM transaction hash.
0x0000000000000000000000000000000000000000000000000000000000000000
A string representing a date and time.
2021-01-01T00:00:00Z
Common Types
Some of the common types used in the Aave Protocol GraphQL API.
A Decimal object represents a decimal value with arbitrary precision.
type DecimalNumber {
"""
The on-chain representation of `value`, stored as an integer.
"""
onChainValue: BigInt!
"""
The number of decimals defining how many fractional digits the number supports.
"""
decimals: Int!
"""
The normalized value computed as `onChainValue / 10^decimals`.
"""
value: BigDecimal!
}
A Percent object represents a percentage value.
type PercentNumber {
"""
The on-chain representation of the percentage, stored in basis points (bps).
"""
onChainValue: BigInt!
"""
The number of decimals defining the precision of `bps`.
"""
decimals: Int!
"""
The normalized percentage value where 1.0 represents 100%.
"""
value: BigDecimal!
"""
The human-friendly percentage value where 100.0 represents 100%
"""
normalized: BigDecimal!
}
A Chain object represents a blockchain network supported by the Aave Protocol.
type Chain {
"""
The chain name
"""
name: String!
"""
The chain icon
"""
icon: String!
"""
The chain id
"""
chainId: ChainId!
"""
The RPC URL of the chain
"""
rpcUrl: String!
"""
The blockchain explorer URL
"""
explorerUrl: String!
"""
Whether this chain is a fork
"""
isFork: Boolean!
"""
Whether this is a testnet chain
"""
isTestnet: Boolean!
"""
The chain's native asset, or null on a chain with no native token
"""
nativeAsset: NativeAsset
nativeWrappedToken: EvmAddress! @deprecated(reason: "Use nativeAsset { ... on WrappedNativeAsset { wrappedNativeTokenAddress } }.")
nativeInfo: TokenInfo! @deprecated(reason: "Use nativeAsset { ... on WrappedNativeAsset { nativeToken } ... on SharedBalanceNativeAsset { nativeToken } }.")
nativeGateway: EvmAddress! @deprecated(reason: "Use nativeAsset { ... on WrappedNativeAsset { gateway } }.")
"""
The signature gateway address
"""
signatureGateway: EvmAddress!
}
A Token object contains basic metadata about a token.
type TokenInfo {
"""
The token info id
"""
id: TokenInfoId!
"""
The token name
"""
name: String!
"""
The token symbol
"""
symbol: String!
"""
The canonical token symbol
"""
canonicalSymbol: String!
"""
The token icon URL
"""
icon: String!
"""
The token decimals
"""
decimals: Int!
"""
The token categories
"""
categories: [TokenCategory!]!
}
An Erc20 object represents an ERC-20 token with its metadata and chain information.
type Erc20Token {
"""
The token contract address
"""
address: EvmAddress!
"""
The chain this token is deployed on
"""
chain: Chain!
"""
The token metadata
"""
info: TokenInfo!
"""
Whether this token is a wrapped native token (e.g., WETH)
"""
isWrappedNativeToken: Boolean!
}
An Erc20 object represents an amount of an ERC-20 token.
type Erc20Amount {
"""
The amount
"""
amount: DecimalNumber!
"""
Get the fiat amount for this token amount
"""
exchange(currency: Currency! = USD): ExchangeAmount!
"""
Get the fiat rate for this token
"""
exchangeRate(currency: Currency! = USD): DecimalNumber!
"""
The token information
"""
token: Erc20Token!
}
An Exchange object represents a monetary value in a fiat currency.
type ExchangeAmount {
"""
The numerical value
"""
value: BigDecimal!
"""
The currency name
"""
name: String!
"""
The currency symbol (e.g., $, €, £)
"""
symbol: String!
"""
The currency icon URL
"""
icon: String!
"""
The number of decimals for the currency
"""
decimals: Int!
}