1. Authentication

The Prometheus Engine employs strict environment separation for authentication.

While the web dashboard utilizes standard OAuth2 Bearer JWT tokens, automated compute nodes, algorithmic scripts, and C++ routines must authenticate utilizing a static Master API Key.

To authenticate a programmatic request, inject your API key into the HTTP headers utilizing the X-API-Key field.

Security Directive: The plaintext API Key is dispatched only once during generation. Compromised keys must be immediately rolled from the dashboard.

Verify Access (Python)

import requests

url = "https://api.prometheusquantengine.com/api/v1/users/me"

headers = {
    "X-API-Key": "pmt_live_your_secure_api_key_here",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())

200 OK Response

{
  "email": "quant_engineer@hedgefund.com",
  "id": "f848ea57-e538-4a43-bbfa-44345d02e0e4",
  "is_active": true,
  "credits_balance": 50.000000,
  "has_api_key": true,
  "has_enterprise_access": false,
  "created_at": "2026-06-22T03:06:53.564Z"
}

2. Limits & Idempotency

Compute Ledger Cost

The billing engine calculates computational deductions deterministically. The total number of stochastic steps is evaluated as $N \times M$, where N represents total trajectories and M represents temporal observation steps (M=1 for European options).

Rate: 250,000,000 stochastic steps = 1.0000 Compute Credit.

Rate Limiting Subsystems

Prometheus evaluates request frequency based on computational weight:

Load Profile	Standard Tier	Enterprise Tier
≤ 50M Paths	10 req / minute	100 req / minute
> 50M Paths	3 req / minute	15 req / minute

Double-Spend Protection (Idempotency)

Network latency or 5xx timeouts can cause clients to mistakenly retry the same simulation payload, resulting in double credit deduction. To prevent this, inject a unique UUIDv4 into the Idempotency-Key header.

If the exact payload is resubmitted alongside a previously cached key (valid for 24 hours), the orchestrator will bypass the C++ engine and return the cached result mathematically intact, incurring a 0.00 Cr deduction.

Idempotency Injection

import requests
import uuid

url = "https://api.prometheusquantengine.com/api/v1/simulations"

headers = {
    "X-API-Key": "pmt_live_your_secure_api_key_here",
    "Idempotency-Key": str(uuid.uuid4()), # Generates unique hash
    "Content-Type": "application/json"
}

# The simulation dictionary
payload = {
    "simulation_type": "European",
    "s_0": 100.0,
    "strike": 100.0,
    "volatility": 0.20,
    "time_to_maturity": 1.0,
    "risk_free_rate": 0.05,
    "option_type": "Call",
    "n_simulations": 100000
}

# If the network fails here, resending the exact same request 
# with the same Idempotency-Key will return the cached result.
response = requests.post(url, json=payload, headers=headers)

3. Monte Carlo Pipeline

The core execution endpoint dynamically routes computations based on the simulation_type field.

Base Parameters

Every pricing payload strictly requires the following base invariants to compile:

s_0 (Decimal > 0): Initial Spot Price.
strike (Decimal > 0): Execution Strike.
volatility (Decimal): Annualized standard deviation [0.0, 5.0].
time_to_maturity (Decimal > 0): Vectorized in total years.
risk_free_rate (Decimal): Continuous risk-free yield.
option_type (String): Strictly "Call" or "Put".
n_simulations (Integer): Total paths. Minimum 10,000 to guarantee statistical significance, bounded at 1,000,000,000 to prevent memory overflow.

Standard European Execution

To compute a path-independent European option, set simulation_type: "European". The orchestrator processes this by implicitly assigning m_steps=1 to harness precise Control Variate computations.

Base European Payload

{
  "simulation_type": "European",
  "label": "EUR_Call_100k_Alpha",
  "s_0": 100.0,
  "strike": 100.0,
  "volatility": 0.20,
  "time_to_maturity": 1.0,
  "risk_free_rate": 0.05,
  "option_type": "Call",
  "n_simulations": 100000
}

201 Created (SimulationResponse)

{
  "id": "2b3a3ab5-ba9c-45c6-9df5-7a258a95c292",
  "user_id": "f848ea57-e538-4a43-bbfa-44345d02e0e4",
  "simulation_type": "European",
  "credits_cost": 0.000400,
  "label": "EUR_Call_100k_Alpha",
  "created_at": "2026-06-22T18:24:56.473Z",
  "fair_value": 10.450584,
  "ci_lower": 10.419271,
  "ci_upper": 10.602154,
  "delta": 0.635126,
  "gamma": 0.019049,
  "vega": 37.567720,
  "rho": 53.064256
}

4. Exotic Polymorphism

The Prometheus API utilizes a polymorphic ingestion layer. By modifying the simulation_type and appending specific parameters, the C++ engine dynamically switches its stochastic pricing algorithms.

Asian Options (Path-Dependent)

Asian options evaluate the payoff based on the arithmetic average of the asset's price over time. To trigger this module, set simulation_type: "Asian" and provide:

m_steps (Integer): Number of discrete temporal observation steps across the life of the option (e.g., 252 for daily trading days in a year).

Barrier Options (Knock-In / Knock-Out)

These contracts activate or extinguish when the underlying asset breaches a predetermined price level. To trigger this module, set simulation_type: "Barrier" and provide:

m_steps (Integer): The temporal resolution used to detect the barrier breach.
barrier_type (String): Must be strictly "DownAndOut", "DownAndIn", "UpAndOut", or "UpAndIn".
barrier_level (Decimal > 0): The absolute price threshold.

Asian Payload Example

{
  "simulation_type": "Asian",
  "s_0": 100.0,
  "strike": 100.0,
  "volatility": 0.20,
  "time_to_maturity": 1.0,
  "risk_free_rate": 0.05,
  "option_type": "Call",
  "n_simulations": 500000,
  "m_steps": 252
}

Barrier Payload Example

{
  "simulation_type": "Barrier",
  "s_0": 100.0,
  "strike": 100.0,
  "volatility": 0.20,
  "time_to_maturity": 1.0,
  "risk_free_rate": 0.05,
  "option_type": "Call",
  "n_simulations": 1000000,
  "m_steps": 252,
  "barrier_type": "DownAndOut",
  "barrier_level": 90.0
}

5. Asynchronous Polling (HPC)

To preserve network stability, any simulation exceeding 50,000,000 total computational steps ($N \times M > 50M$) is automatically intercepted and offloaded to our asynchronous Celery High-Performance Compute (HPC) cluster.

The TaskResponse Ticket

Instead of returning the mathematical matrices directly, the API will respond with a 201 Created status containing a TaskResponse object. This ticket includes a task_id used to track the progress of the worker node.

Long Polling Protocol

Clients should implement a polling loop against the /api/v1/simulations/task/{task_id} endpoint. The engine will emit one of four definitive states:

PENDING: The payload is enqueued in Redis waiting for CPU availability.
STARTED: The C++ routine is actively generating stochastic paths.
SUCCESS: Computation finished. The response will now contain the fair_value and simulation_id.
FAILURE: Extreme mathematical anomaly or node crash. Escrow credits are automatically refunded to your ledger.

Initial Task Ticket (Response)

{
  "status": "processing",
  "task_id": "a1b2c3d4-e5f6-7g8h-9i0j",
  "message": "Massive simulation successfully queued in the HPC cluster."
}

Python Polling Implementation

import requests
import time

task_id = "a1b2c3d4-e5f6-7g8h-9i0j"
url = f"https://api.prometheusquantengine.com/api/v1/simulations/task/{task_id}"
headers = {"X-API-Key": "pmt_live_your_secure_api_key_here"}

while True:
    response = requests.get(url, headers=headers).json()
    status = response.get("status")
    
    if status == "SUCCESS":
        print(f"Done! Fair Value: {response['fair_value']}")
        print(f"Simulation DB ID: {response['simulation_id']}")
        break
    elif status == "FAILURE":
        print("Engine crashed. Credits refunded.")
        break
        
    print(f"Worker Status: {status}. Polling again in 2 seconds...")
    time.sleep(2)

6. Audit & Ledger History

For rigorous accounting, Prometheus maintains an immutable financial ledger tracking all credit allocations, deductions, and refunds.

Ledger Querying

Submit a GET request to /api/v1/billing/history to fetch your ledger sequence. By default, the API filters out micro-deductions (compute costs) and returns only positive capital events (Credit Top-ups, Seed Allocations, and Automatic Refunds).

Data Retention: Ledger and Billing history are permanent. However, stochastic path outputs and simulation metadata are subject to our retention policy (7 days for Standard tier, 30 days for Enterprise) before being permanently purged.

GET /billing/history?only_credits=true

[
  {
    "id": "e4b3c2a1-9876-4a32-10fe-876543210fed",
    "user_id": "f848ea57-e538-4a43-bbfa-44345d02e0e4",
    "simulation_id": null,
    "amount": 6000.000000,
    "description": "Purchase - Hedge Pro Package (Order #1042)",
    "created_at": "2026-07-28T14:22:00.000Z"
  },
  {
    "id": "a1b2c3d4-e5f6-7g8h-9i0j-123456789abc",
    "user_id": "f848ea57-e538-4a43-bbfa-44345d02e0e4",
    "simulation_id": null,
    "amount": 50.000000,
    "description": "Seed Allocation - Verified Developer Provisioning",
    "created_at": "2026-07-26T00:00:00.000Z"
  }
]