Tools

Aave MCP groups its tools into reads, action builders, orders (token swaps), Savings GHO, DAO governance and guidance. tools/list on the endpoint returns the live inventory with each tool's full parameter schema, and is the authority whenever it disagrees with this page.

Token swaps move tokens in the wallet. They are protocol-agnostic, take no version, and run on the v4 backend.

A swap runs an order lifecycle: a quote mints a quoteId, prepare_order returns what the user signs, submit_signed_order relays the signed order, and get_order_status tracks it until it settles.

Some swaps need a token approval first. Prefer the gasless bySignature permit the quote offers and pass the signature back to prepare_order as permitSignature and permitDeadline; a byTransaction approval has to be sent and mined before the order can be prepared.

Savings GHO is an ERC-4626 vault on Ethereum that pays a target rate on deposited GHO. It is a product of its own rather than a reserve, so it has its own tools.

A wallet's maxDeposit is already the smaller of its GHO balance and the remaining cap, so size a deposit against that rather than against the cap. sGHO earns yield but is not collateral: it cannot be supplied or borrowed against, and it does not appear in a health factor.

These take no version. Governance V3 is the DAO's own contract generation, unrelated to the v3 and v4 markets. Vote tallies, quorum and per-voter power are all denominated in AAVE, so they compare directly.

Every successful result is the same envelope, returned both as JSON text and as structuredContent:

{  "data": {},  "next_actions": ["get_user_summary to confirm the resulting health factor"]}

Read the payload from data and follow next_actions. A result may also carry warnings, each with a level, a stable code, and a message:

A read covers every chain it can and names them under chainsCovered, so there is no need to loop over chains by hand. Where the full sweep would be too large to return, the read narrows and names what it left out under chainsNotCovered, which is the only case that needs a second call.

chainsNotServed means something else. Those are chains this API holds no market on, so an empty result there is an absence of data rather than an answer about the chain, and asking again returns the same nothing. get_chains flags them too.

prepare_action returns an execution plan, and its __typename says what to do next.

Both versions offer the same gasless route, and offer it the same way. When an approval plan carries bySignature permit typed data, sign that and call prepare_action again with permitSignature and permitDeadline, the deadline from the message that was signed. The call then returns the action transaction with no approval transaction at all. v4 offers this on a supply; v3 offers it on a supply, a repay or a withdraw, and not on a borrow, since nothing leaves the wallet there.

A plan with no bySignature is a token without permit support, so the on-chain route is the only one. Submit the byTransaction approval and wait for it to be mined before running prepare_action again: the action transaction is only issued once the allowance is visible on chain, so calling again too early returns the approval step a second time.

Supplying a chain's native gas token, with native, usually takes the PreContractActionRequired path, where the first transaction lets the native gateway act and the second performs the supply.

Amounts are in main, human units. "10.5" is 10.5 USDC, and token decimals are handled for you. The format is a plain positive decimal string, so 1e5 and hex are rejected, and get_reserve_details carries the decimals when a conversion is needed. 100000 base units of a 6-decimal token is "0.1", not "100".

On v4 every id is URL-safe base64 of a ::-joined tuple, so they all look alike and several differ only in how many segments they carry.

Carry ids verbatim from whichever tool returned them, and never assemble one. They are opaque by contract, the on-chain reserve id is a 256-bit number rather than a small index, and a value that was built by hand is rejected even when it looks right. The same asset also appears on several spokes at very different rates, which is why the reserveId matters and a symbol will not do.

v3 does not work this way. There a reserve is addressed as market plus token plus chainId, three plain values with no encoding, and an Aave pool address recognised from elsewhere belongs to another deployment and is rejected.

Four rules decide whether an action is possible at all. Each one otherwise surfaces as a different error.

A clean simulation says the position allows the action. It says nothing about token allowances, so an approval step can still be outstanding.