@sperax/tool-backtesting

Backtest DeFi yield strategies against real historical data. Simulate how $10k in Aave, Curve, or Yearn would have performed over the past 6 months.

Strategy Backtesting 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-backtesting

Usage

Call it directly

import { backtestingExecutor } from '@sperax/tool-backtesting';

const result = await backtestingExecutor.invoke('runBacktest', {"chainId":1,"dcaFrequency":"daily"}, {
  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 { BacktestingManifest, backtestingExecutor } from '@sperax/tool-backtesting';

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: BacktestingManifest.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 backtestingExecutor.invoke(block.name, block.input, { messageId: response.id });
  console.log(result.content);
}

BacktestingManifest.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-backtesting

API reference

runBacktest

Backtest a DeFi yield strategy against real historical data from DefiLlama. Simulates daily compounding, tracks portfolio value, and returns key metrics: total return, annualized return, max drawdown, Sharpe ratio, and a comparison vs buying ETH or holding USDC.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | chainId | number | yes | Chain ID (e.g. 1 for Ethereum, 42161 for Arbitrum). | | dcaFrequency | daily | weekly | monthly | no | For DCA strategy: how often to buy. One of 'daily', 'weekly', 'monthly'. | | endDate | string | no | End date in ISO format (YYYY-MM-DD). Defaults to today. Max 2 years of history. | | initialCapital | number | yes | Initial capital in USD (e.g. 10000). | | protocol | string | yes | Protocol name to backtest (e.g. 'Aave V3', 'Curve Finance', 'Yearn Finance'). | | reinvestEarnings | boolean | no | Whether to compound (reinvest) earnings daily. Default: true. | | startDate | string | yes | Start date in ISO format (YYYY-MM-DD). Maximum 2 years in the past. | | strategy | yield_farming | dca | yield_rebalancing | static_hold | yes | Strategy type: 'yield_farming' (deploy into protocol and collect yield), 'dca' (dollar-cost average into a token), 'yield_rebalancing' (yield farm with periodic rebalancing), 'static_hold' (buy and hold token). | | targetToken | string | no | For DCA strategy: the CoinGecko token ID to accumulate (e.g. 'ethereum', 'bitcoin'). |

compareStrategies

Compare up to 5 DeFi strategies side-by-side over the same time period. Returns ranked results with the same set of metrics for each strategy.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | endDate | string | no | End date in ISO format. Defaults to today. | | initialCapital | number | yes | Initial capital in USD applied equally to each strategy. | | startDate | string | yes | Start date in ISO format. | | strategies | array | yes | Array of up to 5 strategies to compare. |

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-backtesting is one of many
• SperaxOS — the agent workspace these tools were built for

License

Apache-2.0