morpho-ethereum-mainnet.md

Morpho Blue + MetaMorpho Subgraph Query Guide

Complete guide to querying Morpho vault data: liquidity, APY, rewards, fees, and market allocations.

📋 Quick Reference

Subgraph Endpoint:

https://gateway.thegraph.com/api/subgraphs/id/8Lz789DP5VKLXumTMTgygjU2xtuzx8AhbaacgN5PYCAs

API Key:

YOUR_API_KEY_HERE

Get your free API key at The Graph Studio

Network: Ethereum Mainnet (Morpho Blue)

---

🎯 Key Entities

MetaMorpho Vaults

• metaMorphos - Vault contracts
  • lastTotalAssets - Current liquidity/TVL
  • fee - Vault performance fee (in basis points)
  • rate.rate - Current APY
  • markets - Market allocations

Underlying Markets

• markets - Morpho Blue markets
  • totalSupply / totalBorrow - Market liquidity
  • lltv - Liquidation threshold
  • inputToken - Supply token
  • loanToken / collateralToken - Market tokens

Allocations

• metaMorphoMarkets - Vault → Market allocations
  • cap - Supply cap per market
  • enabled - Market status

---

📊 Example Queries

1. All MetaMorpho Vaults (Top 20 by TVL)

{
  metaMorphos(first: 20, orderBy: lastTotalAssets, orderDirection: desc) {
    id
    name
    symbol
    asset {
      symbol
      name
      decimals
    }
    totalShares
    lastTotalAssets
    fee
    timelock
    curator {
      id
    }
    owner {
      id
    }
  }
}

cURL:

curl -X POST \
  https://gateway.thegraph.com/api/subgraphs/id/8Lz789DP5VKLXumTMTgygjU2xtuzx8AhbaacgN5PYCAs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -d '{"query": "{ metaMorphos(first: 20, orderBy: lastTotalAssets, orderDirection: desc) { id name symbol asset { symbol name decimals } totalShares lastTotalAssets fee timelock curator { id } owner { id } } }"}'

---

2. Vault Details with Market Allocations

{
  metaMorpho(id: "0xYOUR_VAULT_ADDRESS_HERE") {
    id
    name
    symbol
    asset {
      symbol
      decimals
    }
    lastTotalAssets
    totalShares
    fee
    timelock
    curator {
      id
    }
    markets {
      id
      cap
      enabled
      removableAt
      market {
        id
        inputToken {
          symbol
        }
        loanToken {
          symbol
        }
        collateralToken {
          symbol
        }
        totalSupply
        totalBorrow
        lltv
      }
    }
  }
}

Note: Replace 0xYOUR_VAULT_ADDRESS_HERE with actual vault address (lowercase).

---

3. Vault APY Data

{
  metaMorphos(first: 10, orderBy: lastTotalAssets, orderDirection: desc) {
    id
    name
    symbol
    asset {
      symbol
      decimals
    }
    lastTotalAssets
    totalShares
    fee
    rate {
      rate
      side
      type
    }
  }
}

---

4. Market Allocations Across All Vaults

{
  metaMorphoMarkets(first: 100, orderBy: cap, orderDirection: desc) {
    id
    metaMorpho {
      name
      symbol
    }
    market {
      id
      inputToken {
        symbol
      }
      loanToken {
        symbol
      }
      collateralToken {
        symbol
      }
      totalSupply
      totalBorrow
      lltv
    }
    cap
    enabled
    removableAt
    isInSupplyQueue
    isInWithdrawQueue
  }
}

---

5. Underlying Morpho Blue Markets

{
  markets(first: 50, orderBy: totalSupply, orderDirection: desc) {
    id
    inputToken {
      symbol
      name
    }
    loanToken {
      symbol
    }
    collateralToken {
      symbol
    }
    totalSupply
    totalBorrow
    totalSupplyShares
    totalBorrowShares
    lltv
    oracle
    irm
    lastUpdate
  }
}

---

6. User Positions in Vaults

{
  metaMorphoPositions(first: 100, orderBy: shares, orderDirection: desc) {
    id
    account {
      id
    }
    metaMorpho {
      name
      symbol
    }
    shares
    lastAssetsBalance
    lastAssetsBalanceUSD
  }
}

---

7. Recent Deposits

{
  metaMorphoDeposits(
    first: 20
    orderBy: timestamp
    orderDirection: desc
  ) {
    id
    timestamp
    account {
      id
    }
    metaMorpho {
      name
      symbol
    }
    amount
    amountUSD
    shares
    rate {
      rate
    }
  }
}

---

8. Recent Withdrawals

{
  metaMorphoWithdraws(
    first: 20
    orderBy: timestamp
    orderDirection: desc
  ) {
    id
    timestamp
    account {
      id
    }
    metaMorpho {
      name
      symbol
    }
    amount
    amountUSD
    shares
    rate {
      rate
    }
  }
}

---

💡 Data Mappings for Your Use Case

Requirement	Entity	Field
Liquidity (TVL)	metaMorphos	lastTotalAssets
Net APY	metaMorphos → rate	rate
Fees	metaMorphos	fee (basis points)
Market Allocations	metaMorphoMarkets	cap
Allocation Amounts	metaMorphoMarkets	Check underlying market.totalSupply

---

🔧 Using with Code

JavaScript (Node.js / Browser)

const query = `{
  metaMorphos(first: 10, orderBy: lastTotalAssets, orderDirection: desc) {
    id
    name
    symbol
    lastTotalAssets
    fee
    rate {
      rate
    }
  }
}`;

const response = await fetch(
  'https://gateway.thegraph.com/api/subgraphs/id/8Lz789DP5VKLXumTMTgygjU2xtuzx8AhbaacgN5PYCAs',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_API_KEY_HERE'
    },
    body: JSON.stringify({ query })
  }
);

const data = await response.json();
console.log(data.data.metaMorphos);

Python

import requests

query = """
{
  metaMorphos(first: 10, orderBy: lastTotalAssets, orderDirection: desc) {
    id
    name
    symbol
    lastTotalAssets
    fee
    rate {
      rate
    }
  }
}
"""

response = requests.post(
    'https://gateway.thegraph.com/api/subgraphs/id/8Lz789DP5VKLXumTMTgygjU2xtuzx8AhbaacgN5PYCAs',
    json={'query': query},
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY_HERE'
    }
)

data = response.json()
print(data['data']['metaMorphos'])

---

📝 Important Notes

1. Fee Conversion: The fee field is in basis points. Divide by 10000 to get percentage.

   • Example: fee: 500 = 5% (500/10000)

2. APY Calculation: The rate.rate field provides the current rate. For historical APY:

   • Query historical snapshots
   • Calculate from totalAssets / totalShares changes over time

3. Address Format: Always use lowercase addresses in queries

   • ✅ 0xabcd...
   • ❌ 0xABCD...

4. Pagination: Results are limited to 1000 per query. Use pagination for larger datasets:

   {
     metaMorphos(first: 1000, skip: 0) { ... }
   }

5. Rate Limiting: The Graph has rate limits. Consider caching responses.

---

🔗 Additional Resources

• The Graph Documentation
• Morpho Documentation
• GraphQL Syntax Reference

---

🚀 Quick Test

Run this to verify everything works:

curl -X POST \
  https://gateway.thegraph.com/api/subgraphs/id/8Lz789DP5VKLXumTMTgygjU2xtuzx8AhbaacgN5PYCAs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 291c69c3c9d189767eacf4247cd00eb9" \
  -d '{"query": "{ metaMorphos(first: 5) { name symbol lastTotalAssets } }"}'

You should see a JSON response with vault data! 🎉