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:
| API | OpenAPI spec | Covers |
|---|---|---|
| Read API | https://docs.morpho.org/openapi.json | Blue markets, Midnight markets, vaults, related data, and Midnight router endpoints |
| Action API | https://api.morpho.org/actions/docs/openapi.json | Endpoints 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.
| Surface | Data fetching (GET) | Action API (POST, API key required) |
|---|---|---|
| Fixed Rate Markets (Midnight) | List markets | Midnight Borrow |
| Variable Rate Markets (Blue) | List markets | Blue Borrow |
| Vaults V2 | List V2 vaults | Vault V2 Deposit |
| Vaults V1 | List V1 vaults | Vault V1 Deposit |
| Oracles | Get oracle state | — |
| Tokens | Get token | — |
| Chains | Get chains | — |
API access
- Public API No API key is required for
https://api.morpho.org. The same endpoints are also available athttps://private.api.morpho.orgwith your API key. - Private API Private API access is required. Send requests to
https://private.api.morpho.orgwith your API key in thex-api-keyheader. 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:
| Parameter | Format |
|---|---|
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.
| Network | Chain ID |
|---|---|
| Ethereum | 1 |
| Arbitrum | 42161 |
| Arc | 5042 |
| Base | 8453 |
| HyperEVM | 999 |
| Katana | 747474 |
| Monad | 143 |
| OP Mainnet | 10 |
| Polygon | 137 |
| Robinhood Chain | 4663 |
| Unichain | 130 |
| Stable | 988 |
| Tempo | 4217 |
| World Chain | 480 |
| X Layer | 196 |
Midnight (Read API)
| Network | Chain ID |
|---|---|
| Ethereum | 1 |
| Base | 8453 |
| Arc | 5042 |
| Robinhood Chain | 4663 |
| Tempo | 4217 |
| Arbitrum | 42161 |
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:
| Limit | Threshold | Response |
|---|---|---|
| Standard | 750 requests/minute per IP | 429 Too Many Requests with Retry-After: 600 |
| Severe abuse | 3,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 practice | Recommendation |
|---|---|
| Cache responses | Cache API query results on your backend to reduce redundant requests and improve your application's performance. |
| Request only what you need | Use the documented filters and pagination to fetch only the data required for your use case. |
| Avoid excessive polling | Design your application to fetch data efficiently, respecting API limits to prevent interruptions. |
Errors
| Status | Meaning | Example error codes |
|---|---|---|
| 400 | Invalid request parameters, cursor, or limits | INVALID_CURSOR, VALIDATION_FAILED (Midnight) |
| 404 | Requested position, token, market, or resource was not found | MARKET_NOT_FOUND (Midnight) |
| 413 | Mempool validation payload is too large | PAYLOAD_TOO_LARGE (Midnight) |
| 422 | Requested quote size cannot be fully satisfied | INSUFFICIENT_LIQUIDITY (Midnight) |
| 429 | See Rate limits and best practices | TOO_MANY_REQUESTS (Midnight) |
| 500 | Unexpected server error | INTERNAL_ERROR (Midnight) |
| 503 | Service unavailable | SERVICE_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 task | REST route | Key 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}/state | total_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/history | data[] of timestamp, total_supply_assets, total_borrow_assets, total_collateral_assets |
| Read Blue market APY history | /v0/blue/markets/{market-selector}/apy/history | data[] of timestamp, supply_apy, borrow_apy |
| Read Blue market APY averages | /v0/blue/markets/{market-selector}/apy-averages | supply_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}/liquidity | market_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-vaults | data[] 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}/state | price (integer string), last_updated_at (Unix seconds as a string), last_indexed_block (string) |
| List curators | /v0/curators | data[] 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-v1 | data[] 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-v2 | data[] 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}/state | total_assets, total_supply, share_price_ray, withdrawable_assets |
| Read Vault V2 state, including total assets and share price | /v1/vaults-v2/{vault-selector}/state | total_assets, total_supply, share_price_ray, idle_assets, allocated_assets, withdrawable_assets |
| Read Vault V1 state history | /v0/vaults-v1/{vault-selector}/state/history | data[] of timestamp, total_assets, share_price_ray |
| Read Vault V2 state history | /v0/vaults-v2/{vault-selector}/state/history | data[] of timestamp, total_assets, share_price_ray |
| Read Vault V1 APY history | /v0/vaults-v1/{vault-selector}/apy/history | data[] of timestamp, apy |
| Read Vault V2 APY history | /v0/vaults-v2/{vault-selector}/apy/history | data[] of timestamp, apy |
| Read Vault V1 APY averages | /v0/vaults-v1/{vault-selector}/apy-averages | apy, 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-averages | apy, 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}/allocations | allocations[] of market_id, supply_assets, supply_shares, supply_cap, pending |
| Read Vault V2 allocations | /v0/vaults-v2/{vault-selector}/allocations | data.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-actions | data[] of action_type, parameters, executable_at_timestamp, submitted_transaction_hash |
| Read Vault V2 pending governance actions | /v0/vaults-v2/{vault-selector}/pending-governance-actions | data[] 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-options | idle_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}/positions | data[] 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}/positions | data[] 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/activity | data[] 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/activity | data[] 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/history | data[] of timestamp, shares, assets |
| Read a user's Vault V2 position history | /v0/vaults-v2/{vault-selector}/users/{user-address}/position/history | data[] of timestamp, shares, assets |
| Read a user's Vault V1 performance (PnL) | /v0/vaults-v1/{vault-selector}/users/{user-address}/position/performance | net_earnings_assets, return_on_capital (number) |
| Read a user's Vault V2 performance (PnL) | /v0/vaults-v2/{vault-selector}/users/{user-address}/position/performance | net_earnings_assets, return_on_capital (number) |
| List and paginate a user's Blue positions across markets and chains | GET /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}/position | supply_shares, borrow_shares, collateral_assets (shares, not assets) |
| Read a user's Blue position history | /v0/blue/markets/{market-selector}/users/{user-address}/position/history | data[] of timestamp, supply_shares, borrow_shares, collateral_assets |
| Read a user's Blue position performance | /v0/blue/markets/{market-selector}/users/{user-address}/position/performance | supply_net_earnings_assets, supply_return_on_capital, borrow_net_cost_assets, borrow_cost_on_capital |
| List Midnight books | /v0/midnight/books | data[] 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-offers | data[] 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-offers | Same 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}/positions | data[] 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}/price | price (USD number), provider, timestamp; decimals, symbol and logo_uri come from /v0/tokens/{token-selector} |
| List supported chains | /v0/chains | data[] 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}/stateand/v1/vaults-v2/{vault-selector}/apy-averages; their/v0versions don't exist. Vault V1 uses/v0for both. - No REST route returns an instantaneous APY.
/apy-averagesand/apy/historyare realized look-back values; label them with their window. - Amounts are integer strings: keep them as
BigIntuntil 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.addressand nest the asset asdata.asset(address,decimals,symbol); only list items havevault_addressand a flatasset_address. - Activity items use
tx_hash, nothashortransaction_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:
0x04422053aDDbc9bB2759b248B574e3FCA76Bc145in the Earn tutorials is an Ethereum vault (1:), while8453:0x050cE30b927Da55177A4914EC73480238BAD56f0is 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.