API Reference

Version: 0.4.7 Base URL: https://mcp.aleatoric.systems (hosted)

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

Auth: Requires generate scope

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

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

Query Parameters:

Parameter	Type	Required	Description
`symbol`	String	Yes	Ticker symbol (e.g., `"BTCUSDT"`)
`seed`	Int	No	Random seed for reproducible streams

Stream Format (SSE):

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

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

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.4.7"}, "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
`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

{
  "exchange": "binance",
  "spot_price": 50000.0,
  "mark_price": 50050.0,
  "position_size": 1.0,
  "num_periods": 10,
  "use_soft_cap": true,
  "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