Agentic API

Agentic Primitives are read-only analytics: stateless objects that answer a specific question about an LP position or pool, and return a structured typed dataclass. They never mutate pool state. Same call shape from a Jupyter notebook or from Claude calling them as tools.

This page is the API reference index. For the conceptual overview and the agentic-loop walkthrough, see Agentic Primitives under Concepts. For the per-class detail pages — including signatures, parameter tables, and runnable examples — see the category links below.

Caution

Per-class API pages for each of the 21 agentic primitives are in progress. The links under “Per-category indexes” below currently land on the existing prose-style category pages, which already cover the primitives at the level of “what they answer” and “how to call them.” A scikit-learn-style class browser with a strict template (signature → parameters → returns → example) is coming in a follow-up pass.

Per-category indexes

Category	Primitives	What it answers
Position Analysis	AnalyzePosition, AnalyzeBalancerPosition, AnalyzeStableswapPosition	Why is this LP position gaining or losing money? IL decomposition, fee income, net PnL.
Price Scenarios	SimulatePriceMove, SimulateBalancerPriceMove, SimulateStableswapPriceMove	What happens if the price moves X%? Forward IL, projected position value.
Pool Health	CheckPoolHealth, DetectRugSignals, DetectFeeAnomaly	Is this pool healthy? Concentration, activity, fee anomalies, rug signals.
Risk	CheckTickRangeStatus, AssessDepegRisk	Tick-range proximity (V3); depeg-IL across scenarios (Stableswap).
Optimization	EvaluateTickRanges, EvaluateRebalance, OptimalDepositSplit	Tick-range candidate evaluation, rebalance cost-vs-benefit, V2 zap-in α.
Comparison	CompareFeeTiers, CompareProtocols	Fee-tier comparison (V3); cross-protocol comparison (V2/V3/Balancer/Stableswap).
Execution	CalculateSlippage, DetectMEV	Trade slippage decomposition; theoretical-vs-actual comparison for MEV detection.
Portfolio	AggregatePortfolio	Multi-position aggregation across protocols, with worst-first PnL ranking.
Break-Even	FindBreakEvenPrice, FindBreakEvenTime	At what price / how long until fees break even with IL? (V2 + V3.)

The agentic primitive contract

Every agentic primitive follows the same contract:

result = ClassName().apply(lp, ...args)

• Stateless construction. ClassName() takes no parameters.
• .apply() does the work. The pool object and any analysis-specific arguments (token amounts, scenario parameters, ranges) are passed at call time.
• Read-only. Pool state is never modified. Run as many times as you like at the same pool snapshot — the result is deterministic.
• Returns a typed dataclass. Every primitive defines its own result dataclass — PositionAnalysis, PoolHealth, DepegRiskAssessment, etc. — with named fields a caller can destructure, serialize, or render.

For the dataclass definitions themselves see Result Dataclasses. For tool schemas (MCP) see Tool Schemas.

See also

• Agentic Primitives — concepts and overview
• The Primitive Contract — design rationale
• Tool Schemas — MCP-format schemas for LLM tool-use
• Twin Reference — the defipy.twin State Twin API
• Tools Reference — the defipy.tools schema-emission API