API REFERENCE
Integrate institutional-grade AI forecasting into your platform.
OVERVIEW
The ModelMango API provides direct access to the Hydra V5 Engine. Designed for high-frequency adaptation, it utilizes an asynchronous task queue architecture to handle complex inference loads efficiently.
Unlike standard REST APIs that block until completion, our system returns a task_id immediately, allowing your application to poll for results without timeouts.
- Async Architecture: Non-blocking submission with task polling.
- Hydra Intelligence: Returns not just prices, but Regime (Bull/Bear/Crash) and Confidence scores.
- Multi-Asset: Supports Stocks, Crypto, Forex, and Indices in a single request.
ENDPOINTS
1. Submit Prediction Task
Submit a list of symbols for analysis. Returns a unique task_id.
https://api.modelmango.co/api/v1/custom/predict1{
2 "symbols": ["AAPL.US", "BTC-USD", "EURUSD.FOREX"]
3}2. Retrieve Status & Results
Check the status of your task. Once "COMPLETED", the full dataset is returned.
https://api.modelmango.co/api/v1/custom/predict/status/{task_id}1{
2 "task_id": "550e8400-e29b-41d4-a716-446655440000",
3 "status": "COMPLETED",
4 "created_at": 1715421200.5,
5 "results": [
6 {
7 "symbol": "BTC-USD",
8 "prediction_date": "2025-05-12T00:00:00",
9 "predicted_close": 68500.50,
10 "predicted_high": 69200.00,
11 "predicted_low": 67800.00,
12 "ai_regime": "BULL", // Hydra Regime: NORMAL, BULL, BEAR, CRASH
13 "ai_direction": "BULL", // Trend Direction: NEUTRAL, BULL, BEAR
14 "ai_confidence": 0.89, // Confidence Score (0.0 - 1.0)
15 "ai_duration": 48, // Forecast Horizon (Hours)
16 "status": "COMPLETED",
17 "message": "Success"
18 }
19 ]
20}PYTHON INTEGRATION
Production-ready implementation handling the async polling pattern with timeout protection.
1import requests
2import time
3import os
4
5# CONFIGURATION
6API_URL = "https://api.modelmango.co/api/v1/custom"
7API_KEY = os.getenv('MODELMANGO_API_KEY')
8
9def get_hydra_forecast(symbols):
10 """
11 Submits a prediction job and polls for Hydra V5 results.
12 Implements exponential backoff and timeout handling.
13 """
14 session = requests.Session()
15 session.headers.update({"X-Api-Key": API_KEY, "Content-Type": "application/json"})
16
17 # 1. Submit Job (Async)
18 try:
19 resp = session.post(f"{API_URL}/predict", json={"symbols": symbols}, timeout=10)
20 resp.raise_for_status()
21 task_id = resp.json()["task_id"]
22 print(f"Task submitted: {task_id}")
23 except requests.exceptions.RequestException as e:
24 return {"error": f"Submission failed: {str(e)}"}
25
26 # 2. Poll for Results (Max 30s)
27 start_time = time.time()
28 while time.time() - start_time < 30:
29 time.sleep(1) # Backoff
30 try:
31 status_resp = session.get(f"{API_URL}/predict/status/{task_id}", timeout=5)
32 if status_resp.status_code != 200: continue
33
34 data = status_resp.json()
35 status = data.get("status")
36
37 if status == "COMPLETED":
38 return data["results"]
39
40 if status == "FAILED":
41 return {"error": data.get("error", "Unknown server error")}
42
43 except requests.exceptions.RequestException:
44 continue # Retry on network blip
45
46 return {"error": "Timeout waiting for inference"}
47
48if __name__ == "__main__":
49 # Example: Check Bitcoin and Nvidia
50 forecasts = get_hydra_forecast(["BTC-USD", "NVDA.US"])
51 print(forecasts)
52RESPONSE DEFINITIONS
Details of the JSON fields returned by the COMPLETED status response.
ai_regimeThe detected market state. Values: NORMAL, BULL, BEAR, CRASH. Use this to filter trades (e.g., avoid longs if CRASH).
ai_directionThe projected trend direction for the forecast horizon. Values: NEUTRAL, BULL, BEAR.
ai_confidenceProbability score (0.0 to 1.0) indicating the model's certainty based on current volatility.
predicted_closeThe forecasted closing price for the target date.
task_idUnique identifier used to track the asynchronous prediction job.