xyz.spiralstake/leverage

Official7 toolsLive

by spiral-stake · TypeScript

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

xyz.spiralstake/leverage MCP Server

The xyz.spiralstake/leverage server provides a leveraged-yield router on Morpho. It lists strategies, simulates outcomes, and builds UNSIGNED transactions. It also operates as a read-data backbone for Spiral Stake strategy data by composing and serving JSON for multiple consumers.

🛠️ Key Features

Leveraged-yield routing on Morpho
Strategy listing
Simulation
Build UNSIGNED transactions
Read-only strategy-data composition and JSON serving

🚀 Use Cases

Discover available Morpho leveraged-yield strategies
Run simulations for strategy evaluation
Prepare unsigned transactions for downstream signing or execution

⚡ Developer Benefits

Centralizes strategy-data composition server-side
Provides a like-for-like read surface for the app
Supports agents via a frozen /strategies read contract
Enables future versioned REST surface (OpenAPI) for partners

⚠️ Limitations

Read-only: no contract writes, signing, or private keys
Does not build or execute signed transactions (only UNSIGNED txs)

Captured live from the server via tools/list.

list_strategies

List eligible Spiral leveraged-yield strategies with raw risk facts (collateral/borrow APY, leverage ladder, oracle type, exit-liquidity, LTVs). Optionally filter by collateral category.

Parameters2

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.

Raw schema

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "description": "Filter by collateral category, e.g. 'stable', 'ETH', 'BTC', 'stable-PT'."
    },
    "chainId": {
      "type": "integer",
      "description": "Chain to target. Supported: 1, 4663. Default: 1."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_strategy

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

Parameters2

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

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Morpho market id (0x followed by 64 hex chars)."
    },
    "chainId": {
      "type": "integer",
      "description": "Chain to target. Supported: 1, 4663. Default: 1."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_prices

Current USD prices for loan/collateral tokens (token address -> USD).

Parameters1

chainId

integer

optional

Chain to target. Supported: 1, 4663. Default: 1.

Raw schema

{
  "type": "object",
  "properties": {
    "chainId": {
      "type": "integer",
      "description": "Chain to target. Supported: 1, 4663. Default: 1."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters7

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.

Raw schema

{
  "type": "object",
  "properties": {
    "strategyId": {
      "type": "string",
      "description": "Morpho market id of the strategy (from list_strategies / get_strategy)."
    },
    "payToken": {
      "type": "string",
      "description": "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": {
      "type": "string",
      "description": "Amount of payToken in human units (e.g. '10000' for 10,000 USDC)."
    },
    "leverage": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Target leverage, e.g. 3. Provide this OR desiredLtv."
    },
    "desiredLtv": {
      "type": "string",
      "description": "Target LTV percent, e.g. '66.67'. Provide this OR leverage."
    },
    "slippage": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Swap slippage as a ratio (0.005 = 0.5%). Default 0.005, capped at 0.01."
    },
    "chainId": {
      "type": "integer",
      "description": "Chain to target. Supported: 1, 4663. Default: 1."
    }
  },
  "required": [
    "strategyId",
    "payToken",
    "amount"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

build_leverage_tx

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. Returns { approvals[], tx{to,data,value} } plus the same position preview as simulate_leverage. Send any approvals first, then the tx. The embedded swap calldata is time-sensitive (see meta.expiresAt) — rebuild if it goes stale before signing.

Parameters8

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.

Raw schema

{
  "type": "object",
  "properties": {
    "strategyId": {
      "type": "string",
      "description": "Morpho market id of the strategy (from list_strategies / get_strategy)."
    },
    "payToken": {
      "type": "string",
      "description": "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": {
      "type": "string",
      "description": "Amount of payToken in human units (e.g. '10000' for 10,000 USDC)."
    },
    "leverage": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Target leverage, e.g. 3. Provide this OR desiredLtv."
    },
    "desiredLtv": {
      "type": "string",
      "description": "Target LTV percent, e.g. '66.67'. Provide this OR leverage."
    },
    "slippage": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Swap slippage as a ratio (0.005 = 0.5%). Default 0.005, capped at 0.01."
    },
    "chainId": {
      "type": "integer",
      "description": "Chain to target. Supported: 1, 4663. Default: 1."
    },
    "userAddress": {
      "type": "string",
      "description": "The wallet address that will sign and send. Approvals and onBehalfOf are built for it."
    }
  },
  "required": [
    "strategyId",
    "payToken",
    "amount",
    "userAddress"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters2

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

Raw schema

{
  "type": "object",
  "properties": {
    "userAddress": {
      "type": "string",
      "description": "Wallet address to read positions for."
    },
    "chainId": {
      "type": "integer",
      "description": "Chain to target. Supported: 1, 4663. Default: 1."
    }
  },
  "required": [
    "userAddress"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

build_manage_tx

Build the UNSIGNED transaction to adjust or close an OPEN position, for the given wallet to sign. Non-custodial (never signs/holds keys). Returns { approvals[], tx{to,data,value} }. 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.

Parameters10

userAddress	string	required	Wallet that owns the position and will sign.
id	integer	required	On-chain position index, from get_positions (its `id`).
action	string	required	What to do to the position.
amount	string	optional	Human-units amount. Required for add_collateral/remove_collateral/repay/borrow.
payToken	string	optional	Token to pay in (add_collateral/repay). Collateral/loan = direct; any other = zapped. ETH = zero address.
full	boolean	optional	repay only: clear the entire remaining debt.
desiredLtv	string	optional	increase_leverage: target LTV percent (e.g. '80'). Provide this OR leverage.
leverage	number	optional	increase_leverage: target leverage. Provide this OR desiredLtv.
slippage	number	optional	Swap slippage ratio (0.005 = 0.5%). Default 0.005, capped at 0.01.
chainId	integer	optional	Chain to target. Supported: 1, 4663. Default: 1.

Raw schema

{
  "type": "object",
  "properties": {
    "userAddress": {
      "type": "string",
      "description": "Wallet that owns the position and will sign."
    },
    "id": {
      "type": "integer",
      "minimum": 0,
      "description": "On-chain position index, from get_positions (its `id`)."
    },
    "action": {
      "type": "string",
      "enum": [
        "close",
        "increase_leverage",
        "add_collateral",
        "remove_collateral",
        "repay",
        "borrow"
      ],
      "description": "What to do to the position."
    },
    "amount": {
      "type": "string",
      "description": "Human-units amount. Required for add_collateral/remove_collateral/repay/borrow."
    },
    "payToken": {
      "type": "string",
      "description": "Token to pay in (add_collateral/repay). Collateral/loan = direct; any other = zapped. ETH = zero address."
    },
    "full": {
      "type": "boolean",
      "description": "repay only: clear the entire remaining debt."
    },
    "desiredLtv": {
      "type": "string",
      "description": "increase_leverage: target LTV percent (e.g. '80'). Provide this OR leverage."
    },
    "leverage": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "increase_leverage: target leverage. Provide this OR desiredLtv."
    },
    "slippage": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Swap slippage ratio (0.005 = 0.5%). Default 0.005, capped at 0.01."
    },
    "chainId": {
      "type": "integer",
      "description": "Chain to target. Supported: 1, 4663. Default: 1."
    }
  },
  "required": [
    "userAddress",
    "id",
    "action"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md7 KBView on GitHub

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)
`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, 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.

Install

Tools (7)

list_strategiesget_strategyget_pricessimulate_leveragebuild_leverage_txget_positionsbuild_manage_tx

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://api.spiralstake.xyz/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "leverage": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.spiralstake.xyz/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

xyz.spiralstake/leverage MCP Server

🛠️ 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

Related servers

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