Enterprise API v2.0 • RESTful • JSON

Developer API

Professional-grade REST API for institutional financial analysis. Built for scale, security, and performance with sub-50ms response times.

99.9%
Uptime SLA
< 50ms
Response Time
12+
Algorithms
24/7
Support
Get Started Authentication Get API Key →

Overview

The NGX Baskets API provides institutional-grade access to advanced financial algorithms, portfolio construction tools, and real-time analytics. Built for enterprise security and scalability.

Base URL:

https://ngxbaskets.com/api

Authentication:

Bearer Token (Sanctum)

Authentication

All API requests require authentication using a Bearer token:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     https://ngxbaskets.com/api/me

Security Note: API tokens provide full access to your account. Keep them secure and rotate regularly.

User Information

GET /api/me

Get current user information and subscription details.

curl -H "Authorization: Bearer YOUR_TOKEN" https://ngxbaskets.com/api/me

Response Example:

{
  "id": 1,
  "name": "John Doe",
  "email": "[email protected]",
  "subscription_tier": "enterprise",
  "algorithm_runs_remaining": 950,
  "limits": {
    "baskets": "unlimited",
    "stocks_per_basket": 100,
    "algorithm_runs_per_month": 1000
  }
}

Baskets

GET /api/baskets

Retrieve all baskets for the authenticated user.

curl -H "Authorization: Bearer YOUR_TOKEN" https://ngxbaskets.com/api/baskets

POST /api/baskets

Create a new basket with specified parameters.

curl -X POST https://ngxbaskets.com/api/baskets \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tech Growth Portfolio",
    "start_date": "2024-01-01",
    "end_date": "2024-12-31"
  }'

Stocks

POST /api/baskets/{basket}/stocks

Add a stock to an existing basket.

curl -X POST https://ngxbaskets.com/api/baskets/1/stocks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ticker": "AAPL",
    "exchange": "NASDAQ",
    "weight": 0.25
  }'

Jobs

GET /api/jobs

List all algorithm jobs with their status and results.

curl -H "Authorization: Bearer YOUR_TOKEN" https://ngxbaskets.com/api/jobs

Portfolio Metrics

Advanced portfolio metrics including CAPM analysis, risk measures, and performance ratios.

POST /api/metrics/capm

Calculate Capital Asset Pricing Model (CAPM) metrics including alpha, beta, and risk-adjusted returns.

curl -X POST https://ngxbaskets.com/api/metrics/capm \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "basket_id": 1,
    "benchmark_ticker": "SPY",
    "benchmark_exchange": "NASDAQ",
    "period": "1y",
    "rolling_window": 252
  }'

Response Example:

{
  "alpha": 0.0523,
  "beta": 1.2134,
  "r_squared": 0.8756,
  "portfolio_return": 0.1234,
  "benchmark_return": 0.0987,
  "excess_return": 0.0247,
  "rolling_metrics": {
    "rolling_alpha": [0.051, 0.053, 0.049],
    "rolling_beta": [1.210, 1.215, 1.211]
  }
}

POST /api/metrics/comprehensive

Calculate comprehensive portfolio metrics including Sharpe, Sortino, Calmar ratios, VaR, and CVaR.

curl -X POST https://ngxbaskets.com/api/metrics/comprehensive \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "basket_id": 1,
    "period": "1y",
    "confidence_level": 0.95,
    "risk_free_rate": 0.02
  }'

Response Example:

{
  "return_volatility": {
    "annual_return": 0.1234,
    "annual_volatility": 0.1876,
    "downside_volatility": 0.1234
  },
  "risk_adjusted_ratios": {
    "sharpe_ratio": 0.5521,
    "sortino_ratio": 0.8342,
    "calmar_ratio": 0.4123,
    "information_ratio": 0.3456
  },
  "risk_measures": {
    "max_drawdown": 0.1245,
    "var_95": 0.0234,
    "cvar_95": 0.0345,
    "beta": 1.2134
  }
}

Portfolio Optimization

Advanced portfolio optimization algorithms including Mean-Variance, Hierarchical Risk Parity, and Equal Risk Contribution.

POST /api/optimize/efficient-frontier

Calculate efficient frontier with optimal portfolio weights for different risk levels.

curl -X POST https://ngxbaskets.com/api/optimize/efficient-frontier \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "basket_id": 1,
    "lookback_period": "2y",
    "num_portfolios": 100,
    "risk_free_rate": 0.02
  }'

Response Example:

{
  "optimal_portfolios": {
    "min_variance": {
      "weights": {"AAPL": 0.25, "MSFT": 0.35, "GOOGL": 0.40},
      "expected_return": 0.0987,
      "volatility": 0.1234,
      "sharpe_ratio": 0.5521
    },
    "max_sharpe": {
      "weights": {"AAPL": 0.40, "MSFT": 0.30, "GOOGL": 0.30},
      "expected_return": 0.1234,
      "volatility": 0.1567,
      "sharpe_ratio": 0.6789
    }
  },
  "efficient_frontier": [
    {"return": 0.08, "volatility": 0.12, "sharpe": 0.50},
    {"return": 0.10, "volatility": 0.14, "sharpe": 0.57}
  ]
}

POST /api/optimize/hrp

Hierarchical Risk Parity optimization for robust portfolio construction.

curl -X POST https://ngxbaskets.com/api/optimize/hrp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "basket_id": 1,
    "lookback_period": "2y"
  }'

Response Example:

{
  "hrp_weights": {
    "AAPL": 0.2834,
    "MSFT": 0.3456,
    "GOOGL": 0.3710
  },
  "expected_return": 0.1123,
  "expected_volatility": 0.1456,
  "diversification_ratio": 1.789,
  "cluster_structure": {
    "tech_cluster": ["AAPL", "MSFT", "GOOGL"],
    "weights_by_cluster": {"tech_cluster": 1.0}
  }
}

POST /api/optimize/erc

Equal Risk Contribution optimization for balanced risk allocation.

curl -X POST https://ngxbaskets.com/api/optimize/erc \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "basket_id": 1,
    "lookback_period": "2y",
    "target_volatility": 0.12
  }'

Response Example:

{
  "erc_weights": {
    "AAPL": 0.3333,
    "MSFT": 0.3334,
    "GOOGL": 0.3333
  },
  "risk_contributions": {
    "AAPL": 0.3333,
    "MSFT": 0.3334,
    "GOOGL": 0.3333
  },
  "portfolio_volatility": 0.1200,
  "diversification_ratio": 1.456
}

Backtesting

Advanced backtesting framework with walk-forward analysis, transaction costs, and strategy comparison.

POST /api/backtest/walk-forward

Walk-forward backtesting with out-of-sample validation and realistic transaction costs.

curl -X POST https://ngxbaskets.com/api/backtest/walk-forward \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "basket_id": 1,
    "strategy": "mean_reversion",
    "start_date": "2020-01-01",
    "end_date": "2024-01-01",
    "training_window": 252,
    "rebalance_frequency": 21,
    "transaction_cost_bps": 10,
    "slippage_bps": 5,
    "initial_capital": 100000
  }'

Response Example:

{
  "performance_metrics": {
    "total_return": 0.2345,
    "annual_return": 0.0567,
    "annual_volatility": 0.1234,
    "sharpe_ratio": 0.4567,
    "max_drawdown": 0.0876,
    "calmar_ratio": 0.6483
  },
  "transaction_analysis": {
    "total_transaction_costs": 2345.67,
    "num_rebalances": 48,
    "turnover_rate": 0.23
  },
  "walk_forward_results": [
    {
      "period": "2020-Q1",
      "return": 0.0234,
      "volatility": 0.1123,
      "sharpe": 0.2084
    }
  ]
}

POST /api/backtest/compare-strategies

Compare multiple strategies with comprehensive performance analysis.

curl -X POST https://ngxbaskets.com/api/backtest/compare-strategies \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "basket_id": 1,
    "strategies": ["buy_and_hold", "mean_reversion", "momentum"],
    "start_date": "2020-01-01",
    "end_date": "2024-01-01",
    "initial_capital": 100000
  }'

Response Example:

{
  "strategy_comparison": {
    "buy_and_hold": {
      "total_return": 0.1876,
      "annual_return": 0.0434,
      "sharpe_ratio": 0.3567,
      "max_drawdown": 0.1234
    },
    "mean_reversion": {
      "total_return": 0.2345,
      "annual_return": 0.0567,
      "sharpe_ratio": 0.4567,
      "max_drawdown": 0.0876
    },
    "momentum": {
      "total_return": 0.2098,
      "annual_return": 0.0498,
      "sharpe_ratio": 0.4123,
      "max_drawdown": 0.0987
    }
  },
  "best_strategy": "mean_reversion",
  "performance_ranking": [
    "mean_reversion",
    "momentum",
    "buy_and_hold"
  ]
}

Algorithm Execution

Execute advanced financial algorithms on your basket data. Each algorithm provides different insights into portfolio behavior and risk.

POST /api/algorithms/run

Execute an algorithm on your basket data with custom parameters.

Chebyshev

Statistical bounds

Price Bands

Monte Carlo

Risk simulation

Probabilistic

K-means

Volatility clustering

Pattern Recognition

Sharpe/Sortino

Risk-adjusted returns

Performance

Max Drawdown

Worst-case analysis

Risk Assessment
curl -X POST https://ngxbaskets.com/api/algorithms/run \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "basket_id": 1,
    "algorithm": "chebyshev",
    "parameters": {
      "confidence_level": 0.95,
      "days_back": 252
    }
  }'

Chebyshev Algorithm

Uses Chebyshev's inequality to calculate statistical bounds and confidence intervals for portfolio price bands.

Parameters

confidence_level - Confidence level (0.5-0.99, default: 0.95)
days_back - Historical data period (30-1000 days, default: 252)

Example Response

{
  "job_id": 123,
  "algorithm": "chebyshev",
  "confidence_level": "95%",
  "lower_band": 185.50,
  "upper_band": 234.80,
  "days_in_band_percentage": 78.5,
  "guaranteed_minimum_percentage": 95.0,
  "analysis_summary": "Your portfolio stayed within the calculated 95% confidence bands on 78.5% of trading days."
}

Monte Carlo Algorithm

Runs thousands of simulations to model potential portfolio outcomes and assess risk under various market scenarios.

Parameters

num_simulations - Number of simulations (100-100,000, tier-dependent)
time_horizon_days - Simulation period (30-1000 days, default: 252)
confidence_levels - Confidence intervals to calculate (default: [0.90, 0.95, 0.99])

Example Response

{
  "job_id": 124,
  "algorithm": "monte_carlo",
  "simulations_run": 10000,
  "expected_return_percentage": 12.5,
  "positive_scenarios_percentage": 70.0,
  "confidence_intervals": {
    "95%": {"lower": 8500.00, "upper": 15200.00}
  },
  "risk_level": "Medium",
  "analysis_summary": "Monte Carlo simulation shows an expected return of 12.5% with 70% of scenarios being profitable."
}

K-means Algorithm

Applies machine learning clustering to identify distinct volatility regimes and market conditions in your portfolio's historical performance.

Parameters

num_clusters - Number of volatility clusters (2-10, default: 3)
window_size - Rolling window size (5-60 days, default: 20)
max_iterations - Clustering iterations (10-500, default: 100)

Example Response

{
  "job_id": 125,
  "algorithm": "kmeans",
  "num_clusters": 3,
  "volatility_periods": {
    "Low Volatility": {"percentage": 65.0},
    "Medium Volatility": {"percentage": 25.0},
    "High Volatility": {"percentage": 10.0}
  },
  "dominant_cluster": {"label": "Low Volatility", "percentage": 65.0},
  "analysis_summary": "Portfolio volatility clustering identified low volatility as the dominant regime (65% of periods)."
}

Sharpe/Sortino Ratios

Calculates risk-adjusted return metrics to evaluate portfolio performance relative to volatility and downside risk.

Parameters

risk_free_rate - Annual risk-free rate (0-20%, default: 2%)
days_back - Historical data period (30-1000 days, default: 252)
benchmark_return - Annual benchmark return (-50% to 50%, default: 8%)

Example Response

{
  "job_id": 126,
  "algorithm": "sharpe_sortino",
  "sharpe_ratio": 1.25,
  "sortino_ratio": 1.68,
  "annual_return": 12.5,
  "annual_volatility": 18.2,
  "downside_volatility": 12.8,
  "performance_grade": "Good",
  "information_ratio": 0.85,
  "analysis_summary": "Portfolio achieved 12.5% annual return with 18.2% volatility. Sharpe ratio of 1.25 and Sortino ratio of 1.68 indicate good risk-adjusted performance."
}

Max Drawdown Analysis

Analyzes the maximum peak-to-trough decline and recovery patterns to assess portfolio worst-case scenarios and risk tolerance.

Parameters

days_back - Historical analysis period (30-2000 days, default: 252)
initial_investment - Starting portfolio value ($1K-$10M, default: $10,000)
drawdown_threshold - Alert threshold (1-50%, default: 10%)

Example Response

{
  "job_id": 127,
  "algorithm": "max_drawdown",
  "max_drawdown_percentage": 18.5,
  "max_drawdown_amount": 1850.00,
  "max_drawdown_duration_days": 45,
  "current_drawdown_percentage": 2.1,
  "recovery_time_days": 38,
  "is_recovered": true,
  "risk_level": "Moderate",
  "time_underwater_percentage": 28.5,
  "calmar_ratio": 0.68,
  "analysis_summary": "Portfolio experienced a maximum drawdown of 18.5% ($1,850) lasting 45 days. Recovery took 38 days. Risk level is classified as moderate."
}

Rate Limits

API rate limits are based on your subscription tier:

Free Tier

  • • 10 algorithm runs/month
  • • 100 API requests/hour
  • • Basic algorithms only

Pro Tier

  • • 100 algorithm runs/month
  • • 1,000 API requests/hour
  • • All algorithms + advanced features

Enterprise Tier

  • • Unlimited algorithm runs
  • • 10,000 API requests/hour
  • • Priority support + custom features

Error Handling

The API uses conventional HTTP response codes to indicate success or failure:

Success Codes

  • 200 - Request successful
  • 201 - Resource created
  • 204 - No content returned

Error Codes

  • 400 - Bad request
  • 401 - Unauthorized
  • 422 - Validation error
  • 429 - Rate limit exceeded
  • 500 - Server error

Error Response Format

{
  "error": "Validation failed",
  "errors": {
    "algorithm": ["The selected algorithm is invalid."],
    "parameters.confidence_level": ["The confidence level must be between 0.5 and 0.99."]
  }
}

Enterprise Support

Need assistance with integration? Our enterprise support team is available 24/7 for API questions and technical guidance.

Contact API Support View SDKs