io.github.Finanzgoblin/spectra-mcp-server
Spectra Finance MCP server: yield discovery, PT/YT, looping, Morpho, 10 chains
Ask AI about io.github.Finanzgoblin/spectra-mcp-server
Powered by Claude Β· Grounded in docs
I know everything about io.github.Finanzgoblin/spectra-mcp-server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
MetaVault MCP
Multi-protocol yield intelligence for AI agents β covering Spectra Finance, Pendle, and Morpho via the Model Context Protocol.
50 tools Β· 3 protocols Β· 10+ chains Β· read-only Β· on-chain Curve quoting Β· Pendle logit AMM modeling Β· ERC-4626 health checks Β· yield curve term structure Β· historical eth_getLogs Β· full Pendle protocol parity (13 tools) Β· cross-protocol SpectraβPendle comparison Β· Morpho supply-side visibility Β· Morpho user positions & historical rates Β· Merkl campaign APR integration Β· curator risk monitoring Β· withdrawal stress testing Β· rollover planning Β· multi-vault portfolio aggregation Β· pool expiry monitoring Β· zero web3 library dependencies
What This Does
Any AI agent (Claude, GPT, open-source) that supports MCP can query Spectra, Pendle, and Morpho in a unified interface to:
- Discover the best fixed-rate yield opportunities across 10 chains simultaneously
- Analyze specific PT/YT positions with full data (APY, TVL, liquidity, prices)
- Calculate leveraged looping strategies (Spectra PT + Morpho collateral) with auto-detected borrow rates
- Compare fixed vs. variable yields to make informed decisions
- Track wallet portfolios across all Spectra positions (PT, YT, LP) with Merkl reward integration for complete PnL
- Surface external Merkl campaign APR alongside pool and market data for both Spectra and Pendle
- Monitor pool trading volume, individual transaction activity, and cross-pool address scanning
- Quote PT trades with on-chain Curve
get_dy()for exact output, falling back to math estimates - Simulate portfolio state after a hypothetical trade (BEFORE / TRADE / AFTER with deltas)
- Scan all chains for capital-aware opportunities with price impact, effective APY, and Morpho looping analysis
- Detect YT arbitrage opportunities where IBT APR diverges from YT implied rate
- Compute real veSPECTRA boost multipliers per-pool using live on-chain data from Base
- Discover live MetaVaults across all chains β curator info, TVL, APY, positions, epoch history
- Model MetaVault "double loop" strategies for curators β vault compounding + Morpho leverage with curator economics, auto-populated from live API data or manual parameters
- Monitor MetaVault operational health β curator dashboard with vault allocation per position, depositor flows, fee revenue, bridge activity, and actionable alerts
- Query Morpho lending markets for PT collateral opportunities, identify who supplies the lending liquidity, and discover vault allocations across markets
- Query protocol stats, tokenomics, and governance data
- Compare Spectra vs Pendle yield opportunities side-by-side with maturity-aware matching on overlapping chains
- Scan both Spectra and Pendle for the best curator opportunities with capital-aware sizing and cross-protocol match tagging
- Browse Pendle markets across all Pendle-supported chains (including Pendle-only chains like Mantle, Berachain, HyperEVM, Corn)
- Analyze Pendle markets in full depth β market details, portfolio tracking, trade quoting, trade simulation, looping strategies, YT arbitrage, expiry monitoring, yield curves, capacity analysis, and protocol-wide stats (full parity with Spectra tools)
- Assess pool depth with multi-size capacity curves β quote PT trades at geometric capital tiers ($1Kβ$1M) to find the sweet spot and exhaustion point on both Spectra and Pendle
- Verify IBT health before deploying β on-chain ERC-4626 conversion rate, APR sustainability (organic vs incentive), pool balance, protocol recognition, liquidity
- Visualize yield curves (term structure) for any underlying across all chains β all maturities sorted chronologically with curve shape analysis
- Recover historical on-chain pool activity via
eth_getLogswhen API data has aged out β with dynamic RPC URL support for any chain - Monitor curator Morpho position health β liquidation distance, borrow rate drift, health factors across all chains
- Stress-test MetaVault withdrawal scenarios β liquidity waterfall analysis (idle β maturing β LP removal β PT sale) with market stress simulation
- Plan position rollovers for expiring MetaVault positions β cross-protocol candidate ranking with entry impact, yield gap, and overlap windows
- Aggregate multi-vault curator portfolios β total AUM, blended APY, fee revenue projection, concentration analysis by underlying/chain
- Monitor pool expiry across all chains with readiness assessment β successor pool detection, gauge status from governance API, and operator checklist (deploy pool / submit gauge / ready for migration)
- Learn protocol mechanics on-demand via
mv_get_protocol_context(PT/YT identity, Router batching, deposit paths, glossary, workflow routing)
The agent doesn't need to understand PT/YT mechanics -- it just calls spectra_scan_opportunities or pendle_scan_opportunities with its capital size and gets ranked, actionable data. For cross-protocol comparison, mv_scan_curator_opportunities ranks both protocols together. If it needs to understand why something works that way, it calls mv_get_protocol_context.
Open Emergence Architecture
The server is designed so that AI agents can discover novel strategies without being taught specific strategies. Instead of hard-coding strategy identification logic, the system teaches protocol mechanics at three layers β and lets the agent compose building blocks into its own analysis.
The Three Layers
Layer 1: Protocol Context (mv_get_protocol_context tool + resources)
β Teaches the "physics" of the protocol: PT/YT identity, Router batching, minting
β Available as a callable tool (on-demand) and as MCP resources
β Static knowledge β what CAN happen, not what IS happening
Layer 2: Tool Descriptions (every tool's description string)
β Teaches domain-specific mechanics relevant to that tool's data
β Cross-reference nudges: "use spectra_get_portfolio to check actual holdings"
β Uses "could be" language, not "is" β preserves ambiguity where it exists
β Calls out hidden mechanics that could mislead (e.g., AMM_ADD_LIQUIDITY can mint YT)
Layer 3: Structured Output Hints (computed at runtime in tool output)
β Position Shape analysis in portfolio: balance ratios (e.g., "YT/PT 4:1")
β Portfolio Signals: concentration, maturity alerts, strategy shape across positions
β Volume Signals: volume/liquidity ratio, buy/sell skew, trend detection
β Morpho Market Hints: capacity warnings, utilization alerts, spread analysis, reward incentives
β Morpho Supply-Side Analysis: supplier identification (vault/EOA/looper), concentration metrics,
supply gap warnings β surfaces where lending liquidity comes from and whether it's sufficient
β Competing Interpretation Branches (A/B/C) in activity analysis per-address:
multiple explanations for the same observable pattern, presented with equal weight.
The agent must bring external evidence to collapse branches β the tension IS the info.
β Statistical confidence boundaries: small-N cycle repetitions (β€5) flagged as
insufficient for extrapolation, preventing false pattern-matching
β Flow Accounting with competing hypotheses: YT-only, PT-only, fully exited positions
each get multiple explanations that predict different future behavior
β Address isolation mode: cycle detection, flow accounting, contract/EOA detection,
pool impact warnings, gas estimates, pool context
β Capital-aware warnings: short maturity, low liquidity, negative effective APY
β Yield Dimensions in scan output: fixed, variable, LP, looping side-by-side
β Strategy Tension: competing PT looping vs YT accumulation on same pool
β On-chain quote source indicators: "(on-chain Curve get_dy)" vs "(estimated)"
β Yield composition: IBT APR breakdown (organic base vs external incentives) in scans and quotes
β Incentive sustainability: flags when >50% of IBT APR or LP APY comes from incentives,
shows "organic only" APY so agents can assess yield durability without incentive assumptions
β Pool reserves: IBT/PT amounts with ratio for AMM imbalance analysis
β Merkl campaign APR: external incentive programs (e.g., KAT rewards) shown per-pool/market
with double-counting avoidance (skips campaigns whose reward tokens are already displayed)
β Points multipliers: external programs (Drops, InfiniFi, Firelight) with amounts
β "Could be" / "at current rates" language: preserves ambiguity in ranked output
β Makes key signals SALIENT without prescribing interpretation
Layer 4: Observation Coverage (quantifies blind spots in tool output)
β Value coverage: what % of an address's position is explained by observable activity.
Low coverage means most behavior is invisible (direct mints, transfers, cross-chain).
β Temporal coverage: active days vs dark periods with no observable events.
Longest gap duration surfaced so the agent can reason about invisible activity.
β Data source coverage: which of 5 available sources were consulted vs not.
Explicitly lists what is invisible to the current analysis.
β Activity diversity: single-type activity flagged as highest-ambiguity pattern.
β Boundary marker: "Position sizing should assume this analysis is incomplete,
not comprehensive." β a structural admission of domain-of-validity limits.
β Coverage metrics bound ALL interpretations above them. High-confidence strategy
assessment + low observation coverage = false confidence. The coverage section
forces the agent to size its conviction to what it actually observed.
Design Principles
- Teach mechanics, not conclusions. The server explains that AMM_ADD_LIQUIDITY could be a mint+LP batch operation β it doesn't conclude "this user is accumulating YT."
- Present competing interpretations, not single narratives. Activity analysis outputs multiple interpretation branches (A/B/C) that predict different future behavior. The agent must bring external evidence to collapse them. This friction surface prevents premature pattern-matching β the most common failure mode in wallet strategy analysis.
- Flag statistical insufficiency. Small repetition counts (β€5 cycle detections) are explicitly flagged as insufficient for extrapolation. The agent cannot treat N=3 as a confirmed pattern.
- Every tool cross-references at least one other tool. This creates analytical workflows without dictating them. The agent learns to check
spectra_get_portfolioafter seeing activity patterns, not because it was told to. - Hidden mechanics are called out where they can mislead. The Spectra Router batches multiple operations atomically. A
SELL_PTevent might actually be YT acquisition via flash-mint. Tool descriptions teach this so agents don't draw wrong conclusions from pool data alone. - Full addresses in output, never truncated. When addresses appear in activity data, they're shown in full so the agent can pass them directly to
spectra_get_portfoliowithout needing a block explorer. - Discovery tools warn about capital-awareness gaps.
spectra_get_best_fixed_yieldsexplicitly says "this ranks by raw APY β usespectra_scan_opportunitiesfor capital-aware sizing." - Quantify blind spots, not just interpretations. Tools now output observation coverage metrics: what percentage of behavior is visible, what data sources were consulted vs available, and how long dark periods lasted. These are not interpretations β they're structural measurements of the analysis's own incompleteness. An agent that sees 35% value coverage should size its confidence accordingly, regardless of how coherent the best-fitting interpretation looks.
Why This Matters
A cold-start agent with zero prior knowledge of the protocols can:
- Call
mv_scan_curator_opportunitiesβ see cross-protocol (Spectra + Pendle) yield rankings with capital-aware metrics - Call
spectra_get_pool_activityβ see trading patterns with β hints about ambiguous events - Call
spectra_get_portfolioandpendle_get_portfolioon flagged addresses β see Position Shape across both protocols - Read the cross-reference nudges β compose its own analytical workflow spanning all three protocols
- Identify novel strategies the server was never explicitly programmed to detect
This was validated: a subagent spawned with zero priming correctly identified a mint-and-sell-PT loop strategy (YT accumulation via PT discount) in 3 tool calls, using only the mechanics taught in descriptions and the structured hints in output.
The competing-branch design was motivated by a real failure: an agent analyzing a multi-chain wallet collapsed all activity into "YT accumulator" despite different pools showing different patterns (spread capture, market making, LP cycling). The single-narrative failure mode β where the agent picks one interpretation and defends it β is the most dangerous because it looks like good analysis from inside.
The observation coverage layer addresses a deeper problem: even perfect interpretation of observed data is misleading when the data covers a minority of behavior. Competing branches solve the narrative problem (which story fits?). Coverage metrics solve the exposure problem (how much of the picture am I seeing?). An agent that picks the best interpretation branch but ignores 65% invisible activity is sizing conviction to coherence, not evidence.
Tools
| Tool | Description |
|---|---|
spectra_get_best_fixed_yields | Scan ALL chains for top fixed-rate opportunities. The main discovery tool. Supports compact mode. |
spectra_list_pools | List all active pools on a specific chain, sorted by APY/TVL/maturity. Surfaces pool reserves, IBT APR composition, maturityValue, multipliers, and tags. Supports compact mode and include_expired flag. |
spectra_get_pt_details | Deep dive on a specific Principal Token -- full data including maturityValue, multipliers (points programs), tags, pool reserves, IBT APR composition, and baseIbt for wrapper tokens. |
spectra_compare_yield | Fixed (PT) vs. variable (IBT) yield comparison with spread mechanics and entry cost analysis. |
spectra_get_looping_strategy | Calculate leveraged yield via PT + Morpho looping with effective liquidation margins, borrow rate sensitivity (+1/2/3%), break-even period, and failure scenario modeling. Auto-fetches live Morpho rates when a matching market exists. |
morpho_list_markets | Find Morpho lending markets that accept Spectra PTs as collateral. Filter by chain or symbol. Shows reward incentives, vault supplier count per market. Cross-references Spectra PT addresses. |
morpho_get_rate | Get live borrow rate, state, and supply-side context for a specific Morpho market. Includes PT spread analysis, top supplier identification, and vault allocation details (% of AUM, cap utilization). |
morpho_get_market_suppliers | Supply-side analysis for a Morpho market: top suppliers ranked by size, vault vs EOA/looper identification, concentration analysis, supply gap warnings. Reveals where lending liquidity comes from. |
morpho_list_vaults | List Morpho vaults on a chain with enriched allocations: Spectra PT tagging, live borrow rates and utilization per allocation, cap utilization percentages. Parallel-fetches market rates and PT addresses for zero-latency enrichment. |
morpho_get_positions | Query a user's Morpho positions across markets and vaults on a chain (or all Morpho chains). Shows collateral, borrows, supply with USD values, vault deposits, health factors, looper detection, and position signals. |
morpho_get_history | Historical rates and growth for a specific Morpho market. Shows borrow/supply APY, utilization, and TVL trends with min/avg/max/current stats. Includes rate stability signals, spike detection, and supply/demand squeeze alerts. |
spectra_get_protocol_stats | SPECTRA tokenomics, emissions schedule, fee distribution, governance info. |
spectra_list_chains | List available networks (10 chains). |
spectra_get_portfolio | Wallet positions across PT, YT, and LP with USD values, claimable yield, and Merkl rewards (SPECTRA gauge emissions + incentive programs). Rewards matched to specific pools via reason key parsing. |
spectra_get_pool_volume | Historical buy/sell trading volume for a specific pool. Accepts PT address or pool address. |
spectra_get_pool_activity | Recent individual transactions (buys, sells, liquidity events) with filtering. Address isolation mode presents competing interpretation branches (A/B/C), statistical confidence boundaries on cycles, flow accounting with competing hypotheses, contract/EOA detection, gas estimates. Accepts PT or pool address. |
spectra_get_address_activity | Cross-pool address scanner β finds all pools an address has interacted with on a chain (or all chains) in one call. Includes expired/matured pools via portfolio lookup. Per-pool breakdown + cross-pool aggregates. |
spectra_quote_trade | PT trade quoting with on-chain Curve get_dy() for exact output (falls back to math estimate). Shows price impact, slippage, minOut, pool reserves with ratio, and IBT APR composition. |
spectra_simulate_trade | Preview portfolio BEFORE/AFTER a hypothetical PT trade with deltas, warnings, and on-chain quoting. |
spectra_scan_opportunities | Capital-aware opportunity scanner: price impact at your size, effective APY, Morpho looping, pool capacity, IBT APR composition, and points multipliers. Supports compact mode. |
spectra_scan_yt_arbitrage | YT rate vs IBT rate arbitrage scanner -- finds pools where YT is mispriced relative to underlying yield. Includes IBT APR composition for spread sustainability analysis. Supports compact mode. |
spectra_get_ve_info | Live veSPECTRA data from Base chain (total supply via on-chain read) + boost calculator with per-pool multipliers. |
spectra_list_metavaults | List live MetaVaults across all chains (or a specific chain). Returns curator info, TVL, live APY, share price, active positions, and epoch history. |
spectra_model_metavault | MetaVault "double loop" strategy modeler for curators. Live mode (chain + metavault_address) auto-fetches APY from API; manual mode accepts base_apy directly. Models curator economics (fee revenue, TVL creation, effective ROI). |
spectra_get_curator_dashboard | Operational dashboard for MetaVault curators. Vault health, position status with vault allocation (when available) vs pool TVL, depositor flows, fee revenue estimates, bridge activity, and actionable alerts. Explicitly disambiguates vault allocation from pool-level TVL to prevent misinterpretation. |
pendle_list_markets | List active Pendle markets on a given chain or all Pendle chains. Supports Pendle-only chains (Mantle, Berachain, HyperEVM, Corn). Supports compact mode. |
pendle_get_market_details | Deep dive on a single Pendle market β implied APY, LP APY breakdown (swap fees + PENDLE incentives + boost), underlying variable APY, pool reserves, fee rate, Merkl campaigns. |
pendle_get_best_fixed_yields | Scan all Pendle chains for top fixed-rate opportunities. Ranked by implied APY with TVL/liquidity filters. The Pendle equivalent of spectra_get_best_fixed_yields. |
pendle_get_portfolio | Wallet positions across all Pendle chains β PT, YT, LP balances with USD values and implied APY per position. |
pendle_scan_opportunities | Capital-aware Pendle opportunity scanner β price impact at your size using logit AMM model, effective APY, Morpho looping for Pendle PTs, Merkl campaigns. Supports compact mode. |
pendle_get_market_capacity | Multi-size capacity curve for a Pendle market β quotes at geometric capital tiers using logit AMM model to find sweet spot and exhaustion point. |
pendle_get_yield_curve | Term structure for a given underlying across Pendle chains. All maturities sorted chronologically with curve shape analysis (normal/inverted/flat), steepest segment, cross-chain pairs. |
pendle_list_expiring_markets | Scan Pendle chains for markets approaching maturity. Groups by urgency (CRITICAL β€7d, WARNING β€14d, ALERT β€threshold). |
pendle_scan_yt_arbitrage | YT mispricing scanner β compares underlying variable APY vs implied rate. Pendle YT trades directly on AMM (simpler execution than Spectra's Router flash-mint/redeem). |
pendle_get_protocol_stats | Protocol-wide aggregate stats β total TVL, market count, volume, avg APY across all Pendle chains with per-chain breakdown and Spectra overlap indicator. |
pendle_get_looping_strategy | Leveraged PT + Morpho looping calculator for Pendle PTs β borrow rate sensitivity, break-even analysis, 30-day historical risk assessment with P(underwater) probability. Auto-detects Morpho markets. |
pendle_quote_trade | PT trade quote using Pendle logit AMM model β expected output, price impact, effective APY after entry cost, min output with slippage tolerance. |
pendle_simulate_trade | Portfolio impact simulation for Pendle PT trades β before/after position values, blended APY change, concentration analysis. |
mv_compare_yield | Side-by-side Pendle vs Spectra yield comparison on overlapping chains (mainnet, base, arbitrum, optimism, sonic, bsc). Maturity-aware matching with configurable tolerance (exact β€7d, close β€30d, loose β€90d). |
mv_scan_curator_opportunities | Cross-protocol (Spectra + Pendle) capital-aware scanner for MetaVault curators. Price impact at your size, effective APY, Morpho looping (Spectra + Pendle), cross-protocol match tagging. Supports compact mode. |
spectra_get_onchain_activity | Historical on-chain activity via eth_getLogs β recovers data when the API has aged out transactions. Supports dynamic rpc_url parameter for any chain, token_decimals for correct formatting (USDC=6, WBTC=8). Decodes Curve pool events (swaps, LP adds/removes) via pool_address AND Spectra PT vault events (Mint, Redeem, YieldClaimed) via pt_address. Both can be provided simultaneously for merged results. |
spectra_get_pool_capacity | Multi-size capacity curve β quotes PT trades at geometric capital tiers to show price impact and effective APY degradation. Identifies sweet spot and exhaustion point. On-chain Curve quotes. |
mv_check_ibt_health | Multi-signal IBT health assessment β on-chain ERC-4626 conversion rate, APR composition (organic vs incentive), pool balance ratio, protocol recognition, liquidity level. Returns HEALTHY/CAUTION/WARNING verdict. |
spectra_get_yield_curve | Term structure for a given underlying across all chains. All maturities sorted chronologically with implied APY, TVL, liquidity. Curve shape analysis (normal/inverted/flat), steepest segment, cross-chain pairs. |
morpho_monitor_risk | Liquidation risk monitor for curator Morpho positions β health factor, liquidation price, distance-to-liquidation, borrow rate drift, alert levels (ok/watch/warning/critical). |
spectra_stress_test_vault | Withdrawal stress test for MetaVaults β liquidity waterfall (idle β maturing β LP removal β PT sale), cost to remaining depositors, maximum safe redemption size. Market stress mode (2x impact). |
mv_plan_rollover | Position rollover planner for expiring MetaVault positions β scans Spectra + Pendle for replacement candidates, computes entry impact, yield gap, overlap windows, and net effective APY. |
mv_get_curator_portfolio | Multi-vault portfolio aggregation β total AUM, blended APY, fee revenue projection, concentration by underlying/chain, cross-vault action items. Discovery mode (by curator address) or explicit mode. |
spectra_list_expiring_pools | Scan all chains for pools approaching maturity (default 21-day threshold). Groups by urgency (CRITICAL β€7d, WARNING β€14d, ALERT β€21d). Cross-references each expiring pool's IBT against all active pools for successor detection. Fetches gauge status from governance API. Per-pool readiness assessment (OK/CAUTION/WARNING). Operator checklist: deploy successor pool, submit gauge proposal, ready for migration. |
mv_get_protocol_context | Returns protocol mechanics reference (PT/YT identity, Router batching, deposit paths, glossary, workflow routing). 8 topics callable on-demand. |
Supported Chains
Spectra: Ethereum (mainnet), Base, Arbitrum, Optimism, Avalanche, Katana, Sonic, Flare, BSC, Monad
Pendle: Ethereum, Optimism, BSC, Sonic, Base, Arbitrum, Mantle, Berachain, HyperEVM, Corn
veSPECTRA Boost
The server reads live veSPECTRA total supply directly from the Base chain via raw eth_call (no ethers/viem dependency) and computes per-pool boost multipliers using the real Spectra 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 your share of total veSPECTRA >= your share of pool TVL.
Tools that accept ve_spectra_balance (spectra_scan_opportunities, spectra_scan_yt_arbitrage, spectra_compare_yield, spectra_get_ve_info) compute per-pool boost automatically. The veSPECTRA contract is an NFT-based voting escrow (veNFT) at 0x6a89228055c7c28430692e342f149f37462b478b on Base, sourced from spectra-core.
MetaVault Discovery & Strategy Modeling
MetaVaults are ERC-7540 curated vaults that automate LP rollover and compound YT yield back into LP positions. Two tools work together:
spectra_list_metavaults β Discovery tool. Fetches live MetaVault data from the API (/v1/{network}/metavaults), scanning a single chain or all chains in parallel. Returns curator info, TVL, live APY, share price, active positions with PT/pool details, and epoch rate history.
spectra_model_metavault β Strategy modeler with two modes:
- Live mode: Provide
chain+metavault_addressto auto-fetch the vault's live APY asbase_apy. All other parameters (borrow rate, LTV, curator fee) can still be overridden. - Manual mode: Provide
base_apydirectly for hypothetical or pre-launch modeling.
The "double loop" economics:
Layer 1 (inside vault): Deposit β PT/LP allocation β YT yield β more LP (compounding)
Layer 2 (on top): MV shares β Morpho collateral β borrow β deposit back (leverage)
The key insight: YT compounding raises the vault's base APY, and leverage multiplies that higher base. This creates a "double-loop premium" over raw PT looping that scales with leverage.
Curator economics are built in β the tool models fee revenue on external deposits, additional TVL created by looping, and effective ROI on the curator's own capital.
Setup
Install from npm (recommended)
npm install -g metavault-mcp
Or run directly without installing:
npx metavault-mcp
Install from source
git clone https://github.com/Finanzgoblin/metavault-mcp.git
cd metavault-mcp
npm install
npm run build
Connect to Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"metavault-mcp": {
"command": "npx",
"args": ["metavault-mcp"]
}
}
}
Restart Claude Desktop. You'll see all 50 tools (Spectra, Pendle, Morpho, cross-protocol) available.
Connect to Claude Code
claude mcp add metavault-mcp -- npx metavault-mcp
Deep Analysis Prompts
The more context you give upfront, the deeper the agent can go. Each input unlocks a different tool chain:
| Input | What it unlocks |
|---|---|
Capital size ($200K) | Price impact at your size, pool capacity limits, effective APY |
Wallet address (0x...) | Portfolio simulation, existing position context, Merkl rewards |
| veSPECTRA balance | Real per-pool boost (not min/max range) |
| Asset preference | Filtered yield curve, targeted scans |
| Strategy type | LP vs PT vs looping vs MetaVault β determines which tools get chained |
| Maturity window | Term structure analysis, rollover timing |
The ideal prompt combines all of these. Here are examples that trigger 8-10 tool chains:
- Yield hunter: "I have $50K USDC and 10,000 veSPECTRA. Find me the best risk-adjusted fixed yield for 60-180 days. Check IBT health, quote my exact entry, and show who else is in the pool."
- Curator: "I'm building a USDC MetaVault on Base with $500K own capital, expecting $2M external. Model the double-loop economics and compare Spectra vs Pendle LP allocation."
- Investigator: "Wallet 0xABC... is active on Spectra mainnet. Show me everything β portfolio, activity across all pools, sequence analysis, and what strategy they're running."
- Term structure: "Show me the ETH yield curve across all chains. Where are the term premium anomalies? Quote pool capacity at $200K for the top 3 mispricings."
The cross-referencing between tools is where the real depth happens β no single tool tells the full story. The agent calls mv_get_protocol_context(topic="workflow_routing") to learn these compositions at runtime.
Example Queries
Once connected, you can ask Claude things like:
- "What's the best fixed yield on USDC right now?"
- "Show me all Spectra pools on Base with >$50k TVL"
- "Calculate a 3x looping strategy for PT-USDC on Base using Morpho"
- "Is the fixed rate on stETH better than the variable rate?"
- "What Morpho markets accept Spectra PTs as collateral?"
- "What's the borrow rate on that Morpho PT-USDC market?"
- "What are the current SPECTRA emissions and lock rate?"
- "Show me the portfolio for 0xABC...DEF across all chains β include any unclaimed Merkl rewards"
- "What's the recent trading activity on this pool?"
- "Scan all pools on mainnet for activity from address 0xABC...DEF"
- "Check if address 0xABC...DEF is a contract or EOA and show their trading patterns"
- "Quote buying 10,000 USDC worth of PT on this pool"
- "What would my portfolio look like if I bought 50k of this PT?"
- "I have $100K to deploy -- scan all chains for the best risk-adjusted yield"
- "Scan for USDC opportunities sized for $500K with max 2% entry impact"
- "Find YT arbitrage opportunities where the market is mispricing yield"
- "I have 100K veSPECTRA -- what boost do I get on this pool with a $10K deposit?"
- "Show veSPECTRA total supply and how much I need for max boost"
- "What MetaVaults are live right now? Show me all of them across all chains"
- "Show me the MetaVaults on Base -- what are the APYs and who are the curators?"
- "Model a strategy for this MetaVault on Base" (auto-fetches live APY)
- "Model a MetaVault with 12% base APY and 3% YT compounding, 10% curator fee -- what does looping look like?"
- "Compare MetaVault looping vs raw PT looping at 12% base APY"
- "I'm curating a vault with $100K own capital and $1M external deposits -- what's my effective ROI?"
- "Compare Spectra vs Pendle yields on Base -- which protocol offers better rates for USDC?"
- "I'm curating a MetaVault with $500K -- scan both Spectra and Pendle for the best opportunities"
- "Show me all active Pendle markets on Arbitrum sorted by TVL"
- "How much capital can I put into this pool before the price impact kills my yield?"
- "Is the IBT behind this PT healthy? Check the conversion rate and APR composition"
- "Show me the USDC yield curve -- what rates are available at each maturity?"
- "Compare the 30-day vs 90-day vs 180-day rates for ETH across all chains"
- "This address traded on Katana weeks ago but spectra_get_pool_activity shows nothing -- pull on-chain logs for the last 7 days"
- "Fetch historical activity for this pool using my RPC URL: https://rpc.katana.network"
- "Monitor my Morpho positions for liquidation risk -- show me the distance to liquidation for each"
- "Stress test my MetaVault on Base -- what happens if 30% of depositors redeem in one epoch?"
- "I have a position expiring in 14 days on my MetaVault -- plan the rollover and show me the best candidates"
- "Aggregate my curator portfolio across all chains -- show me total AUM, blended APY, and concentration"
Architecture
Agent (Claude/GPT/etc)
| MCP Protocol (stdio)
MetaVault MCP (this)
| HTTP (15s timeout, 1 retry on 5xx/network errors)
|
+-- api.spectra.finance/v1/{chain}/pools
+-- api.spectra.finance/v1/{chain}/pt/{address}
+-- api.spectra.finance/v1/{chain}/portfolio/{wallet}
+-- api.spectra.finance/v1/{chain}/pools/{pool}/volume
+-- api.spectra.finance/v1/{chain}/pools/{pool}/activity
+-- api.spectra.finance/v1/{chain}/metavaults
+-- app.spectra.finance/api/v1/spectra/*
+-- api.merkl.xyz/v3/userRewards (unclaimed Merkl rewards per wallet)
+-- api.merkl.xyz/v4/opportunities (Merkl campaign APR per chain)
+-- api.morpho.org/graphql (PT collateral markets, borrow rates)
+-- api-v2.pendle.finance/core/* (Pendle market data for cross-protocol comparison)
+-- mainnet.base.org (veSPECTRA on-chain reads via raw eth_call)
+-- Chain RPCs: eth_call for Curve get_dy() quotes, eth_getCode for contract detection
| (mainnet, base, arbitrum, optimism, avalanche, sonic, bsc, flare)
+-- Chain RPCs: eth_getLogs for historical pool activity (any chain via dynamic rpc_url)
Modular TypeScript server. Read-only β queries Spectra's existing API, Morpho's GraphQL API, chain RPCs for on-chain Curve get_dy() quotes and contract detection, and Base RPC for veSPECTRA data. No wallet, no transactions, no keys, no web3 libraries needed.
src/
index.ts Entry point, tool registration, Layer 1 resources (spectra-overview,
curator-strategy-guide), main(), graceful shutdown
config.ts Constants, chain config, Zod schemas, protocol parameters, veSPECTRA constants,
block time constants per chain, RPC URL resolution (hardcoded + dynamic override)
types.ts TypeScript interfaces (SpectraPt, MorphoMarket, ScanOpportunity, MerklTokenReward, MerklChainRewards, MerklCampaign, etc.)
api.ts Fetch helpers with retry, GraphQL sanitization, Morpho batch lookup,
veSPECTRA RPC with Promise-based dedup cache, 30s TTL pool data cache,
Curve get_dy() on-chain quoting, ERC-4626 convertToAssets() health check,
eth_getCode contract detection,
MetaVault multi-chain scanning, API response validation at system boundary,
chunked eth_getLogs with retry for historical event log fetching,
Merkl reward fetching and parsing (pool address extraction from reason keys,
BigInt weiβhuman conversion, matched/unmatched reward categorization),
Merkl v4 campaign APR fetching (60s TTL cache, inflight dedup, address-based lookup)
formatters.ts Formatting, BigInt LLTV parsing, closed-form leverage math,
price impact, fractional-day maturity, boost computation,
slim envelope helpers, token amount formatting (BigInt β human-readable),
cross-protocol maturity matching (normalizeUnderlyingSymbol, matchByAssetAndMaturity),
Layer 3 output hints (Position Shape, LP APY breakdown,
volume signals, Morpho market hints, portfolio signals,
competing interpretation branches, statistical confidence boundaries,
flow accounting with competing hypotheses),
Layer 4 observation coverage (value coverage, temporal gaps,
data source coverage, activity diversity, boundary markers),
Merkl reward display (per-position matched rewards, unmatched/exited rewards),
Merkl campaign APR display (formatMerklCampaignLines with double-counting avoidance)
tools/ Layer 2: each tool description teaches domain-specific mechanics
context.ts mv_get_protocol_context (Layer 1 protocol mechanics, deposit paths, glossary, callable on-demand)
pt.ts spectra_get_pt_details, spectra_list_pools, spectra_get_best_fixed_yields, spectra_compare_yield
looping.ts spectra_get_looping_strategy
portfolio.ts spectra_get_portfolio (balance ratio strategy signals, portfolio-level hints, cross-ref nudges,
Merkl rewards integration β parallel fetch, per-position matching, unmatched rewards)
pool.ts spectra_get_pool_volume (with volume/liquidity hints), spectra_get_pool_activity (PT address resolution, Router batching,
address isolation w/ cycle detection, flow accounting, contract detection,
gas estimates, pool impact warnings, observation coverage metrics),
spectra_get_address_activity (cross-pool scanner with coverage boundary markers)
morpho.ts morpho_list_markets (with capacity/utilization hints), morpho_get_rate (with PT spread analysis)
protocol.ts spectra_get_protocol_stats, spectra_list_chains
quote.ts spectra_quote_trade (on-chain Curve get_dy() with math fallback)
simulate.ts spectra_simulate_trade (also uses on-chain quoting)
strategy.ts spectra_scan_opportunities (capital-aware, batch Morpho, negative-APY filtering, strategy tension)
yt_arb.ts spectra_scan_yt_arbitrage (YT execution mechanics, flash-mint/flash-redeem)
ve.ts spectra_get_ve_info
metavault.ts spectra_list_metavaults, spectra_model_metavault (live API + computational modeling),
spectra_get_curator_dashboard (vault allocation disambiguation, cross-chain position awareness)
pendle.ts pendle_list_markets, mv_compare_yield (maturity-aware cross-protocol yield comparison)
curator_scan.ts mv_scan_curator_opportunities (cross-protocol capital-aware scanner for MetaVault curators)
onchain.ts spectra_get_onchain_activity (historical eth_getLogs, Curve pool + PT vault event decoding, dynamic RPC)
capacity.ts spectra_get_pool_capacity (multi-size quote ladder, sweet spot / exhaustion detection)
ibt_health.ts mv_check_ibt_health (ERC-4626 conversion rate, APR composition, pool balance, verdict)
yield_curve.ts spectra_get_yield_curve (term structure for a given underlying across all chains)
risk_monitor.ts morpho_monitor_risk (liquidation distance, health factor, borrow rate drift, alert levels)
stress_test.ts spectra_stress_test_vault (withdrawal liquidity waterfall, market stress simulation)
rollover.ts mv_plan_rollover (expiring position rollover planner with cross-protocol candidates)
curator_portfolio.ts mv_get_curator_portfolio (multi-vault aggregation, AUM, blended APY, concentration)
expiry_monitor.ts spectra_list_expiring_pools (pool maturity monitoring, urgency grouping, successor cross-reference, gauge status, readiness assessment)
test.cjs Integration test suite (405 tests, McpTestClient over stdio)
test-agent.cjs Agent reasoning test suite (82 assertions, McpTestClient over stdio)
AGENT-TESTS.md 38-question subjective test suite with grading rubrics (incl. open emergence, coverage, newcomer comprehension tiers)
EMERGENCE-AUDIT.md Open Emergence audit β competing branches, observation coverage, anomaly detection gaps
CODE-REVIEW.md Full codebase review (bugs, security, code quality, test coverage)
SECURITY-REVIEW.md Security-focused review (SSRF, GraphQL injection, dependency vulnerabilities)
docs/
recursive-meta-process.md Open Emergence metaframework specification
dissolution-conditions.md Dissolution conditions for every structural decision
architecture-review-agentic-accessibility.md Agentic accessibility review with feature proposals
Each tool file exports a register(server) function. To add a new tool: create src/tools/newtool.ts, export register(), import and call it in index.ts.
All address parameters are validated (0x + 40 hex chars). All API calls have a 15-second timeout with automatic retry on transient failures (5xx, ETIMEDOUT, ENETUNREACH, ENOTFOUND). Cross-chain scans use Promise.allSettled so one chain failing doesn't block results from others. GraphQL inputs are sanitized to prevent injection. All error returns use MCP's isError: true flag for proper error signaling to agents.
Type Safety
- API return types:
fetchSpectra()andfetchMorpho()returnPromise<unknown>(notPromise<any>), forcing explicit type assertions at every call site - Nullish coalescing: All decimal/balance fallbacks use
??(not||) to correctly handle 0-decimal tokens - Morpho state fields: Typed as
number | nullto match actual API behavior β prevents silentNaNpropagation - JSON parsing: Body read as text first, then
JSON.parse()β avoids stream double-consumption that masked error diagnostics - BigInt precision: veSPECTRA total supply parsed with
10n ** BigInt(18)to avoid float intermediate overflow. Trade quoting usesamountToBigInt()(string arithmetic) to avoid precision loss whenamount * 10^decimalsexceedsMAX_SAFE_INTEGER - Input validation: Zod schemas enforce
.min()/.max()bounds on all numeric inputs to prevent invalid GraphQL queries
Technical Details
Precision & Correctness
- Morpho LLTV: Parsed with
BigIntarithmetic to avoid floating-point precision loss on 18-decimal raw values (e.g.,860000000000000000β0.86exactly) - Leverage math: Closed-form geometric series
(1 - ltv^(n+1)) / (1 - ltv)replaces iterative loop accumulation β numerically exact and O(1) - YT arbitrage: Uses fractional days-to-maturity for implied rate calculation, avoiding off-by-one annualization errors near expiry
- Price impact: Zero-liquidity pools return 100% impact (not 0%), preventing false positives in opportunity scanners. Impact clamped to 99% max to prevent negative output in trade quotes
- Negative-APY filtering: Opportunities where entry cost exceeds yield are filtered out before ranking, not sorted to the bottom
Resilience
- Retry logic: Covers
ECONNRESET,ETIMEDOUT,ENETUNREACH,ENOTFOUND,EPIPE,EHOSTUNREACH,EAI_AGAIN, andUND_ERR_SOCKETerrors - Pool data cache: 30-second TTL per-chain with inflight request deduplication β repeated scans within 30s serve cached data
- API validation:
validatePtEntries()filters malformed API responses at system boundary (validates address, maturity, name fields) - veSPECTRA cache: Promise-based deduplication prevents duplicate RPC calls when multiple tools run concurrently (5-minute TTL)
- Morpho batch limit:
firstparameter capped atmin(addresses * 3, 500)to avoid GraphQL response limits - On-chain quoting: Curve
get_dy()via raweth_callon 8 chains with automatic fallback to math estimate on RPC failure - IBT health checks: ERC-4626
convertToAssets()via raweth_callβ graceful degradation when RPC unavailable (other health checks still run) - Historical event logs: Chunked
eth_getLogs(2000 blocks/chunk) with per-chunk retry β failed chunks are skipped so partial results are still returned. Dynamicrpc_urlparameter enables any chain without hardcoded RPCs - Contract detection cache: Permanent
Mapcache foreth_getCoderesults (contract code doesn't change) - Merkl rewards: Best-effort parallel fetch from Merkl API β failure does not block portfolio display. Pool address matching via regex extraction from reason keys. BigInt
parseWei()conversion for safe 18-decimal arithmetic - Merkl campaigns: Best-effort v4 campaign APR fetch per chain (60s TTL cache with inflight dedup). Failure returns empty map β tool output is unchanged. Double-counting avoidance skips campaigns whose reward tokens are already displayed via native API data
- MCP error signaling: All error catch blocks return
isError: trueso agents can distinguish errors from empty results - PT address resolution: Pool tools (
spectra_get_pool_volume,spectra_get_pool_activity) accept either pool address or PT address and resolve automatically - Error logging: Catch blocks in Morpho lookups log to stderr instead of silently swallowing failures
- Graceful shutdown:
server.close()called beforeprocess.exit()on SIGTERM/SIGINT
Testing
From a source checkout:
# Full integration suite (405 tests, requires network)
npm test
# Schema/registration only (98 tests, no network)
npm run test:offline
# Unit tests (242 tests, no network)
npm run test:unit
# Agent reasoning tests (82 assertions, requires network)
npm run test:agent
Unit Tests (api.test.ts, formatters.test.ts, config.test.ts)
242 tests covering pure-function logic: GraphQL sanitization, Morpho field constants, Merkl reward parsing (pool address extraction from reason keys, wei-to-human conversion, matched/unmatched categorization), Merkl reward formatting, balance formatting, cross-protocol maturity matching (normalizeUnderlyingSymbol, matchByAssetAndMaturity), Pendle logit AMM price impact model (estimatePendlePriceImpact), Pendle date/maturity helpers (pendleDaysToMaturity), Pendle market formatters (compact + summary), and configuration validation. No network required.
Integration Tests (test.cjs)
405 tests covering tool registration, schema validation, API responses, on-chain Curve get_dy() quoting, cross-pool address scanning, address isolation mode, cross-protocol curator scanning, and malformed-address negative tests. Dynamically discovers pool and PT addresses from the live API, so tests won't go stale when pools mature.
Agent Reasoning Tests (test-agent.cjs)
82 assertions across multi-tool workflow tests that verify the "reasoning surface" β can an agent using these tools detect anomalies, cross-reference data, and avoid protocol-mechanic traps? Tests include:
- Protocol context completeness β all topics present, Router batching ambiguities explained, cross-reference guidance included
- Anomaly detection β raw APY vs capital-aware rankings produce different results (intentional divergence)
- Cross-tool data consistency β APYs match between
spectra_list_poolsβspectra_get_pt_detailsβspectra_compare_yield - Router mechanics β mint-and-sell loop detection via pool activity β portfolio cross-reference
- Router limitation β API resolves Router txns that
eth_getLogsaddress filtering misses - MetaVault data integrity β curator info, TVL, APY, vault flows, expired position flagging
- Expired pool discovery β
spectra_list_poolsreturns only active pools; MetaVaults surface expired positions - veSPECTRA boost math β max boost (1M veSPECTRA + $1K) vs min boost (100 veSPECTRA + $1M)
- Morpho looping fallback β graceful handling when no Morpho market exists for a PT
- Morpho market classification β Spectra vs Pendle/Other labels, unsupported chain handling
- MetaVault scan inclusion β
include_metavaultsflag correctly shows/hides MetaVault section - Pendle comparison β head-to-head matched pairs with delta, Pendle-only markets, aggregates
- Surfaced API fields β maturityValue, multipliers (points programs), tags, pool reserves with ratio, IBT APR composition, baseIbt for wrapper tokens
- Merkl rewards in portfolio β SPECTRA gauge emissions appear in portfolio output, graceful handling for empty wallets
Subjective Test Suite (AGENT-TESTS.md)
38 copy-pasteable questions across 11 tiers (basic tool usage β open emergence β newcomer comprehension) with grading rubrics for evaluating LLM agent quality when using the MCP tools. Tier 8 tests "open emergence" β the ability to hold competing interpretations without collapsing to a single narrative. Tier 11 tests newcomer comprehension β can the agent explain deposit paths, recognize conservative impact estimates, and route to the right scanner? These are designed to be run by spawning subagents and scoring responses manually or with LLM-as-judge.
API Reference
This server wraps these endpoints:
| Endpoint | Used By |
|---|---|
GET /v1/{chain}/pools | spectra_list_pools, spectra_get_best_fixed_yields, spectra_scan_opportunities, spectra_scan_yt_arbitrage, spectra_get_yield_curve (30s TTL cache) |
GET /v1/{chain}/pt/{address} | spectra_get_pt_details, spectra_compare_yield, spectra_get_looping_strategy, spectra_quote_trade, spectra_simulate_trade, spectra_get_pool_capacity, mv_check_ibt_health, spectra_get_pool_volume/spectra_get_pool_activity (PTβpool resolution) |
GET /v1/{chain}/portfolio/{wallet} | spectra_get_portfolio, spectra_simulate_trade, spectra_get_address_activity (expired pool discovery) |
GET /v1/{chain}/pools/{pool}/volume | spectra_get_pool_volume |
GET /v1/{chain}/pools/{pool}/activity | spectra_get_pool_activity, spectra_get_address_activity (active + expired pools) |
GET /v1/{chain}/metavaults | spectra_list_metavaults, spectra_model_metavault (live mode) |
GET api.merkl.xyz/v3/userRewards?user={address}&chainId={chainId} | spectra_get_portfolio (Merkl reward fetching β SPECTRA gauge emissions + incentive programs) |
GET api.merkl.xyz/v4/opportunities?chainId={chainId} | spectra_list_pools, spectra_get_pt_details, spectra_compare_yield, pendle_list_markets, mv_compare_yield, spectra_scan_opportunities, mv_scan_curator_opportunities, spectra_scan_yt_arbitrage (Merkl campaign APR β 60s TTL cache) |
GET api.spectra.finance/v1/governance/voting-incentives | spectra_list_expiring_pools (gauge status β pool address presence = gauge exists) |
GET app.spectra.finance/api/v1/spectra/circulating-supply | spectra_get_protocol_stats |
GET app.spectra.finance/api/v1/spectra/total-supply | spectra_get_protocol_stats |
POST api.morpho.org/graphql | morpho_list_markets, morpho_get_rate, spectra_get_looping_strategy (auto-detect), spectra_scan_opportunities (batch) |
POST mainnet.base.org (eth_call) | spectra_get_ve_info, spectra_scan_opportunities, spectra_scan_yt_arbitrage, spectra_compare_yield (veSPECTRA total supply) |
POST {chain RPC} (eth_call: get_dy) | spectra_quote_trade, spectra_simulate_trade, spectra_get_pool_capacity (Curve StableSwap-NG on-chain quotes) |
POST {chain RPC} (eth_call: convertToAssets) | mv_check_ibt_health (ERC-4626 IBT conversion rate health check) |
POST {chain RPC} (eth_call: eth_getCode) | spectra_get_pool_activity (contract vs EOA detection in address mode) |
POST {chain RPC} (eth_getLogs) | spectra_get_onchain_activity (historical Curve pool events + Spectra PT vault events β supports dynamic rpc_url override) |
GET api-v2.pendle.finance/core/v2/{chainId}/markets/active | pendle_list_markets (Pendle market discovery) |
GET api-v2.pendle.finance/core/v2/{chainId}/markets/active | mv_compare_yield (maturity-aware cross-protocol comparison) |
GET api-v2.pendle.finance/core/v2/{chainId}/markets/active | mv_scan_curator_opportunities (cross-protocol capital-aware scanning β Spectra + Pendle) |
Note: {chain} uses the slug mainnet for Ethereum (the alias ethereum is accepted by the server and mapped automatically).
Pendle Protocol Integration
13 Pendle tools provide full feature parity with the Spectra toolset, plus 2 cross-protocol tools for unified analysis:
Pendle-Native Tools (13)
| Category | Pendle Tool | Spectra Equivalent |
|---|---|---|
| Discovery | pendle_list_markets | spectra_list_pools |
| Discovery | pendle_get_best_fixed_yields | spectra_get_best_fixed_yields |
| Analysis | pendle_get_market_details | spectra_get_pt_details |
| Analysis | pendle_get_market_capacity | spectra_get_pool_capacity |
| Analysis | pendle_get_yield_curve | spectra_get_yield_curve |
| Portfolio | pendle_get_portfolio | spectra_get_portfolio |
| Strategy | pendle_scan_opportunities | spectra_scan_opportunities |
| Strategy | pendle_scan_yt_arbitrage | spectra_scan_yt_arbitrage |
| Strategy | pendle_get_looping_strategy | spectra_get_looping_strategy |
| Trading | pendle_quote_trade | spectra_quote_trade |
| Trading | pendle_simulate_trade | spectra_simulate_trade |
| Monitoring | pendle_list_expiring_markets | spectra_list_expiring_pools |
| Protocol | pendle_get_protocol_stats | spectra_get_protocol_stats |
Cross-Protocol Tools (2)
mv_compare_yield β Side-by-side comparison on overlapping chains with maturity-aware matching. Normalizes underlying symbols (wstETHβstETH, USDC.eβUSDC) and matches by nearest maturity within configurable tolerance (exact β€7d, close β€30d, loose β€90d). Shows match quality and maturity gap per pair.
mv_scan_curator_opportunities β Cross-protocol capital-aware scanner for MetaVault curators. Scans both Spectra and Pendle in parallel, computes price impact at your capital size, effective APY after entry cost, Morpho looping availability (both Spectra and Pendle PTs), and tags cross-protocol matches.
Pendle-Supported Chains
Overlapping with Spectra: Ethereum, Base, Arbitrum, Optimism, Sonic, BSC Pendle-only: Mantle, Berachain, HyperEVM, Corn
Key Differences from Spectra
- AMM model: Pendle uses a time-decay logit AMM (not Curve StableSwap). The capacity and quote tools use a conservative
scalarRoot=50estimate. - YT trading: Pendle YT trades directly on the AMM (
SYβYT). Spectra YT trades indirectly via Router flash-mint/redeem. - Incentives: Pendle uses PENDLE token emissions + vePENDLE boosting (separate from Spectra's SPECTRA/veSPECTRA system).
- Token wrapping: Pendle uses SY (Standardized Yield) tokens as the pool asset, not IBT (Interest-Bearing Token) like Spectra.
On-Chain Historical Activity
The Spectra REST API (/v1/{network}/pools/{pool}/activity) only retains a limited time window of recent transactions. When investigating addresses or pools with older activity, spectra_get_onchain_activity reads historical event logs directly from the blockchain via eth_getLogs.
Supports two contract types:
- Curve pool (
pool_address): TokenExchange, AddLiquidity, RemoveLiquidity, RemoveLiquidityOne - Spectra PT vault (
pt_address): Mint (deposit IBT β PT+YT), Redeem (burn PT β IBT), YieldClaimed
Both can be provided simultaneously β events are fetched in parallel, merged, and sorted by block number.
Key features:
- Dynamic RPC URL: Agent can pass any
rpc_urlparameter β works for chains without hardcoded RPCs (Katana, Monad) - Chunked fetching: 2000 blocks per chunk with per-chunk retry, best-effort (partial results on RPC issues)
- Dual-contract decoding: Curve StableSwap-NG pool events AND Spectra PrincipalToken vault events
- Block range control: Explicit
from_block/to_blockorlookback_hours(default 24h, max 720h/30 days) - Address filtering: Filter events by a specific address
- No USD values: On-chain logs don't carry prices β token amounts are shown in human-readable form. Cross-reference with
spectra_get_pt_detailsfor price context
Composability with existing tools:
Agent flow: spectra_get_pool_activity β empty? β spectra_get_onchain_activity(pool_address=...) β pool events
Agent flow: portfolio shows PT but no pool trades β spectra_get_onchain_activity(pt_address=...) β vault events (mint/redeem)
Extending
Following the Open Emergence Pattern
When adding new tools, follow the three-layer architecture:
- Description (Layer 2): Teach any protocol mechanics that affect interpretation of the tool's data. Use "could be" language for ambiguous signals. Add cross-reference nudges to at least one related tool.
- Output (Layer 3): If the data contains signals that require domain knowledge to notice (e.g., a ratio that implies a strategy, an event that could mean different things), compute a structured hint and include it in the output. Make it salient but not prescriptive. When an observable pattern has multiple valid interpretations, present them as competing branches with equal weight β do not pick one. Flag small sample sizes as statistically insufficient.
- Coverage (Layer 4): If the tool's output covers only a subset of the address's or pool's full behavior, quantify the blind spots. Report value coverage (observable activity vs position size), temporal gaps, and which data sources were used vs available. End with a boundary marker: "Position sizing should assume this analysis is incomplete, not comprehensive." Coverage metrics bound ALL interpretation branches β high-confidence assessment + low coverage = false confidence.
- Resource (Layer 1): If the new tool introduces fundamental protocol concepts not covered by existing resources, update
spectra-overviewinindex.ts. - Dissolution condition: Document when the new structure would no longer serve, in
docs/dissolution-conditions.md. Every Layer 3 hint, architectural pattern, and generative friction point carries a dissolution condition β a prompt for re-evaluation when circumstances change.
The goal: a cold-start agent reading only the tool descriptions and output hints should be able to use the tool correctly and compose it with other tools into novel analytical workflows.
Adding write capabilities (future)
To enable agents to actually execute strategies, you'd add tools that construct unsigned transactions via Spectra's Router contract. The agent would return the transaction calldata for the user to sign -- never holding keys.
Adding gauge/bribe data
Query the spectra-governance subgraph for current epoch votes, bribe amounts, and voter rewards. This is valuable for agents optimizing veSPECTRA voting strategies.
Not yet wired (API endpoints available)
These Spectra API endpoints are ready to be integrated. Create a new file in src/tools/, export register(), and import it in src/index.ts:
GET /v1/vision/{network}?tokens=...-- APR data for specific tokensGET /v1/watch-tower/{network}/transactions-- Conditional order dataGET /v1/{network}/metavaults/bridge/transactions-- MetaVault cross-chain bridge transaction data (bridged volume, in-flight amounts)
License
MIT
