API Reference

Version: 0.5.2 Base URLs:

• https://mcp.aleatoric.systems — MCP JSON-RPC, MCP REST endpoints, and all /v1/* routes
• https://api.aleatoric.systems — alias for direct REST access (HTTP generation and streaming)

Authentication

All endpoints (except / and discovery endpoints) require authentication via X-API-Key header.

• Auth details and retry guidance: see Auth & Rate Limits

HTTP Endpoints

Batch Generation

Generate a static dataset for a specified duration and save it to disk.

POST /data/generate (also POST /v1/data/generate)

• Auth: Requires generate scope
• Timeout: Synchronous — generation + artifact upload must complete within 120 seconds or the endpoint returns 504. For duration_seconds that produce large datasets use POST /v1/jobs/generate (async, no HTTP timeout).

Request Body:

{
  "config": {
    "symbol": "BTC",
    "initial_price": 50000.0,
    "volatility_annual": 0.60,
    "seed": 42
  },
  "duration_seconds": 3600,
  "driver": {
    "multiprocess": true,
    "workers": 4,
    "window_seconds": 2.0,
    "max_retries": 5,
    "backoff_seconds": 1.25
  }
}

Response:

{
  "status": "completed",
  "download_url": "https://mcp.aleatoric.systems/artifacts/aleatoric_batch_xxx.parquet",
  "row_count": 15420,
  "storage_backend": "local",
  "content_length_bytes": 4523847,
  "job_id": "aleatoric_batch_xxx",
  "manifest_hash": "sha256:abc123..."
}

Live Stream

Subscribe to a real-time stream of market events via SSE.

GET /stream/live (also GET /v1/stream/live)

• Auth: Requires stream scope
• Content-Type: text/event-stream

Query Parameters:

Parameter	Type	Required	Default	Description
symbol	String	Yes	—	Ticker symbol (e.g., "BTCUSDT")
seed	Int	No	—	Random seed for reproducible streams
mode	String	No	single	Stream mode: single (standard L2 events) or composite_pair (interleaved spot+perp)
src_latency_mode	String	No	zero	Simulated source latency: zero (0ms), colocated (1–5ms), retail (50–200ms)
duration_s	Float	No	—	Stream duration in seconds. Omit for indefinite stream.

Single mode (default)

Standard L2 book snapshots and trade events in the Aleatoric wire format.

data: {"event_type": "trade", "price": 50123.50, "size": 0.05, "side": "buy", "timestamp_ms": ...}

data: {"event_type": "book", "bids": [...], "asks": [...], "timestamp_ms": ...}

Composite pair mode (mode=composite_pair)

Emits interleaved spot and perp events. Each SSE frame is a complete JSON object of one of two shapes:

Spot event:

{
  "type": "spot",
  "payload": {
    "ts": 1234567890000,
    "symbol": "BTCUSDT",
    "best_bid": 97001.20,
    "best_ask": 97001.50,
    "bid_qty": 0.84,
    "ask_qty": 1.55,
    "src_latency_ms": 1.2,
    "source_type": "trade",
    "depth_bids": [[97001.2, 0.84], [97000.8, 1.2], [97000.3, 0.9], [96999.7, 2.1], [96999.1, 1.5]],
    "depth_asks": [[97001.5, 1.55], [97001.9, 0.9], [97002.4, 1.1], [97003.0, 0.7], [97003.6, 2.3]]
  }
}

Perp event:

{
  "type": "perp",
  "payload": {
    "ts": 1234567890000,
    "symbol": "BTCUSDT",
    "mark": 97005.30,
    "index": 97001.35,
    "last_funding_rate": 0.00035,
    "next_funding_time": 1234596000000,
    "src_latency_ms": 0.8,
    "best_bid": 97005.10,
    "best_ask": 97005.50,
    "bid_qty": 2.1,
    "ask_qty": 1.8,
    "source_type": "trade",
    "depth_bids": [[97005.1, 2.1], [97004.7, 1.3], [97004.2, 0.8], [97003.6, 1.9], [97003.0, 1.1]],
    "depth_asks": [[97005.5, 1.8], [97005.9, 1.2], [97006.4, 0.6], [97007.0, 2.4], [97007.6, 0.9]]
  }
}

Field notes:

• mark: FDR-clean perp price = spot_mid × (1 + composite_basis_bps / 10000). The composite basis mean-reverts to ±2 bps aligned with the current funding sign (OU process, θ≈0.005, σ≈0.15 bps/tick, cap ±15 bps).
• index: FDR-clean spot price
• last_funding_rate: current 8h funding rate as raw decimal (e.g. 0.00035 = 3.5 bps)
• next_funding_time: epoch ms of the next settlement. Updates continuously as simulation advances.
• source_type: "trade" or "depth". Spot: ~70% trade / 30% depth. Perp: always "trade".
• src_latency_ms: simulated source latency, controlled by src_latency_mode. Drawn independently per instrument — spot and perp values differ even within the same engine tick.
• ts: each instrument receives an independent 0–2 ms sub-step jitter. Spot and perp timestamps at the same engine tick are distinct and not deterministically ordered — a perp event may arrive before its paired spot event. Events are emitted in natural timestamp order.
• depth_bids / depth_asks: first 5 levels as [[price, qty], ...]. Bids descending, asks ascending.

Calling composite_pair — examples

curl:

curl -N \
  -H "Authorization: Bearer $ALEATORIC_API_KEY" \
  "https://mcp.aleatoric.systems/stream/live?mode=composite_pair&symbol=BTCUSDT&seed=42&src_latency_mode=colocated"

Python (sseclient):

import json
import sseclient
import urllib.request

url = "https://mcp.aleatoric.systems/stream/live?mode=composite_pair&symbol=BTCUSDT&seed=42"
req = urllib.request.Request(url, headers={"Authorization": f"Bearer {api_key}"})

with urllib.request.urlopen(req) as resp:
    client = sseclient.SSEClient(resp)
    for event in client.events():
        msg = json.loads(event.data)
        if msg["type"] == "spot":
            spot = msg["payload"]
            print(f"SPOT  bid={spot['best_bid']}  ask={spot['best_ask']}  source={spot['source_type']}")
        elif msg["type"] == "perp":
            perp = msg["payload"]
            print(f"PERP  mark={perp['mark']}  funding={perp['last_funding_rate']:.5f}  next={perp['next_funding_time']}")

Python (httpx + asyncio):

import asyncio, json, httpx

async def stream_composite(api_key: str):
    url = "https://mcp.aleatoric.systems/stream/live"
    params = {"mode": "composite_pair", "symbol": "BTCUSDT", "seed": 42, "src_latency_mode": "zero"}
    headers = {"Authorization": f"Bearer {api_key}", "Accept": "text/event-stream"}

    async with httpx.AsyncClient(timeout=None) as client:
        async with client.stream("GET", url, params=params, headers=headers) as resp:
            async for line in resp.aiter_lines():
                if line.startswith("data:"):
                    msg = json.loads(line[5:].strip())
                    yield msg

asyncio.run(stream_composite("ak_live_..."))

Consuming with nowcaster schemas (TickSpotBook / TickPerpMark):

from binance_funding.io.schemas import TickSpotBook, TickPerpMark

async for msg in stream_composite(api_key):
    if msg["type"] == "spot":
        tick = TickSpotBook(**msg["payload"])
    elif msg["type"] == "perp":
        tick = TickPerpMark(**msg["payload"])

Bounded run (duration_s):

# Stream exactly 60 seconds of composite data
curl -N \
  -H "Authorization: Bearer $ALEATORIC_API_KEY" \
  "https://mcp.aleatoric.systems/stream/live?mode=composite_pair&symbol=BTCUSDT&duration_s=60"

Metrics

GET /metrics

• Prometheus exposition format
• Requires metrics scope

Data Models

Trade Event

{
  "event_type": "trade",
  "timestamp_ms": 1678886400123,
  "capture_time_ms": 1678886400125,
  "symbol": "BTC",
  "side": "buy",
  "price": 25000.0,
  "size": 0.1,
  "trade_id": "trd_8a7b9c...",
  "notional_usd": 2500.0
}

L2 Book Snapshot

{
  "event_type": "book",
  "timestamp_ms": 1678886400100,
  "capture_time_ms": 1678886400102,
  "symbol": "BTC",
  "bids": [{"price": 24999.5, "size": 1.2}, ...],
  "asks": [{"price": 25000.5, "size": 0.8}, ...],
  "best_bid": 24999.5,
  "best_ask": 25000.5,
  "mid_price": 25000.0,
  "spread_bps": 4.0
}

MCP JSON-RPC 2.0 Protocol

The primary interface for MCP clients. Implements the standard Model Context Protocol.

POST /mcp

• Protocol: JSON-RPC 2.0
• Version: 2024-11-05
• Auth: Requires X-API-Key header

Methods

Method	Description
initialize	Handshake with protocol version and server capabilities
tools/list	List all available tools with JSON Schema inputSchema
tools/call	Execute a tool by name with arguments
ping	Connection health check

Example: Initialize

// Request
{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"clientInfo": {"name": "my-client", "version": "1.0"}}}

// Response
{"jsonrpc": "2.0", "id": 1, "result": {"protocolVersion": "2024-11-05", "serverInfo": {"name": "aleatoric-engine", "version": "0.5.2"}, "capabilities": {"tools": {}}}, "error": null}

Example: Call Tool

// Request
{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "get_health", "arguments": {}}}

// Response
{"jsonrpc": "2.0", "id": 2, "result": {"content": [{"type": "text", "text": "{\"status\": \"ok\", \"timestamp\": \"...\"}"}], "isError": false}, "error": null}

Available Tools

Tool	Description
get_health	Lightweight health check
get_presets	List simulation presets
get_config_schema	Get SimulationManifest JSON Schema
validate_config	Validate configs and compute deterministic hash
generate_dataset	Generate synthetic market data batches
normalize_events	Normalize exchange data to canonical format
simulate_funding_regime	Calculate funding rates across venues. Returns periods[] array alongside scalar fields (v0.5.2).
get_venue_details	Get exchange adapter capabilities
get_cache_stats	Cache statistics

Discovery Endpoints (Public)

Endpoint	Description
GET /mcp/tools/list	Tool discovery (no auth required)
GET /.well-known/mcp.json	MCP Server Card for registries
GET /.well-known/mcp-config	Session configuration schema

Legacy MCP HTTP Endpoints

Direct HTTP endpoints (for backwards compatibility). All require mcp scope via X-API-Key header.

Configuration & Schema

Endpoint	Description
GET /mcp/manifest	MCP manifest describing available tools
GET /mcp/config/schema	JSON Schema for SimulationManifest
POST /mcp/config/validate	Validate config and compute hash
POST /mcp/generate_dataset	Generate batch data (MCP Tool)
GET /mcp/presets	List available preset configurations
GET /mcp/venues/{exchange}	Venue details (binance, hyperliquid, okx, bybit, cme, sgx)
GET /mcp/health	MCP health check

Data Normalization

POST /mcp/normalize

Normalize market events from various sources to canonical format.

{
  "source": "binance",
  "symbol": "BTCUSDT",
  "events": [{ "payload": { ... } }, ...],
  "stream": false,
  "enable_cache": false
}

Supported sources: synthetic, hyperliquid, binance, cme, sgx

Funding Simulation

POST /mcp/simulate_funding_regime

Request body:

{
  "exchange": "binance",
  "spot_price": 50000.0,
  "mark_price": 50050.0,
  "position_size": 1.0,
  "num_periods": 3,
  "use_soft_cap": true,
  "seed": 42
}

Request parameters:

Parameter	Type	Required	Default	Description
exchange	String	Yes	—	binance, hyperliquid, okx, bybit, cme, sgx
spot_price	Number	Yes	—	Current spot price
mark_price	Number	Yes	—	Current mark/perp price
position_size	Number	No	—	Optional position size for PnL calculation
num_periods	Int	No	1	Number of forward funding periods to return (max ~12)
seed	Int	No	—	Seed for deterministic multi-period generation
use_soft_cap	Bool	No	true	Apply exchange soft cap to funding rate

The response includes scalar funding fields (funding_rate, funding_rate_bps, premium_bps, perp_price, etc.) plus a periods array containing one entry per settlement interval:

{
  "exchange": "binance",
  "funding_rate": 0.00035,
  "funding_rate_bps": 3.5,
  "premium_bps": 4.2,
  "perp_price": 50052.1,
  "settlement_times": ["2026-03-01T08:00:00+00:00", ...],
  "interval_hours": 8,
  "annualized_rate": 0.3832,
  "periods": [
    {
      "period_index": 0,
      "start_ts_ms": 1234567200000,
      "next_funding_time": 1234596000000,
      "funding_rate": 0.00035,
      "funding_rate_bps": 3.5,
      "premium_bps": 4.2
    },
    {
      "period_index": 1,
      "start_ts_ms": 1234596000000,
      "next_funding_time": 1234624800000,
      "funding_rate": -0.00040,
      "funding_rate_bps": -4.0,
      "premium_bps": -3.8
    }
  ]
}

Period 0 always reflects the model-computed rate for the current interval. Subsequent periods use an alternating-sign template with seeded noise — both positive and negative funding periods are guaranteed for num_periods > 1. Existing clients that only read the scalar response fields are unaffected.

Calling simulate_funding_regime — examples

curl (single period):

curl -s -X POST https://mcp.aleatoric.systems/mcp/simulate_funding_regime \
  -H "Authorization: Bearer $ALEATORIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"exchange":"binance","spot_price":97001.0,"mark_price":97005.3}'

curl (multi-period schedule, deterministic):

curl -s -X POST https://mcp.aleatoric.systems/mcp/simulate_funding_regime \
  -H "Authorization: Bearer $ALEATORIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange": "binance",
    "spot_price": 97001.0,
    "mark_price": 97005.3,
    "num_periods": 6,
    "seed": 42
  }' | jq '.periods[] | {period: .period_index, rate_bps: .funding_rate_bps}'

Python:

import requests

resp = requests.post(
    "https://mcp.aleatoric.systems/mcp/simulate_funding_regime",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "exchange": "binance",
        "spot_price": 97001.0,
        "mark_price": 97005.3,
        "num_periods": 3,
        "seed": 42,
    },
)
data = resp.json()

# Scalar (backward-compatible)
print(f"Current rate: {data['funding_rate_bps']:.2f} bps")

# Multi-period schedule
for p in data["periods"]:
    sign = "+" if p["funding_rate"] >= 0 else ""
    print(f"  Period {p['period_index']}: {sign}{p['funding_rate_bps']:.1f} bps  next={p['next_funding_time']}")

MCP tool call (JSON-RPC):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "simulate_funding_regime",
    "arguments": {
      "exchange": "binance",
      "spot_price": 97001.0,
      "mark_price": 97005.3,
      "num_periods": 6,
      "seed": 42
    }
  }
}

Cache Management

Endpoint	Description
GET /mcp/caches/stats	Cache list + compression totals
GET /mcp/caches/{cache_key}/manifest	Provenance metadata
GET /mcp/caches/export/{cache_key}	Download Parquet file
GET /mcp/caches/stream/{cache_key}	SSE replay of cached events
DELETE /mcp/caches/{cache_key}	Delete single cache entry
DELETE /mcp/caches?confirm=true	Clear all caches

Schemas & Contracts {#schemas—contracts}

• SimulationManifest fields: see /docs/configuration
• MCP tools match mcp.json; parity tests in tests/test_mcp_manifest_parity.py
• Artifacts include job_id, manifest_hash, row_count