@sperax/tool-il-calculator

Advanced impermanent loss calculator with concentrated liquidity support, Monte Carlo simulation, hedge recommendations, and fee-adjusted P&L tracking

IL Calculator is an agent tool from SperaxOS, packaged headless so you can call it from any agent framework. It ships two things: the manifest — a JSON-Schema function definition a model can call — and the executor that runs the call against the real API.

There is no UI layer and no framework lock-in. It works anywhere TypeScript runs.

Install

npm install @sperax/tool-il-calculator

Usage

Call it directly

import { ilCalculatorExecutor } from '@sperax/tool-il-calculator';

const result = await ilCalculatorExecutor.invoke('calculateIL', {"currentPriceRatio":1,"daysActive":1}, {
  messageId: 'msg-1',
});

console.log(result.content); // prose summary written for the model to read
console.log(result.state);   // typed data payload for your own UI

Give it to a model

import Anthropic from '@anthropic-ai/sdk';
import { ILCalculatorManifest, ilCalculatorExecutor } from '@sperax/tool-il-calculator';

const client = new Anthropic();

const response = await client.messages.create({
  model: 'claude-opus-4-8',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Ask something this tool can answer' }],
  tools: ILCalculatorManifest.api.map((api) => ({
    name: api.name,
    description: api.description,
    input_schema: api.parameters,
  })),
});

for (const block of response.content) {
  if (block.type !== 'tool_use') continue;
  const result = await ilCalculatorExecutor.invoke(block.name, block.input, { messageId: response.id });
  console.log(result.content);
}

ILCalculatorManifest.api is already in JSON-Schema form, so it maps onto any tool-calling API — Anthropic, OpenAI, the Vercel AI SDK, or an MCP server — without translation.

Every executor returns a BuiltinToolResult — { success, content, state }. content is prose written for the model to read; state is the typed data payload for your own code. Executors never throw: a failed call comes back as { success: false, content: '<reason>' }, so a network blip degrades the answer instead of crashing the agent loop.

Configuration

None. This tool calls a public API directly and needs no key or origin configuration.

Tool identifier

sperax-il-calculator

API reference

calculateIL

Calculate impermanent loss for a token pair LP position. Supports both standard AMM (x*y=k) and concentrated liquidity (Uni V3). Shows IL, fee earnings offset, net P&L, and break-even timeline.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | currentPriceRatio | number | no | Current price ratio (token0/token1). If omitted, fetched from live data. | | daysActive | number | no | Days the position has been active (for fee earnings estimation). | | entryPriceRatio | number | yes | Entry price ratio (token0/token1) when the position was opened. | | feeTier | number | no | Fee tier as decimal (e.g. 0.003 for 0.3%). Used for fee earnings estimation. | | investmentUsd | number | yes | Total investment in USD. | | priceLower | number | no | For concentrated liquidity: lower price bound of the range. | | priceUpper | number | no | For concentrated liquidity: upper price bound of the range. | | token0 | string | yes | First token symbol (e.g. "ETH"). | | token1 | string | yes | Second token symbol (e.g. "USDC"). |

trackPositionIL

Track real-time impermanent loss for an on-chain LP position. Fetches live data and shows current IL, fee earnings, and net position value.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | chain | string | yes | Chain name (e.g. "ethereum", "arbitrum"). | | poolAddress | string | no | Pool contract address (alternative to positionId). | | positionId | string | no | On-chain position ID or NFT token ID (for Uni V3). | | protocol | string | yes | Protocol name (e.g. "uniswap_v3", "curve", "balancer"). | | walletAddress | string | no | Wallet address that owns the position. |

simulateILScenarios

Run Monte Carlo simulation of future impermanent loss scenarios. Shows probability distributions, worst/best/expected cases, and confidence intervals.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | currentPriceRatio | number | no | Current price ratio. If omitted, fetched live. | | feeTier | number | no | Fee tier for fee earning simulation. | | investmentUsd | number | yes | Investment amount in USD. | | numSimulations | number | no | Number of Monte Carlo paths. Default: 1000. | | priceLower | number | no | For concentrated liquidity: lower price bound. | | priceUpper | number | no | For concentrated liquidity: upper price bound. | | timeHorizonDays | number | yes | Simulation time horizon in days. | | token0 | string | yes | First token symbol. | | token1 | string | yes | Second token symbol. |

getHedgeRecommendation

Get hedge recommendations to offset impermanent loss. Suggests options, perp shorts, structured products, and calculates cost vs coverage tradeoff.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | chain | string | no | Preferred chain for on-chain hedge venues. | | currentILUsd | number | yes | Current IL in USD (or estimated future IL). | | positionSizeUsd | number | yes | LP position size in USD. | | riskTolerance | string | yes | Risk tolerance: "conservative", "moderate", or "aggressive". | | token0 | string | yes | First token of the pair. | | token1 | string | yes | Second token of the pair. |

getHistoricalILAttribution

Get historical IL attribution breakdown across all wallet LP positions. Shows cumulative IL, fee earnings, and net P&L with daily breakdown.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | chain | string | yes | Chain to analyze (or "all" for cross-chain). | | periodDays | number | yes | Historical period in days. Default: 30. | | protocol | string | no | Filter to specific protocol. | | walletAddress | string | yes | Wallet address to analyze. |

Types

Shared types come from @sperax/agent-tools-core: BuiltinToolManifest, BuiltinToolResult, BuiltinToolContext, and the BaseExecutor class every tool executor extends.

Related

• @sperax/agent-tools-core — the tool contract
• All SperaxOS agent tools — tool-il-calculator is one of many
• SperaxOS — the agent workspace these tools were built for

License

Apache-2.0