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": "[email protected]",
  "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.

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"
}

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
}

# Resending this exact request prevents double-billing
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.

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
}

4. Exotic Polymorphism

By modifying the simulation_type and appending specific parameters, the C++ engine dynamically switches its stochastic pricing algorithms.

Asian Options (Path-Dependent)

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)

m_steps (Integer): Temporal resolution used to detect the barrier breach.
barrier_type (String): Strictly "DownAndOut", "DownAndIn", "UpAndOut", or "UpAndIn".
barrier_level (Decimal > 0): Absolute price threshold.

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 cluster.

The TaskResponse Ticket

Instead of returning the mathematical matrices directly, the API responds with a 201 Created status containing a TaskResponse object. This ticket includes a task_id.

Long Polling Protocol

Clients should poll the /api/v1/simulations/task/{task_id} endpoint. The engine emits:

PENDING: Enqueued in Redis.
STARTED: C++ routine actively generating stochastic paths.
SUCCESS: Computation finished. Yields matrices.
FAILURE: Extreme anomaly. Credits automatically refunded.

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.

Data Retention: Ledger and Billing history are permanent. Stochastic path outputs and metadata are purged after 7 days (Standard) or 30 days (Enterprise).

GET /billing/history

[
  {
    "id": "a1b2c3d4-e5f6-7g8h-9i0j-123456789abc",
    "amount": 50.000000,
    "description": "Seed Allocation - Verified Developer Provisioning",
    "created_at": "2026-07-26T00:00:00.000Z"
  }
]