lend-endpoints.md

Lending (Money Market) API Endpoints

All responses are wrapped in { "success": true, "data": ... }. Error responses: { "success": false, "message": "..." } with HTTP 400.

---

GET /mm/snapshot

Aggregate market totals for a chain. Maps to LendGlobalMetrics / LendChain.globalMetrics.

Params

Param	Required	Description
blockchainId	yes	Chain ID (e.g. 146)

Response

{
  "chain_id": 146,
  "total_market_size_usd": "1250000.00",
  "total_available_usd": "450000.00",
  "total_borrows_usd": "800000.00",
  "by_asset": [
    {
      "asset": "0x29219dd400f2Bf60E5a23d13Be72B486D4038894",
      "total_supplied_usd": "1250000.00",
      "total_borrowed_usd": "800000.00",
      "available_usd": "450000.00",
      "supply_cap_units": "5000000",
      "supply_cap_usd": "5000000.00",
      "borrow_cap_units": "3000000",
      "borrow_cap_usd": "3000000.00",
      "liquidation_threshold_bps": 8500,
      "liquidation_penalty_bps": 500,
      "reserve_factor_bps": 1000,
      "last_updated": "2026-02-19T12:00:00Z"
    }
  ],
  "last_updated": "2026-02-19T12:00:00Z"
}

Mapping to MOCK_LEND_DATA

• total_market_size_usd → globalMetrics.totalSuppliedUsd
• total_available_usd → globalMetrics.totalAvailableUsd
• total_borrows_usd → globalMetrics.totalBorrowedUsd
• by_asset[].total_supplied_usd → assets[].globalMetrics.totalSuppliedUsd
• by_asset[].total_borrowed_usd → assets[].globalMetrics.totalBorrowedUsd
• by_asset[].available_usd → assets[].globalMetrics.totalAvailableUsd

---

GET /mm/assets

Lists supported lending tokens and their on-chain config/state. Maps to the asset-level metadata in MOCK_LEND_DATA.

Params

Param	Required	Description
blockchainId	yes	Chain ID

Response

{
  "assets": [
    {
      "chain_id": 146,
      "token_address": "0x29219dd400f2Bf60E5a23d13Be72B486D4038894",
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6,
      "collateral_enabled": true,
      "ltv_bps": 8000,
      "irm": "0x3642839053780cdB43471bC868F721ea6B55022D",
      "oracle": "0xc379376069f1BCD776494C7BAb2aFb10DA6153d2",
      "is_stable": true,
      "is_blue_chip_or_native_asset_correlated": false,
      "last_updated": "2026-02-19T12:00:00Z"
    }
  ]
}

Mapping to MOCK_LEND_DATA

• token_address → assets[].address
• symbol → assets[].symbol
• name → assets[].name
• decimals → assets[].decimals
• collateral_enabled → assets[].isSuppliable
• All lending tokens are borrowable → isBorrowable: true

---

GET /mm/{address}/snapshot

Per-asset market snapshot. Gives caps, thresholds, and totals for a single token.

Params

Param	Required	Description
blockchainId	yes	Chain ID
address	yes	Token address (path param)

Response

Same shape as a single by_asset entry from /mm/snapshot.

---

GET /mm/{address}/series

Historical time series for a lending token.

Params

Param	Required	Description
blockchainId	yes	Chain ID
address	yes	Token address (path param)
interval	yes	1h or 1d
from	yes	Start timestamp (unix seconds)
to	yes	End timestamp (unix seconds)

Response

{
  "asset": "0x29219dd400f2Bf60E5a23d13Be72B486D4038894",
  "series": {
    "supply_apr": [{ "timestamp": "1708300800", "value": "0.0402" }],
    "borrow_apr": [{ "timestamp": "1708300800", "value": "0.0513" }],
    "utilization": [{ "timestamp": "1708300800", "value": "0.64" }],
    "total_supplied_usd": [{ "timestamp": "1708300800", "value": "1250000" }],
    "total_borrowed_usd": [{ "timestamp": "1708300800", "value": "800000" }],
    "price_usd": [{ "timestamp": "1708300800", "value": "1.0001" }]
  },
  "averages": {
    "supply_apr": "0.0395",
    "borrow_apr": "0.0510",
    "utilization": "0.62",
    "total_supplied_usd": "1200000",
    "total_borrowed_usd": "780000",
    "price_usd": "1.0000"
  }
}

Note: APR values are decimals (0.0402 = 4.02%). Multiply by 100 for percentage display.

---

GET /mm/asset/detail

Full detail for a single lending asset. Combines on-chain data, Redis snapshots, series, and optional user positions. This is the primary endpoint for the asset detail page (useLendAsset.tsx).

Already documented in the lend asset detail gist.

---

GET /mm/preview/hf/{action}

Preview health factor after a hypothetical action. Actions: deposit, withdraw, borrow, repay.

Params

Param	Required	Description
chainId	no	Chain ID (default 1)
user	yes	User wallet address
asset	yes	Token address
amount	yes	Amount in native units (wei)

Response

{
  "success": true,
  "chain_id": 146,
  "user": "0xabc...",
  "asset": "0x2921...",
  "amount": "1000000",
  "action": "deposit",
  "current_hf_bps": 18500,
  "projected_hf_bps": 22000,
  "coll_usd": "500000000000000000000",
  "debt_usd": "270000000000000000000",
  "new_coll_usd": "501000000000000000000",
  "new_debt_usd": "270000000000000000000"
}

• current_hf_bps / projected_hf_bps: health factor in basis points (18500 = 1.85)
• coll_usd / debt_usd: WAD-scaled (1e18) USD values
• Maps to userMetrics.healthFactor (divide bps by 10000)

---

Composing useLendData.tsx from these endpoints

// Fetch global overview for a chain
const snapshot = await fetch(`/mm/snapshot?blockchainId=${chainId}`);
const assets = await fetch(`/mm/assets?blockchainId=${chainId}`);

// Map to LendChain shape:
const chain: LendChain = {
  chainId,
  chainName: "Sonic",
  globalMetrics: {
    totalSuppliedUsd: parseFloat(snapshot.total_market_size_usd),
    totalAvailableUsd: parseFloat(snapshot.total_available_usd),
    totalBorrowedUsd: parseFloat(snapshot.total_borrows_usd),
    totalEarningsUsd: 0, // not yet tracked
  },
  assets: assets.assets.map(asset => {
    const byAsset = snapshot.by_asset.find(b => b.asset === asset.token_address);
    return {
      address: asset.token_address,
      symbol: asset.symbol,
      name: asset.name,
      decimals: asset.decimals,
      isSuppliable: asset.collateral_enabled,
      isBorrowable: true,
      tokenprice: 0,         // use /mm/asset/detail for price
      supplyApyPct: 0,       // use /mm/asset/detail for APY
      borrowApyPct: 0,       // use /mm/asset/detail for APY
      globalMetrics: {
        totalSupplied: 0,
        totalSuppliedUsd: parseFloat(byAsset?.total_supplied_usd ?? "0"),
        totalAvailable: 0,
        totalAvailableUsd: parseFloat(byAsset?.available_usd ?? "0"),
        totalBorrowed: 0,
        totalBorrowedUsd: parseFloat(byAsset?.total_borrowed_usd ?? "0"),
        totalEarnings: 0,
        totalEarningsUsd: 0,
      },
    };
  }),
};

// For user-specific data (health factor, positions):
const hf = await fetch(`/mm/preview/hf/deposit?chainId=${chainId}&user=${addr}&asset=${asset}&amount=0`);
// hf.current_hf_bps / 10000 → healthFactor

// For per-asset APY, price, user positions:
const detail = await fetch(`/mm/asset/detail?chainId=${chainId}&symbol=USDC&user=${addr}`);

Supported Tokens

• Sonic (146): USDC, wS