Leveraged-yield router on Morpho. List strategies, simulate, and build UNSIGNED txs.

🛠️ Key Features

toolCount: 7
Read-only MCP data backbone for Spiral Stake strategy data
Serves JSON for app, agents, and future partners
No contract writes, signing, or private keys required
Server-side data composition of client-side data

🚀 Use Cases

Retrieve the complete read surface for swap-like operations
Access a frozen strategies contract reference for agent integration
Expose a versioned, self-documenting REST surface (OpenAPI) for partners

⚡ Developer Benefits

Centralized read API for strategy data
Ground truth data composition from client-side to server-side
Easy integration for app, agents, and partner workflows
Clear separation of read-only data from signing or tx-building

⚠️ Limitations

Read-only: no write, tx-building, or key management
Data provenance limited to readmeExcerpt; future extensions may expand endpoints

Spiral Stake — `mcp` read-data backbone (Step 1a)

The composition authority + read API for Spiral Stake strategy data. It ports the app's client-side data composition server-side and serves it back as JSON, so three consumers run off one core:

The app — the complete read surface it currently fetches, for a like-for-like Step-2 swap.
Agents — the frozen /strategies contract.
Partners (later) — a clean, versioned, self-documenting REST surface (OpenAPI).

Read-only. No contract writes, no tx building, no signing, no private keys. It composes numbers and serves JSON. The MCP tool layer, execution/build_*, and partner auth are later steps — the seams are pre-cut (core + http) but not built.

Architecture

code

src/
  core/        pure composition — no I/O, unit-testable
    leverage.ts        ← VERBATIM copy of v2-client/src/utils/leverage.ts (byte-diff gated)
    apy.ts             collateral-APY resolution (Pendle/DeFiLlama/Royco/StableWatch/on-chain)
    leverageApy.ts     30/60/90d leveraged-APY windows + lumpy-token smoothing
    compose.ts         Market assembly from warm raw (port of FlashLeverage.createInstance)
    strategy.ts        Market → frozen /strategies contract (ladder, freshness, spiralHints)
    exitLiquidity.ts   exit-liquidity tier (the single verdict) + thresholds
  sources/     one adapter per upstream (fetch + parse). native fetch + viem; no axios/wagmi
  cache/       two-layer cache — RAW store (last-good) + warming policy (CONTRACT cadences)
  warmer/      background scheduler (stale-while-revalidate); reads NEVER fetch
  http/        thin hono REST layer (the only thing that knows about requests)
  data/        static market config (copied from the app) + readMarkets port
  config/      env (validated) + structured logger with correlation ids

Data flow: warmer fetches upstreams on the CONTRACT cadence → writes raw to the cache (last-good on failure) → core composes strategies from warm raw only → http serves them. A stale/failed upstream serves last-good with a visible stale age per field-group — never dropped, never coerced to 0.

Run

bash

cp .env.example .env      # fill in RPC + API keys (secrets via env only)
npm install
npm run dev               # tsx watch; serves on :$PORT (default 8787)
npm test                  # golden + parity gates
npm run typecheck         # tsc --noEmit
npm run openapi           # (re)emit openapi.json
node --import tsx scripts/smoke.ts   # live: prime + print one composed strategy

/health (liveness + cache diagnostics) and /ready (503 until the warmer primes the required data) are available immediately on boot.

Endpoints — app-read inventory → endpoint mapping

Every data read the app performs in v2-client/src/api-services/* maps to an endpoint here (positions stay on the dashboard backend and are not reimplemented):

App read (`api-services/*`)	mcp endpoint
`getTokenApy`, `getAllMorphoMarketsData`, `fetchMerklSpotIncentives`, prices, on-chain value → composed markets	`GET /v1/strategies`, `GET /v1/strategies/:id`
`FlashLeverage.createInstance` → the app's full client-side `Market[]` composition	`GET /v1/app/markets` (raw domain model; `BigNumber`→`{"$bn":…}`, `bigint`→`{"$bigint":…}` — revive before use)
`morpho.ts` `getAllBorrowApyHistories` / `getBorrowApyHistory`	`GET /v1/markets/borrow-apy-history`, `GET /v1/markets/:id/borrow-apy-history`
`apy.ts` `resolveTokenApyHistory` (DeFiLlama/Royco/StableWatch history), `chart.ts` `getApyChart`	`GET /v1/collateral/apy-history`, `GET /v1/collateral/:id/apy-history`
`merkl.ts` `fetchMerklIncentiveData` (borrow-incentive APR history)	`GET /v1/markets/:id/incentive-history`
`token.ts` `getAllLoanTokenPrices` / `getTokenPrice`	`GET /v1/prices`
`chart.ts` `getMarketChart` (CoinGecko price chart)	`GET /v1/prices/chart?coinId=&days=&currency=` (on-demand proxy)
`dashboard.ts` `getApySnapshot` (StableWatch stable APY)	`GET /v1/stable-apy` — fetched directly from StableWatch as a warmed upstream; the mcp owns this data now and no longer depends on the dashboard `/apy` endpoint
swap/meta-dex aggregators, referral, positions	out of scope (execution / backend domains)

Cross-cutting: /v1 versioning, CORS limited to CORS_ORIGINS, a consistent error envelope ({ error: { code, message, correlationId } }), a correlation id per request (echoed as x-correlation-id), structured JSON logs, and an OpenAPI 3.1 spec at /openapi.json (+ committed openapi.json).

Parity gates

leverage.ts golden-vector — test/golden/leverage.golden.test.ts freezes fixed inputs → exact outputs; leverage.parity.test.ts asserts the file is a byte-for-byte copy of the app's leverage.ts. This locks every APY/LTV/ladder number to the app.
/strategies composition — test/parity/strategies.compose.test.ts seeds the raw cache with a controlled fixture and asserts the composed contract field-by-field (sourcing, LTV math, ladder via the verbatim leverage.ts, freshness cadences, null-vs-absent, spiralHints isolation). Runs offline in CI.
Live golden-set + app-surface parity — scripts/capture-parity.ts primes the warmer against real upstreams and writes the composed /strategies (+ apy/borrow histories) for a fixed market set to test/fixtures/. The parity diff vs the app is produced by feeding the same fixed inputs to the app's client-side composition and comparing (the app logs its composed markets); the PR commits the fixtures and the empty diff. This is the gate that lets us offload TVL safely.

Frozen decisions (parity-critical)

bignumber.js pinned to the app's 9.3.1; no global BigNumber.config change → toFixed(2) / rounding (ROUND_HALF_UP) identical.
On-chain reads via viem replace wagmi: getCollateralValueInLoanToken (multicall3), stUSDS str(), spUSDG vsr() (chain 4663). The app's (intentionally lossy) BigInt(liqLtv) from the JSON number is matched exactly, not "fixed".
maxLeverage = calcLeverage(maxLtv); defaultLeverage = calcLeverage(safeLtv), safeLtv = maxLtv% − 0.75 — exactly as the app derives them. Ladder = integer steps 1x … ⌊maxLeverage⌋ (LTV =(1 − 1/lev)·100) then the exact max.
Exit slippage is baked into collateralTokens.json by the app's weekly refresh script; its file mtime is the exitLiquidity.asOf. The tier (the only verdict) lives in spiralHints with its thresholds; raw slippagePct stays under exitLiquidity, null (no route) preserved.

category	string	optional	Filter by collateral category, e.g. 'stable', 'ETH', 'BTC', 'stable-PT'.
chainId	integer	optional	Chain to target. Supported: 1, 4663. Default: 1.

id	string	required	Morpho market id (0x followed by 64 hex chars).
chainId	integer	optional	Chain to target. Supported: 1, 4663. Default: 1.

strategyId	string	required	Morpho market id of the strategy (from list_strategies / get_strategy).
payToken	string	required	Address of the token you pay in. May be the collateral (opened directly) or any other token (zapped: swapped to collateral first). Native ETH = the zero address 0x0000…0000.
amount	string	required	Amount of payToken in human units (e.g. '10000' for 10,000 USDC).
leverage	number	optional	Target leverage, e.g. 3. Provide this OR desiredLtv.
desiredLtv	string	optional	Target LTV percent, e.g. '66.67'. Provide this OR leverage.
slippage	number	optional	Swap slippage as a ratio (0.005 = 0.5%). Default 0.005, capped at 0.01.
chainId	integer	optional	Chain to target. Supported: 1, 4663. Default: 1.

strategyId	string	required	Morpho market id of the strategy (from list_strategies / get_strategy).
payToken	string	required	Address of the token you pay in. May be the collateral (opened directly) or any other token (zapped: swapped to collateral first). Native ETH = the zero address 0x0000…0000.
amount	string	required	Amount of payToken in human units (e.g. '10000' for 10,000 USDC).
leverage	number	optional	Target leverage, e.g. 3. Provide this OR desiredLtv.
desiredLtv	string	optional	Target LTV percent, e.g. '66.67'. Provide this OR leverage.
slippage	number	optional	Swap slippage as a ratio (0.005 = 0.5%). Default 0.005, capped at 0.01.
chainId	integer	optional	Chain to target. Supported: 1, 4663. Default: 1.
userAddress	string	required	The wallet address that will sign and send. Approvals and onBehalfOf are built for it.

userAddress	string	required	Wallet address to read positions for.
chainId	integer	optional	Chain to target. Supported: 1, 4663. Default: 1.

Leverage

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

list_strategies

get_strategy

get_prices

simulate_leverage

build_leverage_tx

get_positions

build_manage_tx

Spiral Stake — `mcp` read-data backbone (Step 1a)

Architecture

Run

Endpoints — app-read inventory → endpoint mapping

Parity gates

Frozen decisions (parity-critical)

Install

Remote endpoint

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

list_strategies

get_strategy

get_prices

simulate_leverage

build_leverage_tx

get_positions

build_manage_tx

Spiral Stake — mcp read-data backbone (Step 1a)

Architecture

Run

Endpoints — app-read inventory → endpoint mapping

Parity gates

Frozen decisions (parity-critical)

Install

Remote endpoint

Spiral Stake — `mcp` read-data backbone (Step 1a)