# SpiralStake
> A non-custodial Morpho leverage-execution gateway behind x402 micropayments: discover and simulate leverage strategies, and build unsigned transactions for any agentic AI.

SpiralStake is an x402 micropayment gateway to Spiral Stake's non-custodial leverage execution layer on Morpho. It exposes the same seven tools as the Spiral Stake MCP server as plain HTTP endpoints, payable in USDC or EURC through the x402 two-round HTTP 402 handshake via the central facilitator. An agent reads live strategies, prices, and on-chain positions; runs a deterministic simulation of a leveraged position with no wallet; then builds an unsigned transaction bundle that a human reviews and signs locally. It serves two profiles: Leveraged Yield on correlated pairs, where leverage multiplies the spread between collateral yield and the borrow rate, and Leveraged Long on non-correlated pairs for directional exposure without selling the base asset. Positions are non-custodial and isolated per user, each in its own UserProxy clone; the gateway never holds or touches a private key. Contracts were audited by three independent firms.

## Adopting the persona
GET `/persona` to retrieve the machine-readable SOUL and adopt it as a temporary role/skill. Authored SOUL shipped at /persona; the deterministic rules below are the machine-readable mirror of its hard-rule section.

## Pricing
- `basic` tier — **$0.006125** on Base: `/v1/build/leverage-tx`, `/v1/build/manage-tx`
- Chains: Base, Arbitrum, Polygon, Avalanche, Ethereum. Per-chain prices in `/.well-known/x402.json`.

## Operations
### assembly
- **POST /v1/build/leverage-tx** — Build the unsigned transaction to open a leveraged position — returns approvals, tx, and meta the user signs locally. — params: `strategyId` (string)*, `payToken` (string)*, `amount` (string)*, `userAddress` (string)*, `leverage` (number), `desiredLtv` (string), `slippage` (number), `chainId` (integer) (tier: `basic`)
- **POST /v1/build/manage-tx** — Build the unsigned transaction to adjust or close an open position (actions: close, increase_leverage, add/remove_collateral, repay, borrow). — params: `userAddress` (string)*, `id` (integer)*, `action` (string)*, `amount` (string), `payToken` (string), `full` (boolean), `desiredLtv` (string), `leverage` (number), `slippage` (number), `chainId` (integer) (tier: `basic`)

## Workflows
- **discover-best-yield** (find the highest risk-adjusted leverage opportunity across strategies): `` — Free reads only: list_strategies to enumerate, get_strategy to compare, get_prices for current token/loan prices, then simulate_leverage on shortlisted candidates.
- **research-strategy** (understand a single strategy's market, risk, and expected outcome before any commitment): `` — Free reads: get_strategy for detail on the Morpho market id, then simulate_leverage to preview outcomes at a chosen leverage.
- **open-position** (prepare an unsigned transaction to open a leveraged-yield or leveraged-long position): `build_leverage_tx` — Precede with free reads list_strategies -> get_strategy -> simulate_leverage; never build before simulating. Returns the unsigned bundle (approvals, tx, meta) for the human to sign.
- **manage-or-close** (adjust an open position's leverage or collateral, or close it): `build_manage_tx` — Locate the position index via the free get_positions read, then build_manage_tx with the action (close, increase_leverage, add/remove_collateral, repay, borrow).

## Deterministic contract
- No LLM arithmetic: every computed number comes from a compute operation.

## Data sources
- Spiral Stake Integration REST API (Spiral Stake) — Keyed partner API this gateway proxies. Authentication is server-side — agents never need a key. Live market data.
- Morpho markets (Morpho) — Strategy risk and APY facts are derived from Morpho market data. Live.
- On-chain position state (EVM chain state) — Read via get_positions; reflects a wallet's open/closed positions at the current chain state.
- Deterministic simulation (Spiral Stake) — simulate_leverage derives results deterministically from current state, so repeat calls with the same inputs yield the same outcome.

## Free endpoints
- GET `/`, `/health`, `/about`, `/.well-known/x402.json`, `/llms.txt`, `/openapi.json` (standard)
- GET `/v1/strategies` — List all leverage strategies
- POST `/v1/strategies` — List strategies with filters
- GET `/v1/strategies/{strategy_id}` — Detail for one strategy (Morpho market id)
- GET `/v1/prices` — Current token/loan USD prices
- POST `/v1/simulate` — Deterministic preview of a leveraged position (no wallet)
- GET `/v1/positions/{address}` — A wallet's open/closed positions
- GET `/tools` — list all operations with input schemas
- GET `/feedback` — recent feedback entries
- POST `/feedback` — submit feedback

## Examples
- `open-position` — Open a leveraged-yield position on USDC — find the best strategy, simulate at 3x, then build the open transaction: `{"strategyId": "0x...market-id", "payToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000", "userAddress": "0x...signer", "leverage": 3, "chainId": 8453}`
- `discover-best-yield` — Simulate a 2x leveraged long on ETH/USDC and report the expected APY, LTV, and liquidation point: `{"strategyId": "0x...eth-usdc", "payToken": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "amount": "1", "leverage": 2, "chainId": 1}`
- `manage-or-close` — Increase leverage on an open wstETH/WETH position and rebuild the manage transaction for signing: `{"userAddress": "0x...signer", "id": 3, "action": "increase_leverage", "leverage": 4, "desiredLtv": "75", "chainId": 1}`
- `research-strategy` — Understand a single strategy's market, risk, and expected outcome before any commitment: `{"strategyId": "0x...wstETH-weth", "chainId": 1}`