Documentation

Introduction

Welcome to Driftwood! This API allows you to programmatically generate thousands of stock price trajectories to model equity risk, calculate Value-at-Risk (VaR), and estimate options pricing directly in your own applications. Under the hood, Driftwood runs a Monte Carlo simulation engine powered by Geometric Brownian Motion (GBM) using historical stock drift and volatility.

Our API is entirely stateless and does not require any authentication keys. You can plug it directly into your dashboards, financial planning tools, options calculators, or research notebooks to bring interactive probability models to your users.

The Simulator Endpoint

Send a POST request to /v1/simulate to run a simulation.

Ways to Use the API

curl -X POST http://localhost:8000/v1/simulate \
  -H "Content-Type: application/json" \
  -d '{"ticker": "AAPL", "days": 30, "simulations": 100}'

fetch("http://localhost:8000/v1/simulate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    ticker: "AAPL",
    days: 30,
    simulations: 100
  })
})
.then(res => res.json())
.then(data => {
  console.log("Current Price:", data.current_price);
  console.log("P50 (Median) Path:", data.percentiles.p50);
});

import urllib.request
import json

url = "http://localhost:8000/v1/simulate"
payload = {"ticker": "AAPL", "days": 30, "simulations": 100}

req = urllib.request.Request(
    url,
    data=json.dumps(payload).encode("utf-8"),
    headers={"Content-Type": "application/json"},
    method="POST"
)

with urllib.request.urlopen(req) as response:
    data = json.loads(response.read().decode("utf-8"))
    print(f"Median final price: {data['metrics']['p50_final']}")

<iframe
  src="http://localhost:3000/?ticker=AAPL&days=30&sims=100&embed=true"
  width="100%"
  height="420"
  frameborder="0"
  style="border: 1px solid #e2e8f0;"
></iframe>

Response JSON Structure

The API returns a clean JSON object containing:

• ticker: The ticker symbol.
• current_price: The last recorded closing price.
• percentiles: Arrays for the P10 (Bearish), P50 (Median), and P90 (Bullish) price paths.
• paths: A list of 100 sample simulated raw paths for background visual rendering.
• metrics: Summary stats including mean_final, volatility_annual, and prob_profit (probability that the price ends higher than the starting price).

Rate Limits & Client-Side Caching

To guarantee high availability and protect upstream resources, the Driftwood API enforces a rate limit of 100 requests per 5 seconds per IP address. If you exceed this rate, the API will return an HTTP 429 Too Many Requests response.

We strongly recommend caching simulation data in your own clients or backend proxy layers. Since stock trajectories rely on daily historical prices, running multiple identical simulations within the same day is redundant.