# Chains Source: https://docs.spiralstake.xyz/agents/concepts/chains Targeting Ethereum or Robinhood Chain. Every tool accepts an optional `chainId`. The default is Ethereum mainnet. | chainId | Chain | | ------- | -------------------------- | | `1` | Ethereum mainnet (default) | | `4663` | Robinhood Chain | ```json theme={null} { "category": "stable", "chainId": 4663 } ``` Pass `chainId` to every tool to target that chain. An unsupported `chainId` fails closed with a clear error rather than silently defaulting. ## What each chain lists | | Ethereum (`1`) | Robinhood Chain (`4663`) | | ------------------------------------ | -------------------------------------- | ------------------------------------------------------------------------------------ | | Correlated yield loops | stables, ETH, BTC, Pendle PTs | spUSDG / syrupUSDG / USDe against USDG | | Directional perps (`leveraged_perp`) | wstETH, cbBTC, XAUt … against stables | PONS, CASHCAT against USDG | | Stock + yield equity vaults | — | SPY, NVDA, TSLA, SPCX, AAPL (see the [guide](/agents/guides/stock-plus-yield-vault)) | | Exit liquidity is measured into | USDC (`direction: collateral_to_usdc`) | USDG (`collateral_to_usdg`) | Robinhood Chain is young: its perp markets can list with very little borrowable liquidity (`liquidityUsd`), and an open larger than that reverts. Read `liquidityUsd` before sizing. Position indices (`id` in `get_positions` / `build_manage_tx`) are **per-chain** — id `0` on Ethereum is a different position from id `0` on Robinhood. Each position's `positionId` (`${chainId}-${strategyId}-${id}`) is globally unique. # Non-custodial execution Source: https://docs.spiralstake.xyz/agents/concepts/non-custodial How the build tools produce transactions without ever touching keys. Spiral's execution tools are **non-custodial**. The server never signs, sends, or holds keys — it only *constructs* the transaction the user's own wallet will sign. ## The output of a build `build_leverage_tx` and `build_manage_tx` return: ```json theme={null} { "path": "swapAndLeverage", "approvals": [{ "to": "0x…token", "data": "0x…" }], "tx": { "to": "0x…contract", "data": "0x…", "value": "0" }, "meta": { "positionPreview": { "leverage": "3.0", "effectiveLtv": "66.7", "expectedLeverageApy": "5.64" }, "amountFlashLoan": "…", "minTokenOut": "…", "expiresAt": "2026-01-01T00:00:00.000Z", "signingUrl": "https://app.spiralstake.xyz/…" } } ``` ## Two ways to execute Send `approvals[]` first (if any), then `tx`, from `userAddress` — with any wallet, signer library, or Safe. This is the canonical path. Open `meta.signingUrl` — a one-click link into the Spiral app, prefilled, so a person reviews and signs in their own wallet. ## Safety built into every bundle * **Approvals are exact** — scoped to the precise contract that pulls the funds, for the exact amount (never infinite). * **Every swap carries a `minTokenOut` floor** (≥ 99% of the quote; slippage capped at 1%) — it can't be sandwiched to zero. * **The tx targets the market you chose** and `onBehalfOf` is the signer's address. * **`meta.expiresAt`** — the embedded swap calldata is time-sensitive (\~60s). Rebuild if it lapses before signing. Building a transaction for an address you don't control is inert — it can't be signed without that wallet's key, and it reveals only on-chain-public data. # Oracle & exit liquidity Source: https://docs.spiralstake.xyz/agents/concepts/oracle-and-liquidity The two facts that most determine a leveraged position's risk. ## Oracle type Every market prices collateral through an oracle. The **type** decides how a depeg affects you: Prices by redemption / net asset value. A DEX depeg **won't** liquidate you — the position tracks the collateral's underlying value. Prices from a market feed. A depeg **can** liquidate you even if the collateral still redeems 1:1. Weigh against `ltvPct.liquidation` headroom. Every perp and every stock vault is `market` (API3 / Uniswap TWAP / Chainlink feeds): a price fall liquidates. For a correlated stable loop with a `nav` oracle, liquidation risk largely collapses to a single question: *does the collateral hold its peg?* That's the same risk a passive lender in the same market already carries. ## Exit liquidity `exitLiquidity.slippagePct` is measured **per USD size**, selling the collateral into the chain's stable (`direction`: USDC on Ethereum, USDG on Robinhood Chain). An equity vault's exit liquidity is its stock token's — the vault exits by selling the stock. * A number is the slippage to unwind at that size (negative = price improvement). * `null` = no route at that size. * `maxLeverage` is derived from this — it's a **liquidity** bound, not a safety bound. High headline APY on a `market`-oracle strategy with thin exit liquidity is a trap: the yield is real on paper but unreachable at size, and the position can liquidate on a temporary depeg. Always read oracle type and exit liquidity together. ## If exit liquidity dries up A one-shot [`close`](/agents/tools/build-manage-tx) swaps the **full** leveraged collateral back to the loan token, so it needs a live route. If that route disappears, the build **fails closed** with a clear error — you get an error, never a broken transaction. **You are never trapped.** Two actions need **no swap route at all**: 1. **`repay`** — paying in the loan token clears the debt directly (no swap). 2. **`remove_collateral`** — withdraws the collateral **in-kind** (no swap). Repay the debt with your own funds, then withdraw the collateral as the collateral token. This unwind works regardless of exit liquidity — it never touches the collateral's market. The one prerequisite is having funds to repay with. If you don't, you're dependent on the collateral's route (or liquidation) — which is exactly why [`get_positions`](/agents/tools/get-positions) reports **exit health per position**, so you can act while a route still exists. ## Watch it per position, not per market A market can be "deep" while *your* position is still larger than the depth that exits cleanly. `get_positions` returns `exitLiquidity` for each position — including `exceedsCleanExitSize` — measured against that position's **full unwind notional** (closing swaps all the collateral, not just your equity). Poll it and unwind early rather than discovering the problem when `close` throws. # Strategies & risk facts Source: https://docs.spiralstake.xyz/agents/concepts/strategies What a strategy is and how to read the raw facts an agent reasons over. A **strategy** is a Morpho market Spiral can leverage, identified by its `id` (the Morpho market id, `0x` + 64 hex — or `equity-` + a market id for a vault). `list_strategies` and `get_strategy` return raw, unit-labeled facts — never a score. ## The three profiles | Profile | How to recognise it | What `leverageApyPct` means | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Correlated yield loop** | `correlated: true`, no `spiralHints.profile` | The levered yield: `(collateralApyPct + collateralIncentive.aprPct) × leverage − netBorrowApyPct × (leverage − 1)`. | | **Directional perp** | `correlated: false`, `spiralHints.profile.value = "leveraged_perp"` | The same formula on a collateral that earns \~0: the annualised **financing carry**, typically negative. The collateral's price move, which dominates P\&L, is not in it. | | **Stock + yield equity vault** | `id` starts with `equity-`, `collateral.category = "stocks"`, `spiralHints.profile.value = "equity_yield_vault"` | The **net dollar APY on the deposit** at the vault's default stock-leg LTV — not a user-selectable leverage. You stay 1x long the stock. | Two vaults can share a ticker (Longbow's NVDA and NetNet Credit's). `curator` names who curates the market the collateral sits on, and `collateral.description` says it in words — use them to tell such strategies apart. ## The core facts | Field | Meaning | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `collateralApyPct` / `borrowApyPct` | The yield the collateral earns vs. the cost to borrow. | | `netBorrowApyPct` | Borrow APY minus any borrow incentives. | | `leverageLadder` | `leverage → leverageApyPct` at each rung. **Read this — don't infer APY from carry.** | | `maxLeverage` | A **liquidity** bound (how much you can route through swaps), not a safety bound. | | `ltvPct.liquidation` / `ltvPct.max` | Liquidation LTV and the safe ceiling Spiral opens up to. | | `oracle` | `nav` or `market` — see [Oracle & liquidity](/agents/concepts/oracle-and-liquidity). | | `exitLiquidity` | Slippage to unwind, measured per USD size. | | `correlated` | Whether the pair tracks (leveraged yield) or diverges (perp). | | `curator` | Who curates the market — present only on partner-curated markets (equity vaults, Longbow's perps). | | `collateral.description` | Plain-English account of what the collateral is and how it earns. | | `historicalLeverageApyPct` | Trailing 30/60/90-day levered APY. **Absent** when the market has no history (young markets, every equity vault) — absent means unmeasured, not 0. | | `links.market` | The market's own page — Morpho, longbow\.cash or NetNet Credit. | ## Reading carry correctly `carry = collateralApyPct − netBorrowApyPct`, and leverage multiplies it. But **negative carry can still leave a positive `leverageApyPct`**, because the 1x base yield dominates at low leverage. Always read the `leverageLadder` rather than computing from carry alone. ## Eligibility `list_strategies` returns only **eligible** strategies — near-maturity (PT), no-swap-route, or zero-APY loops are hidden, and on Ethereum so are markets below the borrow-liquidity floor. Robinhood Chain keeps its young, thin markets listed, so read `liquidityUsd` there. A manual-exit market (no DEX route for its collateral) is app-only and never appears here. Numbers are a snapshot (`asOf`) and move with the market. Rebuild any transaction right before signing. # Claude Desktop Source: https://docs.spiralstake.xyz/agents/connect/claude-desktop Add the Spiral MCP to Claude Desktop. Claude Desktop connects to remote MCP servers through a small local proxy (`mcp-remote`). Claude Desktop → Settings → Developer → Edit Config. This opens `claude_desktop_config.json`. ```json claude_desktop_config.json theme={null} { "mcpServers": { "spiralstake": { "command": "npx", "args": ["mcp-remote", "https://api.spiralstake.xyz/mcp"] } } } ``` The Spiral tools appear in the tools menu. Ask: *"List Spiral's stable strategies."* `mcp-remote` bridges Claude Desktop (which speaks stdio) to the remote Streamable HTTP endpoint. It's fetched on demand via `npx` — no global install needed. # Cursor Source: https://docs.spiralstake.xyz/agents/connect/cursor Add the Spiral MCP to Cursor. Cursor supports remote MCP servers directly by URL. Create or edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` in your project. ```json .cursor/mcp.json theme={null} { "mcpServers": { "spiralstake": { "url": "https://api.spiralstake.xyz/mcp" } } } ``` Cursor → Settings → MCP → toggle **spiralstake** on. The ten tools appear in the agent. Ask Cursor's agent: *"Use Spiral to find the best stable yield and build a 3x open tx for 0x… "* — it will chain `list_strategies` → `simulate_leverage` → `build_leverage_tx`. # Other clients Source: https://docs.spiralstake.xyz/agents/connect/other-clients Connect any MCP client, the Inspector, or your own SDK. Any spec-compliant MCP client can connect over Streamable HTTP at `https://api.spiralstake.xyz/mcp`. ## MCP Inspector The fastest way to explore the tools interactively: ```bash theme={null} npx @modelcontextprotocol/inspector ``` In the UI: set **Transport** to `Streamable HTTP`, **URL** to `https://api.spiralstake.xyz/mcp`, then **Connect** → **List Tools**. ## Programmatic (TypeScript SDK) ```ts theme={null} import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; const client = new Client({ name: "my-agent", version: "1.0.0" }); await client.connect(new StreamableHTTPClientTransport(new URL("https://api.spiralstake.xyz/mcp"))); const tools = await client.listTools(); const call = async (name, args = {}) => JSON.parse((await client.callTool({ name, arguments: args })).content[0].text); const { strategies } = await call("list_strategies", { category: "stable" }); ``` The server is **stateless** (a fresh transport per request), so any Streamable-HTTP MCP client works — no session management required on your side. ## Prefer plain HTTP? If you're integrating a backend rather than an agent, the same capabilities are available as a keyed REST API. See the [Integration API](/integration/introduction). # Find the best yield Source: https://docs.spiralstake.xyz/agents/guides/find-the-best-yield Rank stable strategies by risk-adjusted leveraged APY. A worked example of the reasoning an agent should do — facts in, a defensible pick out. ```ts theme={null} const { strategies } = await call("list_strategies", { category: "stable" }); ``` Where the `leverageLadder` **rises** with leverage — those are the ones where leverage helps. Markets whose ladder goes negative are best at 1x only. Prefer `oracle.type === "nav"` (immune to DEX depegs) and deep `exitLiquidity` (low, flat `slippagePct` across sizes). Check `ltvPct.liquidation` headroom. ```ts theme={null} const sim = await call("simulate_leverage", { strategyId: pick.id, payToken: pick.loan.address, amount: "50000", leverage: 8, }); ``` ## What "best" looks like For a yield profile, the standout is usually a **positive-carry, `nav`-oracle stable pair with deep exit liquidity** — where every extra turn of leverage adds APY and the dominant risk is simply whether the collateral holds its peg. Beware deceptively high APY: a `market`-oracle pair showing 60%+ at high leverage but with exit slippage that explodes at size is unreachable in practice and liquidation-prone. The facts are all there — read them together. # Manage & close Source: https://docs.spiralstake.xyz/agents/guides/manage-and-close Adjust or unwind an existing position. Every adjustment uses [`build_manage_tx`](/agents/tools/build-manage-tx) against a position's on-chain `id` (from [`get_positions`](/agents/tools/get-positions)). ## Find the position ```ts theme={null} const { positions } = await call("get_positions", { userAddress: "0x…" }); const id = positions[0].id; ``` ## Adjust ```ts Add collateral theme={null} await call("build_manage_tx", { userAddress, id, action: "add_collateral", payToken: "0x…", amount: "5000" }); ``` ```ts Repay (full) theme={null} await call("build_manage_tx", { userAddress, id, action: "repay", payToken: "0x…", amount: "5000", full: true }); ``` ```ts Increase leverage theme={null} await call("build_manage_tx", { userAddress, id, action: "increase_leverage", desiredLtv: "75" }); ``` ```ts Withdraw / borrow theme={null} await call("build_manage_tx", { userAddress, id, action: "remove_collateral", amount: "1000" }); await call("build_manage_tx", { userAddress, id, action: "borrow", amount: "1000" }); ``` ## Close ```ts theme={null} const bundle = await call("build_manage_tx", { userAddress, id, action: "close" }); // Send bundle.tx — swaps all collateral back to the loan token, repays, returns the rest. ``` Each returns the same `{ approvals, tx, meta }` bundle — sign approvals first, then the tx. Verify with `get_positions` after it confirms. ## Unwinding when exit liquidity is gone `close` needs a live swap route. If it's gone the build **fails closed** — but you can still exit **in-kind**, because these two need **no swap**: ```ts theme={null} // Pay in the LOAN token → direct repay, no route needed await call("build_manage_tx", { userAddress, id, action: "repay", payToken: loanToken, amount: "…", full: true }); ``` ```ts theme={null} await call("build_manage_tx", { userAddress, id, action: "remove_collateral", amount: "…" }); ``` You exit holding the collateral token itself, never touching its market. Don't wait for `close` to throw. `get_positions` returns `exitLiquidity.exceedsCleanExitSize` per position — poll it and unwind while a route still exists. # Open a position Source: https://docs.spiralstake.xyz/agents/guides/open-a-position From a chosen strategy to a signed, on-chain leveraged position. ```ts theme={null} const sim = await call("simulate_leverage", { strategyId, payToken, amount: "50000", leverage: 8, }); ``` Confirm `positionPreview` — leverage, `effectiveLtv`, `expectedLeverageApy`, `priceImpactPct`. ```ts theme={null} const bundle = await call("build_leverage_tx", { strategyId, payToken, amount: "50000", leverage: 8, userAddress: "0x…", }); ``` * `bundle.tx.to` is the Spiral contract for that chain. * `bundle.approvals[].to` is the pay token. * `bundle.tx.value` is `0` for an ERC-20 pay (non-reallocate). Send `approvals[]` first (if any), then `tx`, from `userAddress`. Or hand the user `bundle.meta.signingUrl`. ```ts theme={null} const { positions } = await call("get_positions", { userAddress: "0x…" }); ``` Rebuild if `bundle.meta.expiresAt` passes before signing — the swap calldata is only valid for \~60 seconds. This flow is for loops and perps. A stock + yield equity vault (`id` starting with `equity-`) is entered with [`build_equity_deposit_tx`](/agents/tools/build-equity-deposit-tx) — see [Stock + yield vaults](/agents/guides/stock-plus-yield-vault). # Stock + yield vaults Source: https://docs.spiralstake.xyz/agents/guides/stock-plus-yield-vault Hold a tokenized stock 1x and farm a yield loop with the borrowed share — on Robinhood Chain. An **equity vault** is two legs the user holds directly, entered and exited as one atomic batch: 1. **Stock leg** — the USDG deposit is swapped to a Robinhood tokenized stock (SPY, NVDA, TSLA, SPCX, AAPL) and posted as the user's own collateral on a partner Morpho market (`curator`: Longbow or NetNet Credit). A share of its value — the stock-leg LTV, 50% by default — is borrowed back as USDG. 2. **Yield leg** — that USDG is flash-looped into a Spiral yield strategy (syrupUSDG/USDG) at the yield market's max-safe LTV. The user stays **1x long the stock** and earns the loop's leveraged yield on the borrowed share. A vault's `leverageApyPct` is therefore the **net dollar APY on the deposit** at the default stock LTV, not a leverage choice. ```ts theme={null} const { strategies } = await call("list_strategies", { category: "stocks", chainId: 4663 }); ``` Each vault carries `curator`, `collateral.description`, `oracle.type: "market"`, its stock's `exitLiquidity`, and `spiralHints.profile.leverageApyMeaning`. Two NVDA vaults exist — one per curator. ```ts theme={null} const sim = await call("simulate_equity_deposit", { strategyId: vault.id, amount: "10000", stockLtvPct: "50", chainId: 4663, }); ``` Read `stock.liquidationPriceUsd` and `priceDropToLiquidationPct` (the stock's fall to liquidation), `netApyPct`, and the fees. A higher `stockLtvPct` raises the net APY and shrinks the headroom; above the cap (`stock.maxLtvPct`) the call is refused. ```ts theme={null} const bundle = await call("build_equity_deposit_tx", { strategyId: vault.id, amount: "10000", stockLtvPct: "50", userAddress: "0x…", chainId: 4663, }); ``` Submit `bundle.calls` via EIP-5792 `wallet_sendCalls` (or a Safe), or hand the user `bundle.meta.signingUrl`. A wallet that cannot batch sends the calls in order and always sends the final revoke. ```ts theme={null} const { equityPositions } = await call("get_positions", { userAddress: "0x…", chainId: 4663 }); ``` Watch `stock.ltvHeadroomPct` / `priceDropToLiquidationPct` on the stock leg and `yieldLoops[].ltvPct` on the yield leg. ```ts theme={null} const exit = await call("build_equity_exit_tx", { strategyId: vault.id, userAddress: "0x…", chainId: 4663 }); ``` One batch closes the yield loop(s) and unwinds the stock leg; `meta.estimatedUsdgOut` is what comes back. ## Risks to weigh * **Stock price.** The stock leg is priced by a Chainlink market feed; it liquidates if the stock falls to `ltvPct.liquidation` (a 20% drop at the default 50% LTV on a 62.5% market). * **Yield-leg rates.** The loop runs near its max LTV; if its borrow rate rises above the collateral yield, `netApyPct` falls and can go negative. `simulate_equity_deposit` and `equityPositions.currentNetApyPct` show the live figure. * **Exit liquidity.** The vault exits by selling the stock on the same aggregator it bought it on — read the stock's `exitLiquidity` at the position's size. * **Liquidity to borrow.** The stock market must have `liquidityUsd` to lend the borrow, and the yield market must fund the flash loop directly; both are checked before quoting. Never close a vault's yield loop with `build_manage_tx` — it is refused, because doing so would leave the stock leg standing with its debt. Always use `build_equity_exit_tx`. # Introduction Source: https://docs.spiralstake.xyz/agents/introduction The Spiral Stake MCP server — leveraged yield loops, perps and stock + yield vaults for AI agents, non-custodial. Spiral Stake exposes its leveraged strategies — correlated yield loops, directional perps, and stock + yield equity vaults on tokenized stocks — to AI agents through a **Model Context Protocol (MCP)** server, on Ethereum mainnet and Robinhood Chain. Any MCP-compatible client — Claude, Cursor, or your own — connects to a single endpoint and gains tools to discover strategies, preview positions, and build transactions the user signs. `https://api.spiralstake.xyz/mcp` — Streamable HTTP. Open, no key required. ## What an agent can do List eligible strategies with raw risk facts — collateral/borrow APY, leverage ladder, oracle type, exit liquidity, LTVs. Preview the exact resulting position — leverage, effective LTV, expected APY, price impact — deterministically, with no wallet. Get an **unsigned** transaction (approvals + tx) to open, manage, or close a leveraged position. Read a wallet's open/closed positions and open equity vaults from chain state — collateral, debt, LTV headroom, live APY. On Robinhood Chain: hold a tokenized stock 1x and farm a yield loop with the borrowed share — preview, deposit and exit as one atomic batch. ## Non-custodial by design The server **never signs, sends, or holds keys.** The build tools return a plain `{ approvals, tx }` payload (loops and perps) or an ordered `calls[]` batch (equity vaults) that the user's own wallet signs. This is the same trust model as Morpho, 1inch, and KyberSwap MCPs — the agent orchestrates, the wallet holds custody. ## Facts, not verdicts Every field is a raw, unit-labeled fact. The only opinion is namespaced under `spiralHints`, and it always ships its own thresholds so an agent can override it. The agent decides; Spiral supplies the numbers. Point your MCP client at the endpoint and start querying. # Quickstart Source: https://docs.spiralstake.xyz/agents/quickstart Connect any MCP client to Spiral Stake and run your first query. The Spiral MCP is a remote **Streamable HTTP** server. There is nothing to install and no key to obtain. ```text Endpoint theme={null} https://api.spiralstake.xyz/mcp ``` Point any MCP-compatible client at the endpoint. See the per-client guides for [Claude Desktop](/agents/connect/claude-desktop), [Cursor](/agents/connect/cursor), or [other clients](/agents/connect/other-clients). Your client should list ten tools: `list_strategies`, `get_strategy`, `get_prices`, `get_positions`, `simulate_leverage`, `build_leverage_tx`, `build_manage_tx`, `simulate_equity_deposit`, `build_equity_deposit_tx`, `build_equity_exit_tx`. Try: *"List Spiral's stable strategies and simulate 3x on the best one."* The agent will call `list_strategies`, reason over the facts, then `simulate_leverage`. ## Verify the endpoint A quick unauthenticated check that the server is live and MCP-valid: ```bash theme={null} curl -s -X POST https://api.spiralstake.xyz/mcp \ -H 'content-type: application/json' \ -H 'accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}' ``` Expect a `result.serverInfo` of `{ "name": "spiralstake", "version": "0.1.0" }`. Raw `curl` can't complete the full stateful tool handshake — use a real MCP client (below) or the [MCP Inspector](/agents/connect/other-clients) to call tools. ## The typical flow `list_strategies` → pick a strategy by its risk facts. `simulate_leverage` → confirm leverage, LTV, expected APY. `build_leverage_tx` with the user's wallet address → get the unsigned tx. The user signs approvals then the tx in their own wallet (or opens `meta.signingUrl`). # Disclaimer Source: https://docs.spiralstake.xyz/agents/reference/disclaimer Not financial advice. The Spiral MCP returns **raw, unit-labeled facts** and **unsigned transactions**. It does not provide investment advice, and the only opinion it expresses is namespaced under `spiralHints`, which always ships its own thresholds. * **Numbers are a snapshot** (`asOf`) and move with the market. * **Leverage carries risk** — including liquidation, and loss of principal from collateral depeg, oracle, or smart-contract risk. This is not the same risk profile as an insured savings product. * **Non-custodial** — you sign every transaction in your own wallet. Verify what you sign. This documentation and the MCP are provided for informational purposes only and are **not financial advice**. Do your own research. # Discovery Source: https://docs.spiralstake.xyz/agents/reference/discovery How agents and crawlers find the Spiral MCP. The Spiral MCP is discoverable without any prior knowledge. `spiralstake.xyz/llms.txt` — the file agents read first. Describes the MCP endpoint, tools, and capabilities. Machine-readable server descriptor, served from both the brand root and the API origin. Listed as `xyz.spiralstake/leverage` in the official Model Context Protocol registry. `/openapi.json` — the REST surface for non-MCP clients. ## robots.txt `spiralstake.xyz/robots.txt` explicitly welcomes AI crawlers (GPTBot, ClaudeBot, PerplexityBot, and others) and points them to `llms.txt`. # Rate limits & errors Source: https://docs.spiralstake.xyz/agents/reference/rate-limits-and-errors Limits on the MCP endpoint and how failures are surfaced. ## Rate limits The public MCP endpoint is rate-limited per IP. The build tools make live aggregator + RPC calls, so `/mcp` is capped tighter than the cached read endpoints. | Surface | Limit | | -------------------- | -------------------------- | | `/mcp` (agents) | 60 requests / minute / IP | | Public `/v1/*` reads | 300 requests / minute / IP | Responses carry `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; a `429` includes `Retry-After`. Need higher limits for a production integration? Use the [Integration API](/integration/introduction) with a partner key. ## Errors Tools **fail closed** — on stale market data, a missing swap route, or bad input, a tool returns an error result with a clear, human-readable reason rather than a half-built transaction. Nothing is ever partially executed. Common reasons: * *"Market data is too stale to build a transaction"* — the freshness guard tripped; retry shortly. * *"Market is not currently eligible for leverage"* — the strategy is hidden (thin / near-maturity / no route). * *"Provide either desiredLtv or leverage"* — missing a required input. # build_equity_deposit_tx Source: https://docs.spiralstake.xyz/agents/tools/build-equity-deposit-tx Build the unsigned atomic batch to enter a stock + yield equity vault. Returns the **unsigned** call batch to deposit into a vault, for the given wallet to sign. Non-custodial — the server never signs, sends, or holds keys. The batch is exactly what the Spiral app submits. ## Input Same as [`simulate_equity_deposit`](/agents/tools/simulate-equity-deposit), plus: The wallet that will sign. The stock leg and the yield loop are opened for it. ## Output ```json theme={null} { "chainId": 4663, "action": "equity_deposit", "strategyId": "equity-0x50bc…", "atomic": true, "calls": [ { "to": "0x…USDG", "data": "0x095ea7b3…" }, // 1. approve USDG → equity router { "to": "0x…Morpho", "data": "0xeecea000…" }, // 2. morpho.setAuthorization(router, true) { "to": "0x…Router", "data": "0x4183fb79…" }, // 3. router.equityEntry(...) { "to": "0x…Morpho", "data": "0xeecea000…" } // 4. morpho.setAuthorization(router, false) ], "meta": { "preview": { "…": "same as simulate_equity_deposit" }, "stockBorrowAmount": "494960000", "amountFlashLoan": "4711990000", "expiresAt": "2026-01-01T00:01:00.000Z", "signingUrl": "https://app.spiralstake.xyz/4663/strategies/equity-0x50bc…?leverage=50.00&amount=1000&payToken=0x…", "instructions": "…" } } ``` ## Executing Unlike a loop bundle there is no `approvals` / `tx` split: the Morpho manager authorization the router needs is granted and revoked **inside** the batch, so nothing persists after it. Send `calls` in order as a single batch — EIP-5792 `wallet_sendCalls`, or a Safe MultiSend. This is how the app submits it (`atomic: true`). Send the calls one by one, in order, and **always send the final call** — it revokes the authorization granted in step 2, even if step 3 failed. Give the user `meta.signingUrl` to review and sign in the Spiral app. Rebuild if `meta.expiresAt` passes before signing — the swap calldata is only valid for \~60 seconds. ## What the router does on-chain `equityEntry` pulls the USDG, swaps it to the stock, supplies the stock as **your** collateral on the partner Morpho market, borrows `stockBorrowAmount` USDG against it (bounded on-chain to `LLTV − 0.25%` of the collateral actually received), zaps that USDG into the yield collateral and opens the yield loop on Spiral's core for you. Any residual is refunded to you in the same call. # build_equity_exit_tx Source: https://docs.spiralstake.xyz/agents/tools/build-equity-exit-tx Build the unsigned atomic batch that fully unwinds an open equity vault. Returns the **unsigned** call batch to close a vault the wallet holds (from [`get_positions`](/agents/tools/get-positions)`.equityPositions`): each of its yield loops is closed, then one self-funded router call repays the stock debt, withdraws the stock, swaps it to USDG and returns the proceeds. Non-custodial. ## Input The vault's id (`equity-0x…`). Wallet that owns the vault and will sign. The yield loop id(s) to close with the stock leg (from `get_positions`). Optional when the vault's `yieldLoopMatch` is `tagged`, `basis` or `mixed`; **required** when it is `ambiguous`. Each must be this wallet's open loop on the vault's yield market. Nothing outside this list is ever closed. Ratio; capped at `0.01`. Vaults exist on `4663` only. ## Output ```json theme={null} { "chainId": 4663, "action": "equity_exit", "strategyId": "equity-0x50bc…", "atomic": true, "calls": [ { "to": "0x…FlashLeverage", "data": "0x…" }, // deleverage(yield loop) — one per loop the vault owns { "to": "0x…Morpho", "data": "0x…" }, // setAuthorization(router, true) { "to": "0x…Router", "data": "0x…" }, // router.equityExit(...) { "to": "0x…Morpho", "data": "0x…" } // setAuthorization(router, false) ], "meta": { "position": { "…": "the equityPositions entry being unwound" }, "closedYieldPositionIds": [3], "yieldLoopSelection": "basis", "minLoanOut": "…", "estimatedUsdgOut": "984.11", "expiresAt": "…", "signingUrl": "https://app.spiralstake.xyz/portfolio?position=3&chainId=4663", "instructions": "…" } } ``` `minLoanOut` floors the USDG the router must return to you: the stock swap's min-out less the debt (with a small interest buffer), exactly as the app builds it. Exit swaps carry **no** fee. ## Executing Same rules as the [deposit batch](/agents/tools/build-equity-deposit-tx): submit `calls` as one atomic batch (EIP-5792 / Safe); a wallet that cannot batch sends them in order and must always send the final revoke. ## Fail-closed cases Refused when the wallet has no open vault for that id; when the stock leg has no debt (`equityExit` flash-loans the debt to repay it, so a debt-free leg is withdrawn straight from Morpho instead); or when the vault's `yieldLoopMatch` is `ambiguous` and no `yieldPositionIds` were given — the tool never guesses which loop to close. Always read `meta.closedYieldPositionIds` before signing: those loops are closed together with the stock leg. The yield loop of an open vault cannot be closed on its own through [`build_manage_tx`](/agents/tools/build-manage-tx); this tool is the only way to unwind a vault. # build_leverage_tx Source: https://docs.spiralstake.xyz/agents/tools/build-leverage-tx Build the unsigned transaction to open a leveraged position. Returns the canonical **unsigned** payload to open a position, for the given wallet to sign. Non-custodial — the server never signs, sends, or holds keys. It auto-selects the open path (direct vs. zap-swap, and public-allocator reallocation when liquidity is thin) in the background, just like the app. ## Input Same as [`simulate_leverage`](/agents/tools/simulate-leverage), plus: The wallet that will sign. Approvals and `onBehalfOf` are built for it. ## Output ```json theme={null} { "chainId": 1, "action": "open_leverage", "path": "swapAndLeverage", "approvals": [{ "to": "0x…token", "data": "0x…" }], "tx": { "to": "0x…router", "data": "0x…", "value": "0" }, "meta": { "positionPreview": { "leverage": "3.0", "effectiveLtv": "66.7" }, "amountFlashLoan": "…", "minTokenOut": "…", "expiresAt": "2026-01-01T00:01:00.000Z", "signingUrl": "https://app.spiralstake.xyz/1/strategies/0x…?leverage=66.67&amount=50000&payToken=0x…" } } ``` ## Executing Sign and send each entry in `approvals[]` (none for native ETH). Sign and send `tx` from `userAddress`. Give the user `meta.signingUrl` to review and sign in the Spiral app. `meta.expiresAt` — the embedded swap calldata is time-sensitive (\~60s). If it lapses before signing, rebuild. See [Non-custodial execution](/agents/concepts/non-custodial). # build_manage_tx Source: https://docs.spiralstake.xyz/agents/tools/build-manage-tx Build the unsigned transaction to adjust or close an open position. Returns the unsigned payload to adjust or unwind an **open** position, for the owner to sign. Same non-custodial model and output shape as [`build_leverage_tx`](/agents/tools/build-leverage-tx). ## Actions One of: * `close` — unwind the position fully. * `increase_leverage` — borrow to a higher LTV (provide `desiredLtv` or `leverage`). * `add_collateral` — top up (provide `payToken` + `amount`; pay in collateral or any token). * `remove_collateral` — withdraw collateral (provide `amount`). * `repay` — pay down debt (provide `payToken` + `amount`; set `full: true` to clear it). * `borrow` — draw more loan token (provide `amount`). ## Input Wallet that owns the position and will sign. On-chain position index — from [`get_positions`](/agents/tools/get-positions). Human units. Required for add/remove/repay/borrow. Token to pay in (add\_collateral / repay). `repay` only — clear the entire remaining debt. `increase_leverage` target LTV percent. `increase_leverage` target leverage. ## Example ```ts theme={null} // Close position 0 const bundle = await call("build_manage_tx", { userAddress, id: 0, action: "close" }); // Send bundle.approvals (if any), then bundle.tx ``` Verify the result with [`get_positions`](/agents/tools/get-positions) after the transaction confirms. A loop that [`get_positions`](/agents/tools/get-positions) lists under `equityPositions` is a vault's yield leg. Every action on it is refused here — use [`build_equity_exit_tx`](/agents/tools/build-equity-exit-tx) to unwind the whole vault. # get_positions Source: https://docs.spiralstake.xyz/agents/tools/get-positions Read a wallet's open and closed positions from chain state. Reads a wallet's leverage positions — and, on Robinhood Chain, its open stock + yield equity vaults — directly from chain state (read-only). ## Input Wallet address to read positions for. ## Output Each position carries: | Field | Meaning | | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `id` | On-chain index — feeds [`build_manage_tx`](/agents/tools/build-manage-tx). | | `positionId` | Globally-unique `${chainId}-${strategyId}-${id}`. | | `open` / `liquidated` | Lifecycle flags. | | `amountLeveragedCollateral`, `amountLoan` | Collateral and debt. | | `ltv` / liquidation LTV + headroom | Current risk. | | `leverage`, `netValueUsd`, `currentLeverageApyPct` | Live position economics (the APY includes any collateral-side incentive, as the strategy's ladder does). | | `amountDepositedInLoanToken` | The on-chain deposit basis in loan-token units (not a USD cost basis). | | `exitLiquidity` | **Can this position actually be unwound?** See below. | ## Exit health (per position) Closing swaps the **full** leveraged collateral, so exit health is measured against the whole position — not your equity: ```json theme={null} "exitLiquidity": { "tier": "good", // deep | good | limited | thin | unknown "cleanExitSize": "$500K+", // largest notional that exits cleanly "unwindSizeUsd": 264.2, // this position's full unwind notional "exceedsCleanExitSize": false, // ← act on this "noSwapRoute": false // hard flag: collateral currently unswappable } ``` Poll this on open positions. A market can be `deep` while *your* position still exceeds the depth that exits cleanly — `exceedsCleanExitSize: true` means expect slippage on close. If a route disappears entirely, you can still exit in-kind (`repay` + `remove_collateral` need **no swap**) — see [Oracle & exit liquidity](/agents/concepts/oracle-and-liquidity). ```json theme={null} { "chainId": 1, "userAddress": "0x…", "positions": [ { "id": 0, "positionId": "1-0x3274…-0", "open": true, "leverage": "3.0", "currentLeverageApyPct": "5.64" } ] } ``` ## Example ```ts theme={null} const { positions } = await call("get_positions", { userAddress: "0x…" }); ``` ## Equity vaults (`equityPositions`) A vault is two legs the user holds directly: the stock as their own Morpho collateral with USDG debt, and the Spiral yield loop that debt funds. `get_positions` re-assembles them and **removes the vault's yield loop(s) from `positions`**. `yieldLoopMatch` says how the loop was attributed: | `yieldLoopMatch` | Meaning | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `tagged` | The app recorded the loop for this vault when it was opened (the primary signal). | | `basis` | Exactly one open loop's deposit basis matches the vault's stock debt. | | `mixed` | Some loops tagged, the rest matched on basis (stacked opens). | | `ambiguous` | More than one loop could be the leg. **Nothing is claimed**: the candidates are listed in `ambiguousYieldLoopIds` and stay in `positions`; `build_equity_exit_tx` then needs `yieldPositionIds`. | | `none` | The stock leg is open but no loop matches. | ```json theme={null} "equityPositions": [ { "strategyId": "equity-0x50bc…", "curator": "Longbow", "stock": { "symbol": "SPY", "collateral": "1.291249", "collateralUsd": "990.02", "priceUsd": "766.6309", "debtUsdg": "494.960000", "ltvPct": "50.00", "liquidationLtvPct": "62.50", "ltvHeadroomPct": "12.50", "liquidationPriceUsd": "613.3047", "priceDropToLiquidationPct": "20.00", "borrowApyPct": "0.06" }, "yieldLoops": [ { "id": 3, "collateralSymbol": "syrupUSDG", "ltvPct": "90.48", "currentLeverageApyPct": "40.79" } ], "yieldLoopMatch": "basis", "netValueUsd": "984.11", "currentNetApyPct": "20.37" } ] ``` A vault's yield loop cannot be managed alone: [`build_manage_tx`](/agents/tools/build-manage-tx) refuses every action on it, because closing it by itself would leave the stock leg standing with its debt. Unwind the whole vault with [`build_equity_exit_tx`](/agents/tools/build-equity-exit-tx). No cost-basis or realized P\&L — those require off-chain history. Positions are read live from chain and returned newest-first. # get_prices Source: https://docs.spiralstake.xyz/agents/tools/get-prices Current USD prices for loan and collateral tokens. Returns current USD prices, keyed by token address, for every loan and collateral token the chain's strategies use — 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. ## Input `1` = Ethereum, `4663` = Robinhood Chain. ## Output ```json theme={null} { "asOf": "2026-01-01T00:00:00.000Z", "chainId": 1, "prices": { "0xdAC17F958D2ee523a2206206994597C13D831ec7": 1.0, "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2": 1730.42 } } ``` ## Example ```ts theme={null} const { prices } = await call("get_prices"); ``` Prices are display-only — they never drive LTV, leverage, or liquidation math. A price outage degrades USD values but does not affect a built transaction's safety. # get_strategy Source: https://docs.spiralstake.xyz/agents/tools/get-strategy Full raw facts for one strategy by its Morpho market id. Returns the complete fact set for a single strategy. Unlike `list_strategies`, it resolves any configured market id — useful for inspecting the market behind an existing position. ## Input Morpho market id (`0x` + 64 hex). `1` = Ethereum, `4663` = Robinhood Chain. ## Output The same strategy object as [`list_strategies`](/agents/tools/list-strategies), for one market. Returns an error if the id isn't an eligible strategy. ## Example ```ts theme={null} const strategy = await call("get_strategy", { id: "0x3274643d…" }); ``` # list_strategies Source: https://docs.spiralstake.xyz/agents/tools/list-strategies List eligible leveraged-yield strategies with raw risk facts. Returns every eligible strategy with the full set of [risk facts](/agents/concepts/strategies). Optionally filter by collateral category. ## Input Filter by collateral category: `stable`, `ETH`, `BTC`, `stable-PT`, `stocks` (equity vaults), `Other` (perps). `1` = Ethereum, `4663` = Robinhood Chain. ## Output ```json theme={null} { "asOf": "2026-01-01T00:00:00.000Z", "chainId": 1, "count": 27, "strategies": [ { "id": "0x3274…", "collateral": { "symbol": "sUSDS", "category": "stable" }, "loan": { "symbol": "USDT" }, "collateralApyPct": "3.60", "netBorrowApyPct": "2.57", "maxLeverage": "26.7", "leverageLadder": [ { "leverage": "3.0", "leverageApyPct": "5.66" } ], "ltvPct": { "liquidation": "96.50", "max": "90.50" }, "oracle": { "type": "nav" }, "exitLiquidity": { "slippagePct": { "100000": "0.36" } } } ] } ``` On Robinhood Chain the list also carries perps and equity vaults; each announces its profile: ```json theme={null} { "id": "equity-0x50bc…", "curator": "Longbow", "collateral": { "symbol": "SPY", "category": "stocks", "description": "SPY is Robinhood's tokenized share of …" }, "defaultLeverage": { "leverage": "1", "ltvPct": "50.0", "leverageApyPct": "20.16" }, "oracle": { "type": "market" }, "spiralHints": { "profile": { "value": "equity_yield_vault", "leverageApyMeaning": "…" } }, "links": { "market": "https://www.longbow.cash/borrow/SPY" } } ``` ## Example ```ts theme={null} const { strategies } = await call("list_strategies", { category: "stable" }); ``` Rank by `leverageLadder` (yield), then filter on `oracle.type`, `exitLiquidity`, and `ltvPct.liquidation` headroom. High APY with a `market` oracle and thin exit liquidity is a trap — see [Oracle & liquidity](/agents/concepts/oracle-and-liquidity). # Tools overview Source: https://docs.spiralstake.xyz/agents/tools/overview The ten MCP tools and when to use each. List eligible strategies with raw risk facts. Optionally filter by collateral category. Full facts for one strategy by its Morpho market id. Current USD prices for loan/collateral tokens. Deterministic position preview — no wallet needed. Unsigned transaction to open a position. Unsigned transaction to adjust or close a position. Read a wallet's open/closed positions and open equity vaults from chain state. Preview a stock + yield vault deposit — no wallet needed. Unsigned atomic batch to enter a stock + yield vault. Unsigned atomic batch to fully unwind a vault. ## Read vs. execution | | Tools | Wallet? | | ---------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------- | | **Read** | `list_strategies`, `get_strategy`, `get_prices`, `get_positions` | No | | **Preview** | `simulate_leverage`, `simulate_equity_deposit` | No | | **Execution** | `build_leverage_tx`, `build_manage_tx` | Returns an **unsigned** `{ approvals, tx }`; the user signs | | **Execution (vaults)** | `build_equity_deposit_tx`, `build_equity_exit_tx` | Returns an **unsigned** atomic `calls[]` batch; the user signs | All tools accept an optional `chainId` (default `1`). Execution tools fail closed with a clear reason on stale data or a missing route — never a half-built transaction. # simulate_equity_deposit Source: https://docs.spiralstake.xyz/agents/tools/simulate-equity-deposit Deterministic preview of a stock + yield equity-vault deposit — no wallet needed. Previews depositing USDG into a [stock + yield equity vault](/agents/guides/stock-plus-yield-vault) on Robinhood Chain. Deterministic, read-only, built from live swap quotes — no wallet. You end up **1x long the stock** (held as your own Morpho collateral on the partner market), with `stockLtvPct` of its value borrowed as USDG and flash-looped into the vault's yield strategy. ## Input The vault's id from `list_strategies` (starts with `equity-`). Deposit in human units of the vault's deposit token (USDG), e.g. `"10000"`. Stock-leg LTV percent to borrow at. Default: the vault's `targetLtvPct`. Capped at 88% of the stock market's liquidation LTV (55 on a 62.5% market) — a higher value is **refused**, never clamped. Ratio; capped at `0.01` (the app's setting for vaults). Vaults exist on `4663` only. ## Output ```json theme={null} { "action": "equity_deposit", "preview": { "depositAmount": "1000", "stock": { "symbol": "SPY", "priceUsd": "766.6309", "minReceived": "1.291249", "ltvPct": "50.00", "maxLtvPct": "55.00", "liquidationLtvPct": "62.50", "liquidationPriceUsd": "613.3047", "priceDropToLiquidationPct": "20.00", "borrowUsdg": "494.96", "borrowApyPct": "0.06", "priceImpactPct": "-0.01" }, "yieldLeg": { "collateralSymbol": "syrupUSDG", "collateralIn": "488.735796", "leverage": "10.5", "ltvPct": "90.50", "amountFlashLoan": "4711.99", "leverageApyPct": "40.79" }, "netApyPct": "20.37", "fees": { "stockLegBps": 25, "yieldLegBps": 5, "estimatedFeeUsd": "5.10" }, "slippage": 0.01 } } ``` | Field | Meaning | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `stock.minReceived` | The least stock the deposit swap delivers; the router supplies what it actually gets (≥ this). | | `stock.borrowUsdg` | USDG borrowed against the stock at `ltvPct`, all deployed into the yield loop. | | `stock.liquidationPriceUsd` | The stock price at which the stock leg reaches its liquidation LTV, from the entry price. | | `yieldLeg` | The loop the borrowed USDG opens: its collateral, fixed leverage (the yield market's max-safe LTV), flash loan and APY. | | `netApyPct` | Net dollar APY on the deposit at this LTV: `ltv × (yieldLeg.leverageApyPct − stock.borrowApyPct)`. | | `fees` | Entry swap fees: 25 bps on the stock leg (price exposure), 5 bps on the yield legs. | ## Fail-closed cases The preview refuses, with a plain reason, when the stock market cannot lend the borrow (`liquidityUsd`), when the yield market cannot fund the flash loop directly (the vault entry has no reallocation path), when `stockLtvPct` is above the cap, when market data is stale, or when the id is a loop rather than a vault. ## Example ```ts theme={null} const sim = await call("simulate_equity_deposit", { strategyId: "equity-0x50bc…", amount: "10000", stockLtvPct: "50", chainId: 4663, }); // sim.preview.netApyPct, sim.preview.stock.liquidationPriceUsd ``` # simulate_leverage Source: https://docs.spiralstake.xyz/agents/tools/simulate-leverage Deterministic preview of a leveraged position — no wallet needed. Previews the exact position that opening would produce. Deterministic and read-only — identical for ETH and ERC-20 pay tokens, with no on-chain call and no wallet. ## Input Morpho market id of the strategy. Token you pay in. The collateral (opened directly) or any other token (zapped to collateral first). Native ETH = the zero address. Amount of `payToken` in human units, e.g. `"10000"`. Target leverage, e.g. `3`. Provide this **or** `desiredLtv`. Target LTV percent, e.g. `"66.67"`. Provide this **or** `leverage`. Ratio; capped at `0.01`. ## Output ```json theme={null} { "path": "swapAndLeverage", "positionPreview": { "leverage": "3.0", "requestedLtv": "66.67", "effectiveLtv": "66.73", "amountLeveragedCollateral": "52048.44", "expectedLeverageApy": "5.64", "priceImpactPct": "0.07" }, "amountFlashLoan": "…", "minTokenOut": "…", "reallocationFeeWei": null, "slippage": 0.005 } ``` ## Example ```ts theme={null} const sim = await call("simulate_leverage", { strategyId, payToken, amount: "50000", leverage: 8, }); // sim.positionPreview.expectedLeverageApy ``` Always simulate before building. The preview comes from a live swap quote, so numbers move with prices — treat it as current, not fixed. # Borrow-APY history for all markets (charts) Source: https://docs.spiralstake.xyz/api-reference/borrow-apy-history-for-all-markets-charts /api-reference/openapi.json get /v1/markets/borrow-apy-history # Borrow-APY history for one market Source: https://docs.spiralstake.xyz/api-reference/borrow-apy-history-for-one-market /api-reference/openapi.json get /v1/markets/{id}/borrow-apy-history # Borrow-incentive (Merkl) APR history for one market Source: https://docs.spiralstake.xyz/api-reference/borrow-incentive-merkl-apr-history-for-one-market /api-reference/openapi.json get /v1/markets/{id}/incentive-history # CoinGecko price chart (on-demand proxy) Source: https://docs.spiralstake.xyz/api-reference/coingecko-price-chart-on-demand-proxy /api-reference/openapi.json get /v1/prices/chart # Collateral-APY history for all markets (keyed by market id) Source: https://docs.spiralstake.xyz/api-reference/collateral-apy-history-for-all-markets-keyed-by-market-id /api-reference/openapi.json get /v1/collateral/apy-history # Collateral-APY history for one market Source: https://docs.spiralstake.xyz/api-reference/collateral-apy-history-for-one-market /api-reference/openapi.json get /v1/collateral/{id}/apy-history # Full composed Market[] for the v2-client app (raw domain model) Source: https://docs.spiralstake.xyz/api-reference/full-composed-market[]-for-the-v2-client-app-raw-domain-model /api-reference/openapi.json get /v1/app/markets The internal Market model the app consumes in place of its own client-side composition. Unlike /v1/strategies (curated, string APYs), values keep full precision: BigNumber is tagged as {"$bn":"…"} and bigint as {"$bigint":"…"}; revive both client-side before use. # Liveness + cache diagnostics Source: https://docs.spiralstake.xyz/api-reference/liveness-+-cache-diagnostics /api-reference/openapi.json get /health # One strategy by market id Source: https://docs.spiralstake.xyz/api-reference/one-strategy-by-market-id /api-reference/openapi.json get /v1/strategies/{id} # A wallet's open/closed positions Source: https://docs.spiralstake.xyz/api-reference/partner/a-wallets-openclosed-positions /api-reference/openapi.json get /v1/partner/positions/{address} # Build the unsigned manage/close transaction for a position Source: https://docs.spiralstake.xyz/api-reference/partner/build-the-unsigned-manageclose-transaction-for-a-position /api-reference/openapi.json post /v1/partner/manage/build # Build the unsigned open-leverage transaction Source: https://docs.spiralstake.xyz/api-reference/partner/build-the-unsigned-open-leverage-transaction /api-reference/openapi.json post /v1/partner/leverage/build # Preview opening a leveraged position (deterministic, no wallet) Source: https://docs.spiralstake.xyz/api-reference/partner/preview-opening-a-leveraged-position-deterministic-no-wallet /api-reference/openapi.json post /v1/partner/leverage/simulate # All strategies (frozen contract) Source: https://docs.spiralstake.xyz/api-reference/public/all-strategies-frozen-contract /api-reference/openapi.json get /v1/strategies # Latest token/loan USD prices (address → price) Source: https://docs.spiralstake.xyz/api-reference/public/latest-tokenloan-usd-prices-address-→-price /api-reference/openapi.json get /v1/prices # Readiness (warmer has primed required data) Source: https://docs.spiralstake.xyz/api-reference/readiness-warmer-has-primed-required-data /api-reference/openapi.json get /ready # StableWatch stable-pool APY snapshot + history Source: https://docs.spiralstake.xyz/api-reference/stablewatch-stable-pool-apy-snapshot-+-history /api-reference/openapi.json get /v1/stable-apy The `{ stableApy: [...] }` snapshot the app previously fetched from the dashboard `/apy`. The mcp now owns this data. Not readiness-gated: serves last-good (or an empty list) with a visible stale flag. # Current Architecture Source: https://docs.spiralstake.xyz/architecture The contracts behind Spiral Stake V2: FlashLeverage, MarketPositionManager, SwapManager, and the per-user UserProxy clones that isolate every open position. ## Contract overview **FlashLeverage**\ The main contract users interact with. Handles the full position lifecycle: opening, adjusting, and closing. Also manages fees, LTV validation, UserProxy creation, market configuration, and admin controls. Inherits MarketPositionManager, SwapManager, ReentrancyGuard, and Ownable2Step. **MarketPositionManager**\ Abstract base for all Morpho protocol interactions. Houses the flash loan callback handler (`onMorphoFlashLoan`), collateral supply and withdrawal, borrow and repay logic, position queries, share-to-asset conversion, and market parameter storage. FlashLeverage inherits from this. **SwapManager**\ Handles token swaps through whitelisted external aggregators. No internal AMM. Delegates to routers like KyberSwap, Odos, or Pendle Router using encoded calldata. Validates router approval and verifies output meets `minTokenOut` before completing any swap. **UserProxy**\ An EIP-1167 minimal clone deployed per position. Holds the position's Morpho collateral and debt in isolation. During normal operation, only FlashLeverage can call it. Manual Mode unlocks direct access for the position owner. Includes a `recover()` function for tokens accidentally sent to the proxy or accumulated as external rewards. **FlashLeverageRouter**\ Entry point for users who do not hold the collateral token. Combines a token swap and a `leverage()` call into one transaction. Also integrates with Morpho Public Allocator for vault liquidity reallocation before opening a position. *** ## Inheritance ```text theme={null} FlashLeverage ├── MarketPositionManager │ └── SwapManager ├── ReentrancyGuard (OpenZeppelin) └── Ownable2Step (OpenZeppelin) ``` *** ## Key structs **LeveragePosition** — stored per user per position ID * `open`: bool * `marketId`: Id * `userProxy`: address * `amountDepositedInLoanToken`: uint256, tracks cumulative deposits for yield fee calculation * `amountReturnedInLoanToken`: uint256 **LeverageParams** — input for `leverage()` * `marketId`, `amountCollateral`, `amountFlashLoan`, `swapData`, `minTokenOut` **MarketConfig** * `marketId`: Id * `isCorrelated`: bool **SwapData** * `extRouter`: address * `extCalldata`: bytes *** ## Key functions `leverage(user, params)`\ Opens a new position. Takes a `user` address, so anyone can open a position on behalf of another. Transfers collateral in, deploys a UserProxy for the position, flash-loans the borrow amount, swaps to additional collateral, supplies the total to Morpho, and borrows to repay the flash loan. Deposit fee applied here for non-correlated markets. `deleverage(positionId, amountCollateral, swapData, minTokenOut)`\ Closes a position. Position owner only. Flash-loans the full outstanding debt, repays Morpho, withdraws collateral, swaps to loan token, deducts yield fee on profit for correlated markets, and returns the remainder to the caller. `increaseLeverage(positionId, amountFlashLoan, swapData, minTokenOut)`\ Amplifies an existing position. Position owner only. Flash-loans additional funds, swaps to collateral, supplies the additional collateral, and borrows to repay. `supplyCollateral(user, positionId, amountCollateral)`\ Adds collateral to reduce LTV. Callable by anyone for any position. Deposit fee applies for non-correlated markets. Updates `amountDepositedInLoanToken` for accurate fee accounting. `repay(user, positionId, amountRepay, borrowShares)`\ Repays debt on a position. Callable by anyone. Deposit fee applies for non-correlated markets. `borrow(positionId, amountBorrow)`\ Extracts loan tokens from an existing position. Position owner only. Non-correlated markets only. Blocked on correlated pairs to preserve yield accounting integrity. `withdrawCollateral(positionId, amountWithdraw)`\ Removes collateral from a position. Position owner only. LTV is validated after withdrawal. Yield fee applies on correlated markets if profit is realized. `enableManualMode(userProxy)`\ Owner only. Unlocks a specific UserProxy so the position owner can interact with Morpho directly. Used for emergency recovery upon user request. *** ## Flash loan callback All flash loan operations funnel into a single `onMorphoFlashLoan(uint256 amountLoan, bytes calldata data)` callback. The `data` payload encodes an `Action` enum (LEVERAGE or UNLEVERAGE) that routes execution to `_handleLeverage()` or `_handleDeleverage()` in MarketPositionManager. The callback validates `msg.sender == address(i_morpho)` before executing any logic. *** ## Constants | Constant | Value | Description | | :------------------ | :---- | :------------------------------------------------------------- | | LIQUIDATION\_BUFFER | 0.25% | Subtracted from market LLTV to set max allowed LTV. Immutable. | | MAX\_YIELD\_FEE | 10% | Hard cap on yield fee. Immutable. | | MAX\_DEPOSIT\_FEE | 1% | Hard cap on deposit fee. Immutable. | If a Morpho market has a liquidation LTV of 90%, the protocol caps positions at 89.75% LTV. `s_yieldFee` and `s_depositFee` are both initialized to 0 in the constructor and are 0 on every live deployment. The fee paths described above are present in the code but currently deduct nothing — the only fee the protocol charges is the swap fee at entry (5 bps on correlated markets, 25 bps on non-correlated markets). See [Fees](/fees). *** ## Libraries **Math.sol** — Fixed-point arithmetic at 18-decimal precision. Used for fee and LTV calculations throughout. **TokenHelper.sol** — Safe ERC20 transfer utilities. Uses `address(0)` as the convention for native ETH. **Error.sol** — Custom error definitions for all revert conditions across the protocol. # Audits Source: https://docs.spiralstake.xyz/audits Spiral Stake V2 was audited by three independent security firms across the full development lifecycle, from initial build to deployment. Read the reports. Spiral Stake V2 has been audited by three independent security firms across the full development lifecycle, from initial build to deployment. *** ## Phage Security **Date:** January 20, 2026\ **Method:** Manual review [Read full report](https://github.com/spiral-stake/v2-core/blob/main/audits/2026-01-20-phage-spiral-stake-v2.pdf) *** ## Cyfrin **Date:** March 12, 2026\ **Method:** Manual review [Read full report](https://github.com/spiral-stake/v2-core/blob/main/audits/2026-03-12-cyfrin-spiral-stake-v2.pdf) *** ## Sherlock **Date:** April 27, 2026\ **Method:** Manual Review [Read full report](https://github.com/spiral-stake/v2-core/blob/main/audits/2026-04-27-sherlock-spiral-stake-v2.pdf) # Contract Addresses Source: https://docs.spiralstake.xyz/contract-addresses Verified contract addresses for Spiral Stake V2 on Ethereum mainnet (chainId 1) and Robinhood Chain (chainId 4663), with block-explorer links for each. Spiral Stake V2 is deployed on two chains. The same contracts run on both — only the addresses differ. Agent and API callers select a chain with the `chainId` parameter (`1` or `4663`). ## Ethereum mainnet (chainId 1) | Contract | Address | | :--------------------- | :------------------------------------------------------------------------------------------------------------------------- | | FlashLeverage | [0x2B12066ebD67A6A58E70b37051AbED0590E5A721](https://etherscan.io/address/0x2B12066ebD67A6A58E70b37051AbED0590E5A721#code) | | FlashLeverageRouter | [0x3D131d654e0C413E1cB2ab1071aad78A9470ef9d](https://etherscan.io/address/0x3D131d654e0C413E1cB2ab1071aad78A9470ef9d#code) | | Morpho Blue (external) | [0xBBBBBbbBBb9cC5e90e3b3Af64bdAF62C37EEFFCb](https://etherscan.io/address/0xBBBBBbbBBb9cC5e90e3b3Af64bdAF62C37EEFFCb#code) | ## Robinhood Chain (chainId 4663) | Contract | Address | | :--------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | | FlashLeverage | [0x27eaF95d39cB07d544026167365689C34B4d3f9A](https://robinhoodchain.blockscout.com/address/0x27eaF95d39cB07d544026167365689C34B4d3f9A?tab=contract) | | FlashLeverageRouter | [0x5F7550Bfdd7690E1CFe90c8DbB726964f4d34877](https://robinhoodchain.blockscout.com/address/0x5F7550Bfdd7690E1CFe90c8DbB726964f4d34877?tab=contract) | | Morpho Blue (external) | [0x9D53d5E3bd5E8d4Cbfa6DB1ca238AEA02E651010](https://robinhoodchain.blockscout.com/address/0x9D53d5E3bd5E8d4Cbfa6DB1ca238AEA02E651010?tab=contract) | Robinhood Chain is an Arbitrum-stack L2 with ETH as the gas token. The block explorer is [Blockscout](https://robinhoodchain.blockscout.com); markets there are denominated in USDG (Global Dollar) rather than USDC. UserProxy contracts are not listed here. One is deployed per position as an EIP-1167 minimal clone at the time you open it, so its address is specific to your position — read it from the `userProxy` field on the position. # FAQs Source: https://docs.spiralstake.xyz/faqs Which assets you can leverage, which chains are supported, how liquidation works, and what happens when you close a leveraged yield position on Spiral Stake. **What types of assets can I leverage?** Any asset that has a Morpho lending market. On Ethereum mainnet: staked stablecoins (sUSDe, wUSDe), yield-bearing ETH (wstETH, cbETH), and non-correlated directional markets (ETH/USDC, wBTC/USDC). On Robinhood Chain: USDG-denominated correlated markets (spUSDG/USDG, syrupUSDG/USDG, USDe/USDG). Check the app for the current list of live markets. *** **Which chains is Spiral Stake on?** Ethereum mainnet (chainId `1`) and Robinhood Chain (chainId `4663`). The same contracts run on both — see [Contract Addresses](/contract-addresses). Positions are per-chain: a position opened on one chain is managed on that chain and is not visible from the other. *** **How much leverage can I take?** It depends on the Morpho market's liquidation LTV. The protocol enforces a 0.25% buffer below that threshold. Most correlated pairs support 3-8x. Non-correlated pairs typically support less (3-5x) because price divergence between collateral and loan token can be large. *** **What is the difference between correlated and non-correlated markets?** Correlated means the collateral and loan token track each other in price, like sUSDe and USDC. Lower liquidation risk. Suited to yield amplification. Non-correlated means the two assets move independently, like ETH and USDC. Higher liquidation risk, because price divergence between the two assets can be large and fast. Suited to directional leverage. The two types are also fee-accounted differently in the contracts (yield fee at close vs. deposit fee on inflows), but both of those fees are currently set to 0%. *** **Can I manage my position after opening it?** Yes. You can increase leverage, add collateral, repay debt, or borrow against your collateral. None of these require closing and reopening the position. *** **What happens if I get liquidated?** Morpho liquidators repay your debt and take your collateral. Depending on how far underwater the position is, you may receive little or nothing back. Use `supplyCollateral()` or `repay()` to keep your LTV healthy before it reaches the threshold. *** **Can I exit early?** Yes. `deleverage()` works at any time. You may face swap slippage depending on market conditions, but the exit path is always available as long as a swap route exists for your collateral. *** **What if there is no swap route to exit?** You can deleverage manually. Withdraw a portion of your collateral, convert it to the loan token off-protocol via unstaking, repay part of the debt, and repeat until the position is fully closed. If needed, contact the team and the contract owner can enable Manual Mode on your UserProxy upon your request, letting you interact with Morpho directly. *** **What are the fees?** One fee: a swap fee on the internal swap when a leveraged position is opened. 0.05% (5 bps) on correlated markets, 0.25% (25 bps) on non-correlated markets. Nothing else. The yield fee (correlated pairs) and deposit fee (non-correlated pairs) both exist in the contracts but are set to 0%. No management fees, no withdrawal fees beyond gas, and closing a position returns realized yield in full. See [Fees](/fees). *** **Is my capital safe?** The protocol is non-custodial. Your funds sit in an isolated UserProxy on Morpho. Three independent audits have been completed by Phage Security, Cyfrin, and Sherlock. That said, smart contract risk, market risk, liquidation risk, and oracle risk are all real. Understand them before committing capital. *** **Who can interact with my position?** Anyone can add collateral or repay debt on your behalf. Only you as the position owner can deleverage, increase leverage, borrow, or withdraw collateral. *** **What can the protocol owner do?** The owner can add or remove supported markets and swap routers, adjust fees within the hardcoded caps, update the treasury address, pause all protocol operations in an emergency, and enable Manual Mode on a UserProxy upon request from the position owner. The owner cannot move your funds, change your position, or bypass the liquidation buffer. # Fees Source: https://docs.spiralstake.xyz/fees Spiral Stake charges one fee: a swap fee at position entry, 5 bps on correlated markets and 25 bps on non-correlated markets. No management fee, no performance fee, and nothing charged for as long as your position stays open. Spiral Stake charges a single fee: a **swap fee at position entry**. The rate depends on the market type. The fee is applied to the internal swap that converts the flash-loaned amount into the collateral token when leveraged exposure is created. If you enter from a token other than the collateral token, the swap that converts your deposit is charged at the same rate. No further fees are charged for the duration of the position. ### Fee schedule | Fee | Rate | | :--------------------------------------- | :------------- | | Swap fee (entry), correlated markets | 0.05% (5 bps) | | Swap fee (entry), non-correlated markets | 0.25% (25 bps) | | Yield fee | 0 | | Deposit fee | 0 | | Management fee | 0 | | Withdrawal fee | 0 | ### Equity + yield strategies An equity + yield strategy holds a tokenized stock as collateral and farms the borrowed USDG in a correlated yield loop. The swap from USDG into the stock is charged 25 bps, the non-correlated rate. The swaps from the borrowed USDG into the yield loop are charged 5 bps. ### Notes * No fees are charged on `increaseLeverage()` or `borrow()` * `supplyCollateral()` and `repay()` carry no fee when made in the collateral or loan token. When made from another token, the swap that converts it is charged at the market's rate * Closing a position incurs no fee, realized yield is paid out in full * Morpho flash loans carry no cost # Getting Started Source: https://docs.spiralstake.xyz/getting-started Open your first leveraged yield position: browse Morpho markets, pick a correlated or non-correlated strategy, set leverage, and confirm one transaction. ## 1. Browse markets Go to [app.spiralstake.xyz](https://app.spiralstake.xyz) and explore strategies. Each strategy shows the collateral token, loan token, liquidation LTV and other relevant data. Strategies come in two types: **Correlated markets** (Leveraged Yield): collateral and loan token track each other in price. Lower liquidation risk. Suited for yield amplification. (eg. assets: sUSDe/USDC, PT-sUSDe/USDC, wstETH/WETH) **Non-correlated** (Leveraged Long): collateral and loan token move independently. Higher liquidation risk. Suited for directional leverage. (eg. assets: ETH/USDC, wBTC/USDC, wSPYX/USDC) *** ## 2. Pick your leverage The interface calculates the flash loan amount needed for your target leverage and shows your effective LTV, max LTV, and distance from liquidation before you confirm. For correlated pairs, 3-6x is a reasonable starting range. You can go higher on very stable pairs but the margin for error narrows. For non-correlated pairs, keep leverage conservative (2-3x). Price divergence between the two assets can be large and fast. *** ## 3. Open your position Two entry paths: **Direct deposit:** If you already hold the collateral token (sUSDe, wstETH, etc.), deposit it directly. The protocol handles the full flash leverage loop in one transaction. **Swap and leverage:** If you're starting with a different token (e.g., USDC), the app routes through the FlashLeverageRouter, which swaps your token into the collateral token and opens the leveraged position in a single combined transaction. *** ## 4. Manage your position Once open, you have full control without closing and reopening: 1. **Increase leverage:** Borrows and supplies more against existing collateral to amplify exposure. 2. **Decrease leverage:** Repays/Supply to lower your LTV and widen your liquidation buffer. 3. **Borrow More:** pull loan tokens out against your collateral, within safe LTV limits. 4. **Withdraw collateral:** remove collateral from the position, within safe LTV limits. Also useful for manually deleveraging when atomic deleverage is not possible due to unavailable or inefficient swap routes for a given asset. *** ## 5. Close your position The protocol flash-loans enough to cover your full debt, repays Morpho, withdraws your collateral, swaps it back to the loan token, repays the flash loan, deducts any applicable fee, and sends you the remainder. All in one transaction. If no DEX route exists for your collateral (low liquidity or limited swap coverage), deleverage manually: withdraw a portion of collateral, convert it to the loan token off-protocol, repay part of the debt, and repeat until the position is fully closed. # Glossary Source: https://docs.spiralstake.xyz/glossary Plain-English definitions for leveraged yield: collateral token, correlated pair, deleverage, LTV, liquidation threshold, flash loan, looping and UserProxy. **Collateral Token**\ The asset you deposit and leverage against on Morpho. Examples: sUSDe, wstETH, ETH. **Correlated Pair**\ A market where the collateral and loan token track each other in price, such as sUSDe/USDC or wstETH/WETH. Lower liquidation risk. The yield fee mechanism applies to these markets at close, though it is currently set to 0. **Deleverage**\ Closing a leveraged position. The protocol repays your debt via flash loan, withdraws your collateral, swaps back to the loan token, and returns the remainder to you in one transaction. **Deposit Fee**\ An upfront fee on capital entering non-correlated positions. Charged on `leverage()`, `supplyCollateral()`, and `repay()`. Currently 0%, maximum 1%. **Flash Loan**\ A loan borrowed and repaid within the same transaction, requiring no upfront collateral. Morpho provides flash loans at zero cost. Spiral Stake uses them to open and close leveraged positions atomically. **FlashLeverage**\ The core protocol contract. Orchestrates the full position lifecycle: opening, managing, and closing leveraged positions using flash loans. **FlashLeverageRouter**\ An entry point contract that allows users to swap any token into the required collateral and open a leveraged position in a single combined transaction. **Liquidation**\ When a position's LTV exceeds Morpho's liquidation threshold, liquidators repay the debt and claim the collateral. Depending on how far underwater the position is, the user may receive little or nothing back. **Liquidation Buffer**\ A 0.25% safety margin enforced below Morpho's liquidation LTV. The protocol will not create or modify a position that exceeds this bound. It is a hardcoded compile-time constant and cannot be changed after deployment. **Loan Token**\ The token borrowed from Morpho to create leveraged exposure. Examples: USDC, WETH, USDT. **LTV (Loan-to-Value)**\ Borrowed amount divided by collateral value. Higher LTV means more leverage and less room before liquidation. **Manual Mode**\ An emergency feature where the contract owner unlocks a specific UserProxy upon request from the position owner. Once enabled, the position owner can interact with Morpho directly to repay debt or withdraw collateral, used when atomic deleverage is not possible. **Morpho**\ The underlying lending protocol that provides the borrowing, lending, flash loan, oracle, and liquidation infrastructure that Spiral Stake is built on top of. **Non-Correlated Pair**\ A market where the collateral and loan token move independently in price, such as ETH/USDC or wBTC/USDC. Higher liquidation risk. The deposit fee mechanism applies to capital inflows here instead of a yield fee at close, though it is currently set to 0. **Slippage Protection**\ The `minTokenOut` parameter passed on every swap. If the swap output falls below this value, the transaction reverts. Protects against sandwich attacks and poor execution. **Swap Router**\ An external DEX aggregator approved by the protocol owner for executing token swaps within the protocol. Examples: KyberSwap, Odos. Only whitelisted routers can be used. **UserProxy**\ A minimal clone contract deployed for each position at open. Holds the position's collateral and debt on Morpho in isolation. Problems with one position cannot affect any other user or position. **Yield Fee**\ A performance fee on realized profits when closing a correlated pair position. Currently 0%, maximum 10%. It would only ever apply if the position returned more than was deposited, never on break-even or losing positions. **Yield Spread**\ The difference between what your collateral earns and what it costs to borrow against it on Morpho. When positive, leverage amplifies this spread. When negative, the position runs at a loss. # How It Works Source: https://docs.spiralstake.xyz/how-it-works How flash leverage works: Spiral Stake collapses the whole deposit-borrow-swap-redeposit loop into one atomic transaction using Morpho's zero-fee flash loans. ## The flash leverage mechanism Traditional yield looping requires multiple transactions: deposit, borrow, swap, redeposit, reborrow. Each step costs gas and exposes you to price movement between transactions. Spiral Stake collapses the entire loop into a single atomic transaction using Morpho's zero-fee flash loans. If any step fails, the entire transaction reverts. There is no intermediate state. **Opening a position:** 1. You deposit your collateral token into the protocol 2. The protocol requests a flash loan from Morpho for the full borrow amount 3. The flash-loaned tokens are swapped to the collateral token via a whitelisted swap router 4. The swap output is combined with your deposit and supplied as total collateral to Morpho, through your isolated UserProxy 5. The protocol borrows the loan token against that collateral 6. The borrowed amount repays the flash loan 7. Position is open **Closing a position:** 1. The protocol flash-loans the full outstanding debt amount 2. That flash loan repays your Morpho debt completely 3. All collateral is withdrawn from Morpho 4. Collateral is swapped back to the loan token 5. The flash loan is repaid from swap proceeds 6. Any applicable fees are deducted from profit (currently none — see [Fees](/fees)) 7. Remaining funds are sent to you *** ## Working examples ### Correlated: yield amplification (sUSDe/USDC) You deposit \$10,000 worth of sUSDe and target 3x leverage. sUSDe yields 12% APY. Morpho borrow rate is 4%. These are illustrative rates; actual rates are variable. The protocol flash-loans \$20,000 USDC, swaps to sUSDe, and combines with your deposit for \$30,000 total collateral. It borrows \$20,000 USDC against that to repay the flash loan. Annual breakdown: * \$30,000 collateral at 12% yield = \$3,600 gross * \$20,000 debt at 4% borrow rate = \$800 cost * Net profit = \$2,800 on a \$10,000 deposit = 28% APY The yield fee is set to 0, so the full \$2,800 is yours at close. The only fee charged is the 5 bps swap fee at entry — see [Fees](/fees). Base sUSDe without leverage: 12% APY. ### Non-correlated: directional leverage (ETH/USDC) You deposit 10 ETH (\$30,000 at \$3,000/ETH) and target 3x leverage. The protocol flash-loans \$60,000 USDC, swaps to 20 ETH, and combines with your deposit for 30 ETH total collateral. It borrows \$60,000 USDC to repay the flash loan. | Scenario | Collateral value | Debt | Your net | Return | | :--------------------- | :--------------- | :------- | :------- | :----- | | ETH up 20% (\$3,600) | \$108,000 | \$60,000 | \$48,000 | +60% | | No change (\$3,000) | \$90,000 | \$60,000 | \$30,000 | 0% | | ETH down 20% (\$2,400) | \$72,000 | \$60,000 | \$12,000 | -60% | Without leverage, a 20% ETH move returns +/-20%. At 3x, the same move returns +/-60%. Leverage amplifies both gains and losses equally. Non-correlated positions carry meaningful liquidation risk when prices move against you. The deposit fee is set to 0. The only fee charged is the 25 bps swap fee at entry, the non-correlated rate — see [Fees](/fees). *** ## Position lifecycle Once open, you have full control over your position without needing to close and reopen: 1. **Increase leverage:** borrows and supplies more against existing collateral to amplify exposure 2. **Decrease leverage:** repay debt or supply collateral to lower your LTV and widen your liquidation buffer 3. **Borrow more:** pull loan tokens out against your collateral, within safe LTV limits 4. **Withdraw collateral:** remove collateral from the position, within safe LTV limits. Also useful for manually deleveraging when atomic deleverage is not possible due to unavailable or inefficient swap routes for a given asset 5. **Close (atomic):** one transaction unwinds everything and returns your net proceeds 6. **Close (manual):** if no DEX route exists for your collateral at the time of withdrawal, withdraw a portion, convert it off-protocol to the loan token, repay part of the debt, and repeat until fully closed # Authentication Source: https://docs.spiralstake.xyz/integration/authentication API keys for the partner endpoints. Partner endpoints require an API key, sent as a bearer token. ```http theme={null} Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx ``` An `X-API-Key: ` header is also accepted. Keep your key **server-side**. Never ship it to a browser or mobile client — anyone with the key gets your rate tier and revenue attribution. ## Getting a key Keys are issued out-of-band as part of onboarding. Contact us to start: [abhishek@spiralstake.xyz](mailto:abhishek@spiralstake.xyz). Each key is tied to a partner profile with: * a **rate tier** (requests/minute), * **usage attribution** for revenue reconciliation. Only the key's hash is stored — the raw key is shown once at issuance. ## Behavior | Request | Result | | ----------------------------------- | ------------------------------------------- | | Valid key on `/v1/partner/*` | Authorized, attributed, on your rate tier | | No / invalid key on `/v1/partner/*` | `401 unauthorized` | | Valid key on a public read | Optional — puts that read on your rate tier | | Invalid key on a public read | Ignored (public routes are never gated) | Public read endpoints work with no key. Sending your key on them is optional — it just moves them onto your rate tier instead of the shared per-IP limit. # Fees & revenue share Source: https://docs.spiralstake.xyz/integration/guides/fees How fees work and how partner revenue is reconciled. ## The swap fee Spiral embeds a fee on the swap inside each leverage transaction (charged on the input token): **5 bps** on correlated markets, **25 bps** on non-correlated markets. It's already baked into the built transaction — you don't add anything. ## Revenue share Your API key attributes every build to your partner profile. Revenue share is **reconciled off-chain** against on-chain volume, per your agreement — you don't route fees on-chain or handle any settlement in your integration. Attribution is captured at build time as a lead indicator; settled amounts are reconciled against actual on-chain execution. You never touch the fee flow — it's transparent to your integration. ## What you owe your users Nothing beyond the strategy's own economics. The position preview (`positionPreview.expectedLeverageApy`) and the swap's `priceImpactPct` already reflect real, net figures — show them as-is. # Going live Source: https://docs.spiralstake.xyz/integration/guides/going-live Checklist before you point real volume at the API. Your API key never reaches a client. All partner calls originate from your backend. Users see the position preview before they commit. You surface `effectiveLtv` and `expectedLeverageApy`. You rebuild when `meta.expiresAt` lapses, and treat a `503` as retryable. You map the [error envelope](/integration/reference/errors) to your UI — `400` for user-fixable input, `401` for auth, `429`/`503` for retry. You pass `chainId` explicitly (`1` or `4663`) and handle both if you support Robinhood Chain. Your key's rate tier matches your expected volume — see [Rate limits](/integration/reference/rate-limits). ## Support Quote the `correlationId` from any error response when you reach out: [abhishek@spiralstake.xyz](mailto:abhishek@spiralstake.xyz). # Integration flow Source: https://docs.spiralstake.xyz/integration/guides/integration-flow The end-to-end shape of a Spiral integration. A Spiral integration is a thin orchestration layer on top of the API — you own the UX and the signing; Spiral supplies the data and the transactions. ```mermaid theme={null} sequenceDiagram participant U as User participant P as Your app participant S as Spiral API participant W as User wallet U->>P: Choose a strategy + amount P->>S: POST /v1/partner/leverage/simulate S-->>P: positionPreview P->>U: Show leverage, LTV, expected APY U->>P: Confirm P->>S: POST /v1/partner/leverage/build (userAddress) S-->>P: { approvals, tx, meta } P->>W: Request signature (approvals, then tx) W-->>U: Approve in wallet W->>W: Broadcast on-chain ``` ## Responsibilities | Spiral | You | | --------------------------------- | ----------------------------------- | | Strategy data, prices, risk facts | Discovery UX | | Deterministic position previews | Presenting the preview | | Unsigned approvals + transaction | Prompting the user's wallet to sign | | Position reads | Position UX + tracking | ## Key rules * **Simulate before build** — show users the outcome first. * **Build with the user's wallet address** — `approvals` and `onBehalfOf` are bound to it. * **Respect `meta.expiresAt`** — rebuild if the \~60s swap-calldata window lapses. * **Non-custodial** — you never send Spiral a key; Spiral never moves funds. # Managing positions Source: https://docs.spiralstake.xyz/integration/guides/managing-positions Read, adjust, and close a user's positions. ## Read positions ```bash theme={null} curl -s "https://api.spiralstake.xyz/v1/partner/positions/0xUSER?chainId=1" \ -H "authorization: Bearer $SPIRAL_KEY" ``` Each position carries an `id` (the on-chain index — feeds manage builds), a globally-unique `positionId`, collateral/debt, current vs. liquidation LTV, leverage, net USD value, and live APY. ## Build a manage/close transaction ```bash theme={null} curl -s -X POST https://api.spiralstake.xyz/v1/partner/manage/build \ -H "authorization: Bearer $SPIRAL_KEY" -H "content-type: application/json" \ -d '{"userAddress":"0x…","id":0,"action":"close"}' ``` ### Actions | Action | Extra fields | | ------------------- | ------------------------------------------- | | `close` | — | | `increase_leverage` | `desiredLtv` or `leverage` | | `add_collateral` | `payToken`, `amount` | | `remove_collateral` | `amount` | | `repay` | `payToken`, `amount`, optional `full: true` | | `borrow` | `amount` | The response is the same `{ approvals, tx, meta }` bundle — [sign it](/integration/guides/signing) the same way. Re-read positions after the transaction confirms to refresh your UI. ## Exit health — surface it to your users Each position carries `exitLiquidity`, measured against its **full unwind notional** (closing swaps all the collateral, not just equity): ```json theme={null} "exitLiquidity": { "tier": "good", "cleanExitSize": "$500K+", "unwindSizeUsd": 264.2, "exceedsCleanExitSize": false, "noSwapRoute": false } ``` Show it on your position UI. `exceedsCleanExitSize: true` means a close will slip — a market can be `deep` while that *specific* position is larger than the depth that exits cleanly. **Users are never trapped.** A one-shot `close` needs a live swap route and **fails closed** if it's gone. But `repay` (paying in the loan token) and `remove_collateral` need **no swap at all** — repay the debt, then withdraw the collateral **in-kind**. Build that path into your UI as the fallback, and use `exceedsCleanExitSize` to prompt users to unwind early. # Signing the transaction Source: https://docs.spiralstake.xyz/integration/guides/signing How to execute the unsigned bundle a build returns. Every build returns an unsigned bundle: ```json theme={null} { "approvals": [{ "to": "0x…token", "data": "0x…" }], "tx": { "to": "0x…contract", "data": "0x…", "value": "0" }, "meta": { "expiresAt": "…", "signingUrl": "https://app.spiralstake.xyz/…" } } ``` ## Order of operations Sign and broadcast each entry in `approvals[]` from the user's wallet. Empty for native ETH. Sign and broadcast `tx` (`to`, `data`, `value`) from the same wallet. ## Two paths Prompt the connected wallet (wagmi/viem/ethers, WalletConnect, or a Safe) with the raw `approvals` + `tx`. Full control of your UX. Redirect the user to `meta.signingUrl` — the Spiral app, prefilled, where they review and sign. Zero signing code on your side. ## Freshness `meta.expiresAt` marks when the embedded swap calldata goes stale (\~60 seconds). Build **right before** the user signs. If they hesitate past `expiresAt`, rebuild — signing a stale bundle will simply revert on-chain (funds are never at risk, but the transaction fails). ## Safety guarantees * Approvals are scoped to the exact contract, for the exact amount — never infinite. * Every swap carries a `minTokenOut` floor (≥ 99% of quote) — it can't be sandwiched. * The transaction targets the strategy you chose and is bound to `userAddress`. # Introduction Source: https://docs.spiralstake.xyz/integration/introduction Embed Spiral Stake's leveraged-yield strategies into your app — non-custodial, via a keyed REST API. The Integration API lets a neobank, wallet, or fintech offer Spiral's leveraged-yield strategies inside their own product. It's the same audited engine the app and agents use, exposed as a plain, keyed REST API. `https://api.spiralstake.xyz` ## Non-custodial These endpoints return **unsigned transactions** your user signs in their own wallet. The API never signs, sends, or holds keys — **you keep full custody of the signing step.** You build the position; the user's wallet authorizes it. ## What you get Public strategy + price data to render an earn/leverage experience. Deterministic position previews to show users before they commit. Unsigned open / manage / close transactions for your user to sign. A wallet's live positions — collateral, debt, LTV, APY. ## Two access modes on one host | Surface | Auth | | ---------------------------------------------------------------- | ----------------------------- | | Public reads (`/v1/strategies`, `/v1/app/markets`, `/v1/prices`) | None | | Partner endpoints (`/v1/partner/*`) | `Authorization: Bearer ` | A key also puts your traffic on your own **rate tier** and attributes it for **revenue share**. Keys are issued out-of-band. Then make your first call in the [Quickstart](/integration/quickstart). # Quickstart Source: https://docs.spiralstake.xyz/integration/quickstart Discover, simulate, build, and hand off for signing — in four calls. ```bash theme={null} curl -s "https://api.spiralstake.xyz/v1/strategies?chainId=1" ``` Pick a strategy by its risk facts. No key needed. ```bash theme={null} curl -s -X POST https://api.spiralstake.xyz/v1/partner/leverage/simulate \ -H "authorization: Bearer $SPIRAL_KEY" \ -H "content-type: application/json" \ -d '{"strategyId":"0x…","payToken":"0x…","amount":"10000","leverage":3}' ``` Returns the deterministic `positionPreview`. ```bash theme={null} curl -s -X POST https://api.spiralstake.xyz/v1/partner/leverage/build \ -H "authorization: Bearer $SPIRAL_KEY" \ -H "content-type: application/json" \ -d '{"strategyId":"0x…","payToken":"0x…","amount":"10000","leverage":3,"userAddress":"0x…"}' ``` Returns `{ approvals, tx, meta }`. Send `approvals[]` first (if any), then `tx`, from `userAddress` — or hand them `meta.signingUrl`. See [Signing](/integration/guides/signing). ## TypeScript ```ts theme={null} const H = { authorization: `Bearer ${process.env.SPIRAL_KEY}`, "content-type": "application/json" }; const api = "https://api.spiralstake.xyz"; const build = await fetch(`${api}/v1/partner/leverage/build`, { method: "POST", headers: H, body: JSON.stringify({ strategyId, payToken, amount: "10000", leverage: 3, userAddress }), }).then((r) => r.json()); // build.approvals[], build.tx {to,data,value}, build.meta.signingUrl ``` `build.meta.expiresAt` — the embedded swap calldata is valid \~60s. Build right before the user signs, and rebuild if it lapses. # Errors Source: https://docs.spiralstake.xyz/integration/reference/errors The error envelope and status codes. Every error returns a consistent envelope: ```json theme={null} { "error": { "code": "bad_request", "message": "Human-readable reason.", "correlationId": "b7c1…" } } ``` Quote the `correlationId` when contacting support. ## Status codes | Status | Code | Meaning | Your action | | ------ | ------------------------------------ | ------------------------------------------------------------------------------ | -------------------- | | `400` | `bad_request` | Invalid input (bad chain, missing field, unknown strategy, malformed address). | Fix the request. | | `401` | `unauthorized` | Missing or invalid API key on a partner endpoint. | Check your key. | | `404` | `not_found` | Unknown route or strategy. | — | | `429` | `rate_limited` | Rate tier exceeded. | Honor `Retry-After`. | | `503` | `upstream_unavailable` / `not_ready` | Transient — market data too stale, no swap route, RPC hiccup, or warming up. | Retry with backoff. | ## Build failures fail closed The build endpoints never return a half-built transaction. A caller-fixable problem is a `400`; a transient upstream issue is a `503` (retryable). The `message` states the specific reason. # Rate limits Source: https://docs.spiralstake.xyz/integration/reference/rate-limits Per-partner rate tiers. Each API key has its own rate tier, applied per minute. Keyed requests are metered against your tier rather than the shared per-IP limit. Every response carries: | Header | Meaning | | --------------------- | ------------------------------------ | | `RateLimit-Limit` | Your per-minute ceiling. | | `RateLimit-Remaining` | Requests left in the current window. | | `RateLimit-Reset` | Seconds until the window resets. | A `429` response includes `Retry-After` (seconds). Each **build** call spends live aggregator (KyberSwap/Pendle) and RPC quota, so your tier is sized to your real throughput. Reads are cache-served and cheap. Need a higher tier? [Contact us](mailto:abhishek@spiralstake.xyz). ## Tips * Cache public strategy/price reads on your side — they change on a cadence, not per request. * Build **just before** signing (freshness), not speculatively — it saves quota and avoids stale bundles. # Overview Source: https://docs.spiralstake.xyz/overview Spiral Stake is a non-custodial leverage execution layer built on Morpho — loop yield-bearing collateral for amplified stablecoin yield, or go leveraged long. Spiral Stake is the leverage execution layer for digital assets, fully non-custodial and built on top of Morpho. It enables flashloan based leverage on both correlated and non-correlated markets, with isolated positions per user. ## Two Distinct Profiles ### Leveraged Yield (Correlated markets) Pair assets that track each other closely: sUSDe/USDC, wUSDe/USDC, wstETH/WETH. When collateral yield exceeds the borrow rate, leverage multiplies that spread. A 5% base yield at 5x leverage targets 25%, minus borrow costs. ### **Leveraged Long (Non-correlated markets)** Pair assets with independent price movements: ETH/USDC, wBTC/USDC. Leverage your directional conviction without selling your base asset or using a perpetuals exchange. Gains and losses are amplified relative to your leverage multiple. Both strategies share the same execution infrastructure, position isolation, and position management capabilities. # Risks Source: https://docs.spiralstake.xyz/risks Liquidation, depeg, oracle and smart-contract risk on leveraged yield positions — and the 0.25% LTV buffer Spiral Stake enforces before liquidation. Spiral Stake involves leverage. Leverage amplifies both gains and losses. Read this section before interacting with the protocol *** ## Liquidation risk If your collateral value falls below the required LTV threshold on Morpho, liquidators can repay your debt and claim your collateral. Depending on how far underwater the position is, you may receive little or nothing back. The protocol enforces a 0.25% buffer below Morpho's liquidation LTV and validates your LTV on every leverage and borrow operation. This gives your position a margin before liquidation becomes possible, but it does not protect you from large or fast price moves. **Correlated markets:** both sides move together, which limits liquidation risk under normal conditions. However, depegs, redemption failures, or oracle lag can still push your LTV past the threshold. **Non-correlated markets:** standard market risk applies. A significant drop in collateral price relative to the loan token can bring you close to or past liquidation quickly. Position sizing and leverage choice matter significantly here. You can reduce liquidation risk at any time by adding collateral or repaying debt without closing the position. *** ## Interest rate risk Profitability on correlated positions depends on the spread between your collateral yield and your borrow rate. Morpho borrow rates are variable and tied to pool utilization. If utilization spikes and borrow costs rise while your collateral yield stays flat or falls, the spread can compress or turn negative. Monitor pool conditions and be ready to repay or close if the spread no longer justifies staying in. *** ## Smart contract risk Spiral Stake interacts with several systems: Morpho Blue, external swap aggregators, oracle feeds, and the UserProxy delegation pattern. A bug or exploit in any of these could affect your funds. The protocol mitigates this through position isolation (one UserProxy per user), reentrancy guards on all state-changing functions, whitelisted swap routers only, and immutable safety parameters. Three independent audits have been completed. None of this eliminates smart contract risk entirely. *** ## Collateral and yield source risk For correlated positions, your collateral token depends on an underlying protocol to generate yield. If staking rewards change, protocol fees are adjusted, or the underlying yield source has a smart contract issue, expected returns can drop or the token can depeg. Understand what is backing your collateral before committing capital. *** ## Liquidity and exit risk Under stressed market conditions, swap liquidity between your collateral and loan token can dry up. Exiting a large position may become expensive due to slippage or temporarily impossible if routes are unavailable. The protocol enforces slippage protection on all swaps via a minimum output parameter. If no route is available at close, you can still unwind manually: withdraw collateral in portions, convert off-protocol, repay debt incrementally. Size positions with available liquidity in mind. *** ## Oracle risk LTV calculations rely on Morpho's oracle infrastructure. Stale prices, oracle manipulation, or misconfiguration can cause incorrect LTV assessments, either allowing undercollateralized positions to remain open or triggering liquidations that should not have occurred. This risk is inherited from Morpho and the oracle providers for each market. *** ## Direct Morpho interaction Do not supply collateral or repay debt directly to Morpho on behalf of your UserProxy. Always use the protocol's functions: `supplyCollateral()` and `repay()`. If you bypass the protocol and interact with Morpho directly on behalf of the userProxy contract of your position, the protocol's internal accounting will not be updated. Those amounts will be misidentified as yield rather than as your own deposits or repayments. The yield fee is currently 0%, so this costs you nothing today, but the position's reported profit will be wrong and any future non-zero yield fee would be charged against your own principal. # Security Source: https://docs.spiralstake.xyz/security Every position runs in its own isolated UserProxy contract, with reentrancy guards and flash-loan callbacks validated against the Morpho contract address. ## Position isolation Every position gets its own UserProxy clone contract deployed at the time the position is opened. One user's problems cannot spill over to another, and multiple positions from the same user are also fully isolated from each other. The proxy only accepts calls from the FlashLeverage contract during normal operation. Users cannot call it directly unless Manual Mode has been explicitly enabled by the owner on that specific proxy. *** ## Reentrancy protection All state-changing functions are protected with OpenZeppelin's `nonReentrant` guard. Flash loan callbacks are validated to only accept incoming calls from the Morpho contract address, blocking any attempt to invoke the callback from an external source. *** ## Liquidation buffer The 0.25% safety buffer below Morpho's liquidation LTV is a compile-time constant. It cannot be changed after deployment, regardless of owner configuration. Every leverage and borrow operation validates that the resulting LTV stays within this bound before execution proceeds. *** ## Input validation Every state-modifying function validates inputs before executing. No zero addresses, no zero amounts, collateral tokens must be registered in supported markets, positions must be open, and the resulting LTV must remain within safe bounds. Operations that would push a position toward liquidation revert. *** ## Ownership and fee caps Ownership uses OpenZeppelin's Ownable2Step, requiring a two-step acceptance process before any transfer completes. Ownership renunciation is intentionally disabled so the protocol always retains administrative capability for emergency response. Fee caps are hardcoded constants that cannot be exceeded regardless of owner configuration: * Yield fee maximum: 10% * Deposit fee maximum: 1% The owner can adjust fees within these bounds, but cannot set them above the hardcoded caps. *** ## Swap security Only routers explicitly whitelisted by the owner can execute swaps within the protocol. Every swap validates output against the caller-provided `minTokenOut` parameter and reverts if the output falls short. User proxy contracts cannot be registered as swap routers, preventing the owner from routing swap calls through a user's proxy to manipulate their Morpho position. If a router is compromised or behaves unexpectedly, the owner can remove it from the whitelist. *** ## Emergency mechanisms **Pause:** The owner can pause all position operations in an emergency. This covers opening, closing, and all active management functions including deleverage and withdrawCollateral. **Manual Mode:** If funds become stuck in a UserProxy for any reason, the owner can enable manual mode on that proxy upon the user's request. Once enabled, only the position owner (user) can interact with Morpho directly to repay debt or withdraw collateral. Enabling manual mode does not give the owner access to or control over user funds. **Token recovery:** The `recover()` function on UserProxy lets position owners retrieve any ERC20 tokens that landed in the proxy by accident or accumulated as external rewards.