Morpho API

Fetch Morpho market and vault data, or build simulated transaction calls with the Action API.

OpenAPI specs

Use the OpenAPI spec for the API you call to generate types:

APIOpenAPI specCovers
Read APIhttps://docs.morpho.org/openapi.jsonBlue markets, Midnight markets, vaults, related data, and Midnight router endpoints
Action APIhttps://api.morpho.org/actions/docs/openapi.jsonEndpoints that build transaction calls

API surfaces

Read endpoints use GET requests to return data; the Action API requires an API key and returns calls for the user's wallet to sign and send.

SurfaceData fetching (GET)Action API (POST, API key required)
Fixed Rate Markets (Midnight)List marketsMidnight Borrow
Variable Rate Markets (Blue)List marketsBlue Borrow
Vaults V2List V2 vaultsVault V2 Deposit
Vaults V1List V1 vaultsVault V1 Deposit
OraclesGet oracle state—
TokensGet token—
ChainsGet chains—

API access

  • Public API No API key is required for https://api.morpho.org. The same endpoints are also available at https://private.api.morpho.org with your API key.
  • Private API Private API access is required. Send requests to https://private.api.morpho.org with your API key in the x-api-key header. Request an API key.

Use the method, path and parameters documented for each operation. Endpoint pages and tutorial sections show these tags so you know which API to call.

Action API

The Morpho Action API returns the transaction calls to send from your wallet, with a simulation and a signed proof. The API does not submit transactions. Verify each response before signing typed data or sending calls.

An API key is required. Request an API key and send it in the x-api-key header.

Use https://private.api.morpho.org as the base URL. Action requests on https://api.morpho.org are refused with HTTP 403.

For public signing keys and proof checks, see Verify the signed proof.

Versioning

Endpoint versions appear in the path. Most routes use /v0. Exactly two routes use /v1: /v1/vaults-v2/{vault-selector}/state and /v1/vaults-v2/{vault-selector}/apy-averages. Every other Vault V2 route, including the /v0/vaults-v2 list, stays on /v0.

Selectors

Path selectors use the formats described by each operation:

ParameterFormat
Variable Rate Markets (Blue) {market-selector}<chain_id>:<market_id>, for example 1:0xfff1970c0ffae288764186fbb38a9171a17e98676744a1e345809cb8b9e73342 on Ethereum or the Base cbBTC/USDC market 8453:0x9103c3b4e834476c9a62ea009ba2c884ee42e94e6e314a26f04d312434191836. Market IDs are 32-byte hashes: copy one from /v0/blue/markets, never compose one
Fixed Rate Markets (Midnight) {market-id}Market ID only, no chain prefix: the same ID never appears on two chains. Example: 0x00bf2a673443d982dc209eac2764ccf8ad7e38b6a11df1ec96e9dc722260812c
{vault-selector}<chain_id>:<vault_address>, for example the Base Vault V2 Gauntlet USDC Prime: 8453:0x050cE30b927Da55177A4914EC73480238BAD56f0
{oracle-selector}<chain_id>:<oracle_address>, taken from a market's oracle_address; for the Blue example above, 1:0xd6154930A8df0A488Fae08547E53221B572EEA37
{token-selector}<chain_id>:<address>
{block-selector}<chain_id>:<block_number>
{user-address}Address of the position owner or requested user

Supported networks

The Read API accepts different chain filters for Blue, vaults and periphery endpoints than for Midnight endpoints:

Blue, vaults and periphery (Read API)

The Read API covers Blue markets, Vault V1 and Vault V2, user positions, and supporting resources such as tokens, oracles, chains, blocks and curators, alongside Midnight markets and router endpoints. These tables list accepted chain filters, not deployment guarantees.

NetworkChain ID
Ethereum1
Arbitrum42161
Arc5042
Base8453
HyperEVM999
Katana747474
Monad143
OP Mainnet10
Polygon137
Robinhood Chain4663
Unichain130
Stable988
Tempo4217
World Chain480
X Layer196

Midnight (Read API)

NetworkChain ID
Ethereum1
Base8453
Arc5042
Robinhood Chain4663
Tempo4217
Arbitrum42161

Morpho API main rules

Pagination

Cursor-paginated operations use limit and cursor as documented. Omit cursor on the first request, then send the previous response's cursor value unchanged until it is null. Never build or guess a cursor value: an invented cursor returns 400 INVALID_CURSOR. In examples, write the second request as cursor=<cursor from the previous response>, never as a literal value. Limits, defaults, and cursor binding vary by endpoint; keep the filters and sort values unchanged when continuing a paginated request.

Response envelope

Successful response schemas place results under a top-level data field. Paginated responses may also include a top-level cursor; the shape of data depends on the endpoint.

Amount units

Amount fields use the units stated in their descriptions. For example, vault total_assets is in underlying token units, and Midnight min_assets is in raw loan-token assets. Blue market lltv_wad is WAD-scaled; the spec defines 1e18 as 100%. Amounts are integer strings in the token's smallest unit: parse them with BigInt (or Python int), never Number or float, and scale by the token's decimals from /v0/tokens/{token-selector} only at the end, for example USD TVL = formatUnits(BigInt(total_assets) * priceE18 / 10n ** BigInt(decimals), 18) with viem's formatUnits and parseUnits, where priceE18 = parseUnits(price.toLocaleString("en-US", { useGrouping: false, maximumFractionDigits: 18 }), 18) turns the USD number from /v0/tokens/{token-selector}/price into an 18-decimal integer, so the multiplication stays exact. Never call Number(BigInt(...)) on a raw amount. Vault shares are also raw integers; their decimals are not always 18, so report assets rather than converting shares yourself.

Rate limits and best practices

To ensure reliable API infrastructure for all users and protect against malicious usage, spam, and attacks, the API enforces the following rate limits:

LimitThresholdResponse
Standard750 requests/minute per IP429 Too Many Requests with Retry-After: 600
Severe abuse3,334 requests/10 min per IP (about 20,000/hour)429 Too Many Requests with Retry-After: 604800

These limits apply to api.morpho.org. For higher limits, request an API key.

An IP that goes over the severe-abuse limit is blocked for 7 days. Repeated abuse can lead to a permanent block.

Best practiceRecommendation
Cache responsesCache API query results on your backend to reduce redundant requests and improve your application's performance.
Request only what you needUse the documented filters and pagination to fetch only the data required for your use case.
Avoid excessive pollingDesign your application to fetch data efficiently, respecting API limits to prevent interruptions.

Errors

StatusMeaningExample error codes
400Invalid request parameters, cursor, or limitsINVALID_CURSOR, VALIDATION_FAILED (Midnight)
404Requested position, token, market, or resource was not foundMARKET_NOT_FOUND (Midnight)
413Mempool validation payload is too largePAYLOAD_TOO_LARGE (Midnight)
422Requested quote size cannot be fully satisfiedINSUFFICIENT_LIQUIDITY (Midnight)
429See Rate limits and best practicesTOO_MANY_REQUESTS (Midnight)
500Unexpected server errorINTERNAL_ERROR (Midnight)
503Service unavailableSERVICE_UNAVAILABLE (Midnight)

Midnight error responses expose the machine-readable code as error.code.

Find the REST endpoint for a task

The REST API is the recommended default for reads. Each route below links to its API reference, including parameters and response fields.

Replace {vault-selector}, {oracle-selector}, and {token-selector} with <chainId>:<address> (for example, 8453:0x... for Base). Replace {market-selector} with <chainId>:<marketId> for Blue. Midnight uses its own {market-id}; {user-address} is a wallet address.

Read taskREST routeKey response fields
List and paginate Blue markets/v0/blue/markets (cursor, limit, optional chain_id)market_id, loan_token, collateral_token, oracle_address, irm_address, lltv_wad; top-level cursor
Read Blue market state/v0/blue/markets/{market-selector}/statetotal_supply_assets, total_borrow_assets, total_supply_shares, total_borrow_shares, fee_wad, rate_at_target_per_second_wad, last_accrual_timestamp; no APY fields
Read Blue market state history/v0/blue/markets/{market-selector}/state/historydata[] of timestamp, total_supply_assets, total_borrow_assets, total_collateral_assets
Read Blue market APY history/v0/blue/markets/{market-selector}/apy/historydata[] of timestamp, supply_apy, borrow_apy
Read Blue market APY averages/v0/blue/markets/{market-selector}/apy-averagessupply_apy_averages and borrow_apy_averages, keyed 6h, 24h, 7d, 30d, 90d, 1y; no lookback parameter
Read market liquidity, including Public Allocator liquidity/v0/blue/markets/{market-selector}/liquiditymarket_liquidity, reallocatable_liquidity, borrow_amount_to_target_utilization
List the vaults the Public Allocator can pull liquidity from/v0/blue/markets/{market-selector}/public-allocator-vaultsdata[] of vault_address, adapter_address, public_allocator_address, absolute_cap, can_pull_from_idle, can_pull_from_market, penalty_wad
Read the current oracle price/v0/oracles/{oracle-selector}/stateprice (integer string), last_updated_at (Unix seconds as a string), last_indexed_block (string)
List curators/v0/curatorsdata[] of curator_id, name, image_url, verified, addresses[] (chain_id, curator_address); top-level cursor. Query: verified, chain_ids, limit (default 100, maximum 1000)
Read the curator behind an address/v0/curators/{curator-selector}/details (<chain_id>:<curator_address>)data.curators[] of id, name, logo_uri, socials[]. This is the only per-curator route
List and paginate Vault V1 instances/v0/vaults-v1data[] of vault_address, asset_address, name, symbol, curator; top-level cursor. Listed vaults plus V1 vaults a Vault V2 uses through a MorphoVaultV1Adapter; items carry no listing flag and there is no listed parameter
List and paginate Vault V2 instances/v0/vaults-v2data[] of vault_address, asset_address, name, symbol, curator; top-level cursor. Listed vaults only; there is no listed parameter. This list stays on /v0
Read Vault V1 state, including total assets and share price/v0/vaults-v1/{vault-selector}/statetotal_assets, total_supply, share_price_ray, withdrawable_assets
Read Vault V2 state, including total assets and share price/v1/vaults-v2/{vault-selector}/statetotal_assets, total_supply, share_price_ray, idle_assets, allocated_assets, withdrawable_assets
Read Vault V1 state history/v0/vaults-v1/{vault-selector}/state/historydata[] of timestamp, total_assets, share_price_ray
Read Vault V2 state history/v0/vaults-v2/{vault-selector}/state/historydata[] of timestamp, total_assets, share_price_ray
Read Vault V1 APY history/v0/vaults-v1/{vault-selector}/apy/historydata[] of timestamp, apy
Read Vault V2 APY history/v0/vaults-v2/{vault-selector}/apy/historydata[] of timestamp, apy
Read Vault V1 APY averages/v0/vaults-v1/{vault-selector}/apy-averagesapy, lookback: one window per call, chosen with the lookback query (one_hour, six_hours, one_day, seven_days, thirty_days, ninety_days, one_year, inception)
Read Vault V2 APY averages/v1/vaults-v2/{vault-selector}/apy-averagesapy, lookback: one window per call, chosen with the lookback query (one_hour, six_hours, one_day, seven_days, thirty_days, ninety_days, one_year, inception)
Read Vault V1 allocations/v0/vaults-v1/{vault-selector}/allocationsallocations[] of market_id, supply_assets, supply_shares, supply_cap, pending
Read Vault V2 allocations/v0/vaults-v2/{vault-selector}/allocationsdata.allocations[] of adapter_address, adapter_kind (morpho_market_v1, morpho_market_v1_v2, morpho_vault_v1, morpho_vault_v2, unknown), target, caps[]. target has only type (blue_market, vault_v1, vault_v2, unknown) plus vault_address for vault targets and a nullable target_address for unknown targets; it never holds a market ID. For a blue_market adapter, each Blue market is a caps[] entry with cap_type: "market_v1", market_id, allocated_assets and expected_supply_assets; the cap_type: "adapter" entry carries real_assets. Every cap has cap_id, cap_data, absolute_cap, relative_cap_wad. data.unscoped_caps[] holds collateral caps (cap_type: "collateral", collateral_address) and caps whose target could not be decoded (cap_type: "unknown")
Read Vault V1 pending governance actions/v0/vaults-v1/{vault-selector}/pending-governance-actionsdata[] of action_type, parameters, executable_at_timestamp, submitted_transaction_hash
Read Vault V2 pending governance actions/v0/vaults-v2/{vault-selector}/pending-governance-actionsdata[] of action_type, parameters, executable_at_timestamp, submitted_transaction_hash; action_type unknown has null parameters
Read V2 withdrawal options/v0/vaults-v2/{vault-selector}/withdrawal-optionsidle_assets, liquidity_adapter_available_assets, adapter_penalties[] (adapter_address, force_deallocatable_assets, penalty_rate_wad). The total withdrawable now is withdrawable_assets on /v1/vaults-v2/{vault-selector}/state: call both
List a user's Vault V1 positions across chains/v0/vaults-v1/users/{user-address}/positionsdata[] of vault_address, chain_id, shares, assets; top-level cursor. Items carry no asset address: read it from the vault detail's data.asset
List a user's Vault V2 positions across chains/v0/vaults-v2/users/{user-address}/positionsdata[] of vault_address, chain_id, shares, assets; top-level cursor. Items carry no asset address: read it from the vault detail's data.asset
Read a user's Vault V1 position activity/v0/vaults-v1/{vault-selector}/users/{user-address}/position/activitydata[] of type (deposit, withdraw, shares_transfer_in, shares_transfer_out), tx_hash, block_number, data.assets, data.shares; limit defaults to 100, maximum 1000
Read a user's Vault V2 position activity/v0/vaults-v2/{vault-selector}/users/{user-address}/position/activitydata[] of type (deposit, withdraw, shares_transfer_in, shares_transfer_out), tx_hash, block_number, data.assets, data.shares; limit defaults to 100, maximum 1000
Read a user's Vault V1 position history/v0/vaults-v1/{vault-selector}/users/{user-address}/position/historydata[] of timestamp, shares, assets
Read a user's Vault V2 position history/v0/vaults-v2/{vault-selector}/users/{user-address}/position/historydata[] of timestamp, shares, assets
Read a user's Vault V1 performance (PnL)/v0/vaults-v1/{vault-selector}/users/{user-address}/position/performancenet_earnings_assets, return_on_capital (number)
Read a user's Vault V2 performance (PnL)/v0/vaults-v2/{vault-selector}/users/{user-address}/position/performancenet_earnings_assets, return_on_capital (number)
List and paginate a user's Blue positions across markets and chainsGET /v0/blue/users/{user-address}/positions (cursor, limit)data[] of chain_id, market_id, supply_shares, borrow_shares, collateral_assets; top-level cursor
Read a user's Blue market position/v0/blue/markets/{market-selector}/users/{user-address}/positionsupply_shares, borrow_shares, collateral_assets (shares, not assets)
Read a user's Blue position history/v0/blue/markets/{market-selector}/users/{user-address}/position/historydata[] of timestamp, supply_shares, borrow_shares, collateral_assets
Read a user's Blue position performance/v0/blue/markets/{market-selector}/users/{user-address}/position/performancesupply_net_earnings_assets, supply_return_on_capital, borrow_net_cost_assets, borrow_cost_on_capital
List Midnight books/v0/midnight/booksdata[] of market_id, maturity, loan_token, collaterals, top 3 asks and bids levels (price, units, assets); top-level cursor. Query: limit (default 10, maximum 20), sort (comma-separated id, ask, bid, maturity, - prefix for descending, at most 3 fields), optional chain_ids (at most one chain), loan_tokens, collateral_tokens, maturities, maturity_gte, maturity_lte
Read one Midnight book/v0/midnight/books/{market-id}asks and bids, up to depth levels each (tick, price scaled by 1e18, units, assets, count). Query: depth (default 100, maximum 6745)
Quote a Midnight book/v0/midnight/books/{market-id}/{side}/quote (side: asks or bids; provide exactly one of assets or units)average_best_price, average_worst_price, available_assets, available_units, takeable_offers[]. Query: limit offers to walk (default and maximum 10000), optional slippage (0.1 to 100, one decimal) or average_worst_price, never both, optional taker; 422 when the target can't fill within limit or the guard
List the executable offers on one book side/v0/midnight/books/{market-id}/{side}/takeable-offersdata[] of market_id, units, offer, ratifier_data, valid_until, warning; up to 1,000 offers, best price first. Not paginated: no limit or cursor. Deprecated: it still works, but the spec gives no replacement or removal date; its warning field is deprecated too, so rely on units for the takeable amount
List one maker's takeable offers/v0/midnight/takeable-offersSame item fields; top-level cursor. Query: maker (required), optional market_ids and groups (each at most 20 IDs), limit, cursor
List a user's Midnight positions/v0/midnight/users/{user-address}/positionsdata[] of market_id, chain_id, type, maturity, credit, debt, effective_apr, collaterals; top-level cursor. active_only=true drops matured markets
Read the current USD token price/v0/tokens/{token-selector}/priceprice (USD number), provider, timestamp; decimals, symbol and logo_uri come from /v0/tokens/{token-selector}
List supported chains/v0/chainsdata[] of chain_id, name, last_indexed_block, supported_protocols (blue, vault-v1, vault-v2, midnight, preliquidation)

Common mistakes to avoid:

  • Vault V2 state and APY averages are only /v1/vaults-v2/{vault-selector}/state and /v1/vaults-v2/{vault-selector}/apy-averages; their /v0 versions don't exist. Vault V1 uses /v0 for both.
  • No REST route returns an instantaneous APY. /apy-averages and /apy/history are realized look-back values; label them with their window.
  • Amounts are integer strings: keep them as BigInt until you scale by token decimals.
  • Cursors come only from the previous response.
  • List Vault V2 with /v0/vaults-v2: only the state and APY averages routes use /v1.
  • Tokens have no list route: read each token with /v0/tokens/{token-selector}.
  • Vault detail responses use data.address and nest the asset as data.asset (address, decimals, symbol); only list items have vault_address and a flat asset_address.
  • Activity items use tx_hash, not hash or transaction_hash.
  • Use a real address in examples, such as the vault selector above, never a made-up one, and keep it on its own chain: 0x04422053aDDbc9bB2759b248B574e3FCA76Bc145 in the Earn tutorials is an Ethereum vault (1:), while 8453:0x050cE30b927Da55177A4914EC73480238BAD56f0 is on Base.
  • Write every route in full with its placeholders, such as /v1/vaults-v2/{vault-selector}/apy-averages; a bare version prefix is not a route.

Midnight book sides: bids are makers' buy (lend) offers and asks are makers' sell (borrow) offers. A taker lends by taking asks and borrows by taking bids; lend_depth sums bid assets and borrow_depth sums ask assets. Chain filters differ: the Blue market list takes chain_id, while the vault lists, user-position lists and Midnight books take chain_ids. History routes use a lookback query parameter: one_day, seven_days, thirty_days, ninety_days, one_year or inception, and the /apy/history routes also accept six_hours. There is no all window. Vault position lists default to every exposed chain when chain_ids is omitted; the V2 list excludes fee wrappers. Vault performance returns net_earnings_assets and return_on_capital, not USD PnL.

For product-specific examples, see the Earn, Borrow, and Midnight Get data tutorials.