Leverage

xyz.spiralstakePublished by spiralstake.xyzOfficial publisherv0.1.1Updated Oct 24, 2026

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

VerifiedStreamable HTTPWeb executableFinanceDeveloper Tools

Overview

AI-generated overview

Leverage is a remote MCP server for Spiral Stake's leveraged-yield strategies on Morpho: it lists strategies, prices tokens, simulates positions and builds UNSG

What you can do
List and inspect eligible Spiral strategies on supported chains, with raw risk facts such as APYs, leverage ladder, oracle type, LTVs and exit liquidity, by chain or by Morpho market id. Fetch current USD prices for the loan and collateral tokens the strategies use. Simulate opening a leveraged position or depositing into a stock-plus-yield equity vault, read-only and without a wallet. Read a wallet's open and closed positions from chain state, including LTV, headroom, leverage and net value. Build unsigned transactions or call batches to open, adjust, close or unwind positions, for the user to sign.
When to use it
Useful when an assistant needs to research or compare Spiral Stake leveraged-yield strategies, preview leverage and equity-vault outcomes, or prepare unsigned transactions for a user to sign in their own wallet. Not needed for plain token prices or unrelated DeFi work.
Requirements
A remote streamable HTTP endpoint; no package install. No authentication, environment variables or headers are declared. The server reads chain state and upstream price and APY sources, so network access is required. Signing and broadcasting happen in the user's own wallet, not here.
Before you install
The build tools produce real transactions that move funds and involve borrowing and leverage; the user must review and sign them in their own wallet. Positions carry liquidation risk, and the server reports LTV and headroom but does not manage risk. Simulations are previews, not guarantees. Prices and APYs come from third-party sources and may be stale. The server states it never signs, sends or holds keys.

Installation

In SourceWeft

  1. Open Leverage in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/xyz.spiralstake%2Fleverage/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "leverage": {
      "type": "http",
      "url": "https://api.spiralstake.xyz/mcp"
    }
  }
}

README

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:

  1. The app — the complete read surface it currently fetches, for a like-for-like Step-2 swap.
  2. Agents — the frozen /strategies contract.
  3. 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

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 installnpm run dev               # tsx watch; serves on :$PORT (default 8787)npm test                  # golden + parity gatesnpm run typecheck         # tsc --noEmitnpm run openapi           # (re)emit openapi.jsonnode --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 marketsGET /v1/strategies, GET /v1/strategies/:id
FlashLeverage.createInstance → the app's full client-side Market[] compositionGET /v1/app/markets (raw domain model; BigNumber→{"$bn":…}, bigint→{"$bigint":…} — revive before use)
morpho.ts getAllBorrowApyHistories / getBorrowApyHistoryGET /v1/markets/borrow-apy-history, GET /v1/markets/:id/borrow-apy-history
apy.ts resolveTokenApyHistory (DeFiLlama/Royco/StableWatch history), chart.ts getApyChartGET /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 / getTokenPriceGET /v1/prices
chart.ts getMarketChart (CoinGecko price chart)GET /v1/prices/chart?coinId=&days=&currency= (on-demand proxy)
chart.ts getDexOhlcv (DEX price chart for tokens with no CoinGecko/TradingView chart, e.g. CASHCAT/PONS on Robinhood)GET /v1/prices/ohlcv?chainId=&token=&timeframe=&aggregate=&limit= (on-demand GeckoTerminal proxy, 30s cache, last-good on failure; COINGECKO_PRO_API_KEY lifts the rate limit)
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
— (protocol-level, not an app read)GET /v1/tvl — protocol TVL across all supported chains, warmed every 5m from on-chain positions: tvlUsd = net user equity (collateral − debt, the DefiLlama TVL), grossTvlUsd = total looped collateral, borrowedUsd = total debt, plus positions/users; 503 until the first chain is computed
swap/meta-dex aggregators, referral, positionsout 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

  1. 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.
  2. /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.
  3. 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.

Source: README.md at commit 914e845

Tools

10

list_strategies

List Strategies

List eligible Spiral strategies on a chain with raw risk facts (collateral/borrow APY, leverage ladder, oracle type, exit liquidity, LTVs, curator). Mainnet (1): correlated yield loops on stables, ETH, BTC and Pendle PTs. Robinhood Chain (4663): stable loops on USDG, directional perps (spiralHints.profile 'leveraged_perp' — APYs are financing carry only) and stock + yield equity vaults (profile 'equity_yield_vault', ids start with 'equity-'). Optionally filter by collateral category.

ParameterschainIdcategory

get_strategy

Get Strategy

Get one eligible strategy's full raw facts by its Morpho market id.

ParametersidrequiredchainId

get_prices

Get Prices

Current USD prices of every loan and collateral token the chain's strategies use (token address -> USD), including equity-vault stocks. Loan tokens are priced from CoinGecko; collateral from the market oracle × its loan token's price — the same figures the strategies' priceUsd fields carry.

ParameterschainId

simulate_leverage

Simulate Leverage

Preview opening a leveraged position — deterministic, read-only, no wallet needed. Returns the resulting leverage, effective LTV, leveraged collateral, expected leveraged APY, price impact, the auto-selected execution path, flash-loan size, and (if the flash loan exceeds direct market liquidity) the public-allocator reallocation fee. Numbers move with market prices.

ParametersamountrequiredchainIdleveragepayTokenrequiredslippagedesiredLtvstrategyIdrequired

build_leverage_tx

Build Leverage Transaction

Build the UNSIGNED transaction to open a leveraged position, for the given wallet to sign. Non-custodial: this server never signs, sends, or holds keys. The canonical output is the executable { approvals[], tx{to,data,value} } — sign and broadcast it directly (approvals first), plus the same position preview as simulate_leverage. meta.signingUrl is an optional one-click link for a human to sign in their own wallet. The embedded swap calldata is time-sensitive (see meta.expiresAt) — rebuild if stale.

ParametersamountrequiredchainIdleveragepayTokenrequiredslippagedesiredLtvstrategyIdrequireduserAddressrequired

get_positions

Get Positions

Read a wallet's open/closed Spiral leverage positions from chain state (read-only). For each: collateral/loan, leveraged collateral, net equity, debt, current LTV vs liquidation LTV (with headroom), current leverage, net USD value, and current leveraged APY. No cost-basis / realized P&L (those need off-chain history). Newest first. `equityPositions` lists the wallet's open equity vaults (stock leg + the yield loop(s) it funds); those loops are excluded from `positions`.

ParameterschainIduserAddressrequired

build_manage_tx

Build Manage Transaction

Build the UNSIGNED transaction to adjust or close an OPEN position, for the given wallet to sign. Non-custodial (never signs/holds keys). Canonical output is the executable { approvals[], tx{to,data,value} } (sign/broadcast directly); meta.signingUrl is an optional link for a human to sign in their own wallet. Actions: 'close' (unwind fully), 'increase_leverage' (borrow to a higher LTV), 'add_collateral' (top up — pay in collateral or any token), 'remove_collateral' (withdraw), 'repay' (pay down debt; set full=true to clear it), 'borrow' (draw more loan token). Get the position `id` from get_positions. Swap calldata (close/increase/zap paths) is time-sensitive — see meta.expiresAt.

ParametersidrequiredfullactionrequiredamountchainIdleveragepayTokenslippagedesiredLtvuserAddressrequired

simulate_equity_deposit

Simulate Equity Vault Deposit

Preview depositing USDG into a stock + yield equity vault — deterministic, read-only, no wallet. You end up 1x long the stock (held as your own Morpho collateral), with `stockLtvPct` of its value borrowed as USDG and flash-looped into the vault's yield strategy. Returns the stock received, the borrow, the stock liquidation price and headroom, the yield leg's size/leverage/APY, the net APY at that LTV, fees and price impact per leg.

ParametersamountrequiredchainIdslippagestrategyIdrequiredstockLtvPct

build_equity_deposit_tx

Build Equity Vault Deposit

Build the UNSIGNED call batch to deposit into a stock + yield equity vault, for the given wallet to sign. Non-custodial. Returns `calls[]` (approve USDG → router, authorize the router on Morpho, the one-call equityEntry, revoke) to submit as ONE atomic batch (EIP-5792 wallet_sendCalls / Safe), plus the same preview as simulate_equity_deposit. meta.signingUrl is a one-click link for a human to sign in the app. Swap calldata is time-sensitive (meta.expiresAt).

ParametersamountrequiredchainIdslippagestrategyIdrequiredstockLtvPctuserAddressrequired

build_equity_exit_tx

Build Equity Vault Exit

Build the UNSIGNED call batch to fully unwind an OPEN equity vault (from get_positions.equityPositions): close each of its yield loops, then one self-funded router call repays the stock debt, withdraws the stock, swaps it to USDG and returns the proceeds. Submit as ONE atomic batch. Non-custodial; the vault's yield loop cannot be closed alone through build_manage_tx. Only the vault's own loop(s) are closed: those get_positions attributes unambiguously, or exactly the ones you pass in yieldPositionIds. Always read meta.closedYieldPositionIds.

ParameterschainIdslippagestrategyIdrequireduserAddressrequiredyieldPositionIds

Version history

1
  1. v0.1.1LatestSep 16, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.