Skip to main content

​
POST /backtest

Run a backtest for Aave lending and borrowing strategies.

​
Request Body

​
user
string
required
User ID for the backtest
​
start_ts
integer
required
Starting timestamp (Unix epoch seconds)
​
steps
integer
required
Number of simulation steps to run
​
initial_wallet
object
required
Initial token balances. Map of token ID to amount (e18 string format)Example: {"1": "10000000000000000000"} for 10 ETH
​
tokens
object
required
Token symbol to ID mappingExample: {"ETH": 1, "USDC": 2}
​
protocol_ids
object
required
Protocol identifiers
  • aave_id (string, optional): Aave protocol ID
  • lido_id (string, optional): Lido protocol ID
  • uniswap_id (string, optional): Uniswap protocol ID
​
price_config
object
required
Price data configuration. Must include kind field with one of:
  • constant: Fixed prices
  • simulated: GBM-based price simulation
  • historical: Real historical price data
​
strategy
object
required
Strategy configuration. Must include kind field with one of:
  • aave_supply_only: Simple supply strategy
  • aave_supply_borrow_once: Supply and borrow once
  • lido_stake_wrap_supply: Stake ETH with Lido, wrap to wstETH, supply to Aave
  • aave_leverage_band: Automated leverage band controller
​
rates_config
object
Optional interest rates configuration
  • variable_borrow_rates: Map of token symbol to rate per tick (RAY format)
  • supply_rates: Optional supply rates
​
simulation
object
Optional simulation parameters
  • gas_price_gwei (integer): Gas price in gwei
  • gas_token (integer): Token ID for gas payments (default: 1 for ETH)
  • on_shortfall (string): Policy when user cannot pay gas - “reject_tx” or “allow_debt”

​
Response

​
snapshots
array
Array of snapshots at each simulation step
​
ts
integer
Timestamp
​
engine_step
integer
Simulation step number
​
aave_dep_value_e18
integer
Total Aave deposit value (e18 format)
​
aave_debt_value_e18
integer
Total Aave debt value (e18 format)
​
hf_bps
integer
Health factor in basis points
​
net_value_e18
integer
Net portfolio value (e18 format)
​
gas_cost_usd
number
Gas costs for this step in USD
​
summary
object
Backtest summary statistics
​
ticks
integer
Total number of ticks executed
​
min_hf_bps
integer
Minimum health factor (basis points)
​
max_hf_bps
integer
Maximum health factor (basis points)
​
max_drawdown_e18
integer
Maximum drawdown (e18 format)
​
terminal_net_e18
integer
Final net value (e18 format)
​
initial_net_e18
integer
Initial net value (e18 format)
​
total_pnl_e18
integer
Total profit/loss (e18 format, can be negative)
​
vol_annual
number
Annualized volatility
​
sharpe
number
Sharpe ratio
​
sortino
number
Sortino ratio
​
total_return
number
Total return percentage
​
apr
number
Annual percentage rate
​
apy
number
Annual percentage yield
​
wins
integer
Number of winning periods
​
losses
integer
Number of losing periods
​
win_rate
number
Win rate percentage
​
total_gas_cost_usd
number
Total gas costs in USD

​
Example Request

curl -X POST http://localhost:8080/backtest \
  -H "Content-Type: application/json" \
  -d '{
    "user": "user1",
    "start_ts": 1704067200,
    "steps": 100,
    "initial_wallet": {
      "1": "10000000000000000000"
    },
    "tokens": {
      "ETH": 1,
      "USDC": 2
    },
    "protocol_ids": {
      "aave_id": "aave-v3"
    },
    "price_config": {
      "kind": "historical",
      "range": {
        "start_ts": 1704067200,
        "end_ts": 1704153600
      },
      "interval_secs": 3600,
      "routes": [
        {
          "key": "ETH",
          "target": "aave-v3",
          "token_id": 1
        }
      ]
    },
    "strategy": {
      "kind": "aave_supply_only",
      "token": 1,
      "deposit_units_e18": "5000000000000000000"
    }
  }'

​
Example Response

{
  "snapshots": [
    {
      "ts": 1704067200,
      "engine_step": 0,
      "aave_dep_value_e18": 15000000000000000000,
      "aave_debt_value_e18": 0,
      "hf_bps": 0,
      "net_value_e18": 15000000000000000000,
      "gas_cost_usd": 0.5
    }
  ],
  "summary": {
    "ticks": 100,
    "min_hf_bps": 15000,
    "max_hf_bps": 25000,
    "max_drawdown_e18": 500000000000000000,
    "terminal_net_e18": 15500000000000000000,
    "initial_net_e18": 15000000000000000000,
    "total_pnl_e18": 500000000000000000,
    "vol_annual": 0.25,
    "sharpe": 1.5,
    "sortino": 2.1,
    "total_return": 3.33,
    "apr": 12.5,
    "apy": 13.2,
    "wins": 65,
    "losses": 35,
    "win_rate": 65.0,
    "total_gas_cost_usd": 50.0
  }
}

​
POST /backtest/uniswap

Run a backtest for Uniswap liquidity provision strategies.

​
Request Body

​
user
string
required
User ID for the backtest
​
start_ts
integer
required
Starting timestamp (Unix epoch seconds)
​
end_ts
integer
required
Ending timestamp (Unix epoch seconds)
​
steps
integer
required
Number of simulation steps
​
initial_wallet
object
required
Initial token balances. Map of token ID to amount (u128)
​
tokens
object
required
Token symbol to ID mapping
​
pool_config
object
required
Uniswap pool configuration
  • pool_address (string): Pool contract address
  • token0 (integer): First token ID
  • token1 (integer): Second token ID
  • fee_tier (integer): Fee tier (e.g., 500, 3000)
  • tick_spacing (integer): Tick spacing
​
strategy
object
required
Strategy configuration. Must include kind field with one of:
  • simple_market_maker: Basic liquidity provision
  • concentrated_liquidity: V3-style concentrated liquidity
  • v4_hook_strategy: V4 hook testing
  • bunni_hook: Bunni protocol hooks
  • kyber_hook: Kyber DMM hooks
​
market_data_config
object
required
Market data source configuration. Must include kind field:
  • mock: Simulated market data
  • subgraph: Historical subgraph data
​
simulation
object
Optional simulation parameters (gas configuration)

​
Response

​
snapshots
array
Array of snapshots at each step with detailed market data and position info
​
summary
object
Uniswap backtest summary
​
ticks
integer
Total ticks executed
​
initial_value_usd
number
Initial portfolio value in USD
​
final_value_usd
number
Final portfolio value in USD
​
total_return_percentage
number
Total return percentage
​
annualized_return
number
Annualized return
​
max_drawdown_percentage
number
Maximum drawdown percentage
​
total_fees_earned_usd
number
Total fees earned in USD
​
total_impermanent_loss_usd
number
Total impermanent loss in USD
​
sharpe_ratio
number
Sharpe ratio
​
sortino_ratio
number
Sortino ratio
​
calmar_ratio
number
Calmar ratio
​
rebalance_count
integer
Number of rebalances executed
​
gas_costs_usd
number
Total gas costs in USD
​
net_profit_after_costs
number
Net profit after all costs
​
performance_metrics
object
Detailed performance metrics including win rate, profit factor, APY, and trade statistics
​
step_results
array
Detailed results for each simulation step
​
success
boolean
Whether the backtest completed successfully
​
message
string
Status message

​
Example Request

curl -X POST http://localhost:8080/backtest/uniswap \
  -H "Content-Type: application/json" \
  -d '{
    "user": "user1",
    "start_ts": 1704067200,
    "end_ts": 1704153600,
    "steps": 100,
    "initial_wallet": {
      "1": 10000000000000000000,
      "2": 30000000000
    },
    "tokens": {
      "ETH": 1,
      "USDC": 2
    },
    "pool_config": {
      "pool_address": "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
      "token0": 2,
      "token1": 1,
      "fee_tier": 500,
      "tick_spacing": 10
    },
    "strategy": {
      "kind": "concentrated_liquidity",
      "pool_address": "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
      "token0": 2,
      "token1": 1,
      "price_range_bps": 500,
      "capital_efficiency": 2.0,
      "auto_compound": true
    },
    "market_data_config": {
      "kind": "mock",
      "base_price": 3000.0,
      "volatility": 0.5,
      "volume_pattern": "random",
      "liquidity_depth": 10000000.0
    }
  }'

​
Example Response

{
  "snapshots": [],
  "summary": {
    "ticks": 100,
    "initial_value_usd": 60000.0,
    "final_value_usd": 62500.0,
    "total_return_percentage": 4.17,
    "annualized_return": 52.8,
    "max_drawdown_percentage": 2.5,
    "total_fees_earned_usd": 2800.0,
    "total_impermanent_loss_usd": 350.0,
    "sharpe_ratio": 1.8,
    "sortino_ratio": 2.4,
    "calmar_ratio": 21.12,
    "max_liquidity_utilization": 0.95,
    "avg_price_impact_bps": 5.0,
    "rebalance_count": 12,
    "gas_costs_usd": 75.0,
    "net_profit_after_costs": 2375.0
  },
  "performance_metrics": {
    "total_return_percentage": 4.17,
    "annualized_return_percentage": 52.8,
    "volatility_percentage": 15.2,
    "sharpe_ratio": 1.8,
    "sortino_ratio": 2.4,
    "max_drawdown_percentage": 2.5,
    "win_rate_percentage": 68.0,
    "profit_factor": 2.5,
    "calmar_ratio": 21.12,
    "apy_percentage": 68.5,
    "total_trades": 12,
    "fees_to_gas_ratio": 37.33
  },
  "step_results": [],
  "success": true,
  "message": "Backtest completed successfully"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us