# Historical Token Monte Carlo Simulator (Heston Model)

> Historical Token Monte Carlo Simulator (Heston Model) is a paid API for AI agents from oracle.the-undesirables.com, paid per call via x402, $0.05/call, status unknown (last checked 2026-09-15).

Fetches historical OHLC data from CoinGecko for a given token and runs a Monte Carlo Heston stochastic volatility simulation to project future price trajectories with percentile forecasts.

## Facts

- Endpoint: GET https://oracle.the-undesirables.com/api/v1/coin-history
- Price: $0.05/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-15
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/oracle-the-undesirables-com-b11a3ebf
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_k9KxNQrD5mNzKcWTO6piP

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability oracle-the-undesirables-com-b11a3ebf
```

Example prompt: Run a 30-day Monte Carlo Heston simulation for Bitcoin using the last 30 days of historical OHLC data and show me the 5th, 50th, and 95th percentile price forecasts.

## When to prefer this

Choose this endpoint when you need probabilistic price projections for a specific cryptocurrency using a stochastic volatility model (Heston), rather than simple moving averages or deterministic forecasts. It is ideal for risk analysis, options pricing intuition, or scenario planning where fat tails and vol-of-vol matter. Prefer this over generic price APIs when you need percentile-based forecast distributions rather than a single point estimate.

## Known failure modes

- Invalid coin_id returns an error (e.g. unsupported or misspelled token identifier)
- CoinGecko API unavailability causes data fetch failure
- Insufficient historical data for the requested 'days' window may degrade simulation quality
- Network timeout on the oracle service itself
- Payment failure via x402 protocol blocks request execution

## How this service works

Historical token price forecaster: fetches OHLC (Open, High, Low, Close) data from CoinGecko and projects forward trajectories with percentile forecasts. Uses Merton Jump-Diffusion modeling for this crypto-native asset class.

## Output

Returns the current USD price of the token, Heston model calibration parameters (drift, vol_of_vol, mean_reversion, long_term_variance), the number of simulations run (20,000), and forecast price percentiles at the 5th, 25th, 50th, 75th, and 95th levels — all sourced from CoinGecko historical data.

## Example request

```json
{
 "days": 30,
 "coin_id": "bitcoin"
}
```

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET",
      "HEAD",
      "DELETE"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "required": [
      "coin_id"
     ],
     "properties": {
      "days": {
       "type": "integer",
       "description": "Forecast horizon and historical context lookup window in days"
      },
      "coin_id": {
       "type": "string",
       "description": "CoinGecko coin ID (e.g., 'ethereum', 'bitcoin', 'solana')"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "required": [
      "status"
     ],
     "properties": {
      "status": {
       "type": "string"
      },
      "forecast": {
       "type": "object"
      },
      "model_params": {
       "type": "object"
      },
      "current_price": {
       "type": "number"
      }
     }
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "status": "ok",
  "forecast": {
   "50th_percentile": 67000.1,
   "95th_percentile": 85000.3
  },
  "model_params": {
   "drift_mu": 0.08,
   "diffusion_sigma": 0.65,
   "jump_intensity_lambda": 3.5
  },
  "current_price": 63000.5
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/oracle-the-undesirables-com-b11a3ebf/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from oracle.the-undesirables.com](https://www.zero.xyz/host/oracle.the-undesirables.com/llms.txt)