io.github.Finanzgoblin/spectra-mcp-server

Compare Spectra's fixed yield (via PT) against the variable yield of the underlying interest-bearing token. Helps users decide if locking in a fixed rate is worthwhile versus staying in the variable-rate position. Protocol context: - The fixed rate comes from buying PT at a discount. Entry cost (price impact from the AMM trade) is amortized over days to maturity — shorter maturity means higher annualized entry cost, longer maturity spreads the cost thin. - Variable rate (IBT APR) fluctuates continuously. The fixed rate locks in at purchase. - LP alternative: providing liquidity to the Curve pool earns trading fees + SPECTRA gauge emissions. This is a third option alongside fixed (PT) and variable (IBT). Use get_looping_strategy to lever up the fixed yield via Morpho. Use get_portfolio to check your current positions. Use scan_opportunities for multi-chain comparison.

Scan all pools on a chain (or all chains) for a given address's activity. Returns per-pool breakdown and cross-pool aggregates. Useful for discovering multi-pool strategies without making N manual get_pool_activity calls. When investigating a wallet that operates across multiple pools (e.g., a curator or yield farmer diversifying across maturities), this tool reveals the full scope of their on-chain activity in one call. Each pool's activity is summarized with type breakdown and total volume. Cross-pool totals show the address's aggregate engagement with Spectra. For deep per-pool analysis (cycle detection, flow accounting, contract detection), use get_pool_activity with the address parameter on the specific pool of interest. Use get_portfolio to see current holdings across all pools.

Find the best fixed-rate yield opportunities across all Spectra chains. Scans all supported networks and returns the top opportunities ranked by implied APY. Filters by asset type if specified. Important: This ranks by raw implied APY without considering your capital size or pool liquidity. These rankings will often disagree with scan_opportunities (which ranks by effective APY after entry cost). That disagreement is intentional -- raw APY reflects the pool's headline rate while effective APY reflects what you actually capture at your capital size. Neither ranking is "correct" -- they measure different things. Use both to develop conviction about which pools genuinely serve your strategy.

Calculate a leveraged fixed-yield strategy using Spectra PT + Morpho looping. Strategy: Deposit asset -> mint PT on Spectra -> use PT as collateral on Morpho -> borrow underlying -> deposit again -> repeat. Each loop multiplies yield exposure. Returns projected yields at different leverage levels (1x to max safe leverage), effective APY, and risk parameters. Automatically fetches the live Morpho borrow rate and LLTV when a matching market exists. You can still override morpho_ltv and borrow_rate manually if needed. NOTE: Looping requires a Morpho market that accepts the specific PT as collateral. Risk context: - Borrow rates are variable. A 5% spread (7% yield - 2% borrow) can turn negative if borrow rates spike above your fixed yield. Monitor rates in Morpho. - Higher leverage amplifies both returns and liquidation risk. Consider keeping 1-2 loops below maximum for safety buffer. - Entry cost (price impact) compounds across loops — each iteration faces degraded effective pool liquidity. Use get_morpho_markets to find available Morpho markets. Use scan_opportunities to discover the best looping opportunities across all chains with capital-aware sizing.

Find Morpho lending markets that accept Spectra PT tokens as collateral. Returns market details including LLTV, borrow/supply APY, utilization, and liquidity. Essential for looping strategies: borrow against PT to lever up fixed yield. Can search across all chains or filter by a specific chain. Protocol context: - LLTV = Liquidation Loan-to-Value. This is the threshold where liquidation CAN occur, NOT the safe operating level. Loop safely at ~90-95% of LLTV for margin buffer. - High utilization (>90%) means limited borrowing capacity — check available liquidity. - Borrow rates are variable and can spike. Monitor rates when running leveraged positions. - Not all Spectra chains have Morpho markets. Current Morpho PT coverage: mainnet, base, arbitrum, katana. Use get_looping_strategy to calculate leveraged yield for a specific PT + Morpho market. Use get_morpho_rate to fetch live borrow APY for a specific market key. Use scan_opportunities for automated cross-chain looping discovery.

Get the current borrow rate and market state for a specific Morpho market. Provide the market's unique key (hex ID) and chain. Returns live borrow APY, supply APY, utilization, and liquidity — the data needed to calculate looping profitability. Use get_morpho_markets to discover market keys first. Important: Rates are live as-of-query and change continuously based on utilization. When planning a looping strategy, verify rates are still favorable before executing. A profitable spread (fixed yield > borrow rate) can turn negative if borrow rates spike. Use get_looping_strategy with these rates to calculate leveraged yield projections.

Get recent trade and liquidity activity for a specific Spectra pool. Returns individual transactions: buys, sells, and liquidity adds/removes with USD values, timestamps, and tx hashes. Pool activity shows only the Curve pool's perspective (IBT ↔ PT swaps and LP events). The Spectra Router batches operations atomically, so any single pool event may be one step of a multi-step strategy. There is no BUY_YT or SELL_YT event type — the pool never touches YT directly. Use get_protocol_context for the full mechanics of how Router batching maps to pool activity types. Protocol mechanics that affect how activity appears: - BUY_PT and SELL_PT are Curve pool swaps between IBT and PT. - There is NO "BUY_YT" or "SELL_YT" type. The pool never touches YT directly. - YT selling via the Router's flash-redeem internally buys PT from the pool to pair with YT for redemption — so YT sells show up as BUY_PT in the activity log. - A standalone mint (deposit IBT → PT+YT) does NOT appear in pool activity. However, the Router can batch a mint + LP add in one atomic execute() call. The minted PT + remaining IBT enter the pool as AMM_ADD_LIQUIDITY while the minted YT goes directly to the user's wallet. So AMM_ADD_LIQUIDITY events may ALSO represent YT acquisition — the YT minting is invisible in pool data. - The Router can also flash-mint atomically: flash-borrow IBT → mint PT+YT → sell PT on the pool → user tops up the shortfall → user receives YT. This shows up as SELL_PT but the user's net action is acquiring YT, not selling PT. - AMM_REMOVE_LIQUIDITY returns IBT + PT from the pool. Users often follow up by selling the PT (SELL_PT) to recover capital, completing a mint→LP→remove→sell loop that nets them YT at the cost of the PT discount (~1 - ptPrice). Key principle: any pool event type can be one step of a multi-step Router operation. Do not assume SELL_PT means "user is bearish on PT" or AMM_ADD_LIQUIDITY means "user is providing liquidity for yield." Always cross-r…

Get historical trading volume for a specific Spectra pool. Returns timestamped buy/sell volume in USD. Use list_pools first to find pool addresses. Useful for assessing pool activity and liquidity depth before entering a position. Context: Volume alone doesn't indicate capital efficiency — $1M volume in a $5M liquidity pool is very different from $1M in a $500K pool. Combine volume data with pool liquidity (from list_pools or get_pt_details) to assess real trading conditions. Output includes volume/liquidity ratio analysis when pool data is available. For individual transaction details and whale activity, use get_pool_activity instead. Use quote_trade to estimate price impact for a specific trade size.

Get wallet positions on Spectra for a specific address. Returns PT, YT, and LP balances with USD values, claimable yield, and current rates. Queries a single chain or all chains. Use this to understand what a wallet currently holds on Spectra. Protocol context: - Depositing IBT always mints BOTH PT and YT in equal amounts. If a wallet holds YT but no PT, it sold or LPed its PT. If it holds PT but no YT, it sold its YT. - PT + YT = 1 underlying at maturity. This identity is fundamental to all strategies. - Balance ratios are the key signal. Output shows Position Shape (e.g., "YT/PT 4:1") so you can reason about what the holder's position implies given the mechanics above. - When investigating a strategy, ALWAYS cross-reference portfolio with get_pool_activity. Activity shows the HOW (transaction patterns), portfolio shows the WHAT (resulting position). Neither alone tells the full story. - Strategies often span multiple wallets. If get_pool_activity shows concentrated activity from several addresses, check each one to build the full picture. - For activity analysis, use get_pool_activity with the address parameter — it will automatically cross-reference portfolio data and provide flow accounting, contract detection, gas estimates, and pool impact analysis. - Use get_address_activity to scan all pools for an address's activity in one call.

Get essential Spectra protocol mechanics needed for correct reasoning. Returns concise explanations of how PT/YT work, how Router batching affects pool activity interpretation, how to read wallet strategies from holdings, and how looping works. Covers mechanics that are easy to misinterpret without context — for example, SELL_PT in pool activity could be a flash-mint to acquire YT, not a PT sale. Available topics: pt_yt_mechanics, router_batching, position_analysis, looping, networks Omit the topic parameter to get all topics at once.

Get Spectra protocol-wide statistics: SPECTRA token supply, circulating supply, current weekly emissions, rebase formula, and general protocol info. Use this for questions about SPECTRA tokenomics or protocol health. Protocol context: - Rebase distributes additional SPECTRA to veSPECTRA holders. The formula is highly non-linear: (veSPECTRA/totalSPECTRA)^3. At 10% lock rate, rebase captures ~0.1% of emissions. At 50% lock rate, rebase captures ~12.5%. This incentivizes high ve participation. - Weekly emissions decay exponentially and eventually stabilize. - Gauge emissions boost LP APY across all pools (see LP APY breakdown in pool tools). Use get_ve_info for live veSPECTRA data and boost calculations.

Get detailed information about a specific Spectra Principal Token (PT). Returns: maturity date, TVL, implied APY, PT/YT prices, pool liquidity, LP APY breakdown, underlying asset info, IBT protocol, and yield leverage. Use this when you know the specific PT address and chain. Protocol context: - PT trades at a discount to its underlying (the discount IS the fixed yield). At maturity, PT redeems 1:1 for the underlying asset. - PT + YT = 1 underlying at maturity. YT price = 1 - PT price (in underlying terms). - YT leverage shows how much yield exposure 1 unit of YT provides relative to holding the underlying directly. Higher leverage = more amplified yield exposure. Use compare_yield to compare fixed vs. variable rates. Use get_looping_strategy to calculate leveraged fixed yield via Morpho. Use get_portfolio to check wallet holdings. Use get_pool_activity to see trading patterns on this pool.

List all blockchain networks supported by Spectra Finance. Use this as a starting point to discover what's available. Not all chains have identical feature coverage. Morpho looping markets currently exist on mainnet, base, arbitrum, and katana. veSPECTRA governance lives on Base.

Get live veSPECTRA governance token information and compute boost scenarios. Reads the current veSPECTRA total supply from Base chain on-chain, and given your balance + a specific pool, computes your exact boost multiplier. The Spectra boost formula: B = min(2.5, 1.5 * (v/V) * (D/d) + 1) v = your veSPECTRA balance V = total veSPECTRA supply (read live from Base) D = pool TVL d = your deposit size Full 2.5x boost when: v/V >= d/D (your share of votes >= your share of pool) Useful for understanding how much veSPECTRA you need for max boost in a given pool at a given deposit size.

List all active Spectra pools on a given chain. Returns a summary of each pool including: asset name, maturity, TVL, implied APY, LP APY, and pool liquidity. Useful for discovering available yield opportunities. Each pool is a Curve StableSwap-NG AMM pair of IBT (interest-bearing token) and PT (Principal Token). Implied APY is the fixed rate you lock in by buying PT at discount. LP APY is the yield from providing liquidity to the pool (fees + gauge emissions). For multi-chain discovery, use get_best_fixed_yields (raw APY ranking) or scan_opportunities (capital-aware with price impact and looping analysis). Use get_pool_activity on a specific pool to see recent trading patterns.

Model a MetaVault "double loop" strategy for curators. MetaVaults are ERC-7540 curated vaults that automate LP rollover and compound YT yield back into LP positions. This tool models the economics of leveraging MetaVault shares as collateral on Morpho (or similar lending markets). The "double loop": Layer 1 (inside vault): YT yield → LP tokens (compounding loop, managed by curator) Layer 2 (on top): MV shares → Morpho collateral → borrow → deposit back (leverage loop) Because YT compounding raises the base yield, leverage multiplies a higher base — creating a "double loop premium" over raw PT looping. Dual Morpho Market Strategy: Curators should create TWO Morpho markets for maximum flywheel effect: Market A (PT / underlying): For external users to loop PT. Drives pool volume & LP fees. Market B (MV shares / underlying): For the curator to loop vault shares. Amplifies own capital. These markets reinforce each other — PT demand deepens the pool, deeper pool attracts more loopers, and the curator earns fees on all external deposits flowing through the vault. Curator economics: The curator EARNS the performance fee on external deposits — this is revenue for managing the vault (rolling positions, compounding YT, maintaining allocations). All parameters are curator-configurable. No live API calls — this is a strategy modeling tool for pre-launch planning. When MetaVault API goes live, auto-detection will be added.

Estimate expected output, price impact, and minimum output for a PT trade. Automatically uses on-chain Curve get_dy() for exact quotes when a public RPC is available for the chain. Falls back to a conservative constant-product math estimate if on-chain quoting fails. Side: "buy" = spend underlying/IBT to buy PT (e.g. spend USDC-worth to get PT) "sell" = sell PT to receive underlying/IBT This tool only quotes PT trades on the Curve AMM pool. YT does not trade on the pool directly — YT is acquired by minting (deposit IBT to get PT+YT) or sold via flash-redeem. To estimate YT value: YT price = 1 - PT price in underlying terms. Returns: expected output amount, spot & effective rates, price impact, and minOut at the specified slippage tolerance. The output indicates whether the quote came from on-chain (exact) or math estimate (conservative upper bound). On-chain quotes reflect the actual Curve StableSwap-NG amplification parameter and current pool state — significantly more accurate than the math estimate, especially for large trades. Use simulate_portfolio_after_trade to preview your full portfolio state after this trade (BEFORE / TRADE / AFTER with deltas). Use compare_yield to evaluate whether the trade makes sense relative to variable rates.

Scan all Spectra chains for the best risk-adjusted yield opportunities, sized to your capital. Unlike get_best_fixed_yields (which ranks by raw APY), this tool computes: - Entry price impact at YOUR capital size (a 50% APY pool with $10K liquidity is useless at $500K) - Effective APY after amortizing entry cost over days to maturity - Morpho looping availability and optimal leveraged net APY - Pool capacity (max capital before price impact exceeds your threshold) - Risk warnings (low liquidity, short maturity, high impact) Returns opportunities ranked by effective APY (or looping net APY where available). Ranking logic: when a profitable Morpho looping market exists, ranks by looping net APY with cumulative entry cost amortized; otherwise ranks by effective APY (base APY minus annualized entry cost). Use get_looping_strategy to drill into a specific opportunity's leverage details. Use get_pool_activity and get_portfolio to investigate trading patterns and positions.

Scan all Spectra chains for YT (Yield Token) arbitrage opportunities. Compares the IBT's actual current variable APR against the rate implied by the YT's market price. When these diverge significantly, an arbitrage opportunity may exist: - Positive spread (IBT APR > YT implied rate): IBT earns more than the YT price implies - Negative spread (IBT APR < YT implied rate): IBT earns less than the YT price implies Returns opportunities sorted by absolute spread, with capital-aware entry sizing and break-even analysis. Execution mechanics: - Buying YT: The Spectra Router can flash-mint (flash-borrow IBT → mint PT+YT → sell PT on pool → user covers shortfall → user receives YT). This appears as SELL_PT in pool activity. Alternatively, minting IBT → PT+YT and selling PT separately. - Selling YT: The Router flash-redeems (borrow IBT → buy PT from pool → burn PT+YT → repay → profit). This appears as BUY_PT in pool activity. The Curve pool does NOT trade YT directly. - Break-even assumes the spread persists. Real variable rates fluctuate — spreads can close quickly. The break-even period is the minimum time needed, not a guarantee. Use compare_yield for a detailed fixed-vs-variable breakdown on a specific pool. Use get_pool_activity to monitor recent trading patterns in the target pool.

Preview what a wallet's Spectra portfolio would look like after a PT trade. Fetches the wallet's current position (if any) and the PT pool data, computes a trade quote, then shows BEFORE / TRADE / AFTER with deltas. Works even if the wallet has no existing position (simulates a new entry). Side: "buy" = acquire PT, "sell" = dispose PT. Note: This simulates PT trades only, not YT. YT is acquired by minting (deposit IBT to get PT+YT) and sold via the Router's flash-redeem mechanism, not through the Curve pool directly. The wallet's YT balance is shown but not modified by this simulation. Use get_portfolio to see current full positions. Use quote_trade for a standalone price quote without portfolio context.