Vantyx Trade API: AI Stock Research & Congressional Data

Auto-Trade Health Check

Returns the health status of the auto-trading scheduler, including system status, job counts, last run times, and failure tracking.

Parameters

Response Schema

{
  "system_status": "ok",  // "ok" | "degraded" | "error"
  "scheduler_status": "running",  // "running" | "stopped"
  "job_counts": {
    "total_jobs": 10,  // Total number of scheduled jobs
    "running_jobs": 0,  // Number of jobs currently running
    "completed_jobs": 8,  // Number of jobs completed in the last run
    "failed_jobs": 0  // Number of jobs failed in the last run
  },
  "last_run_times": {
    "last_successful_run": "2026-04-11T06:30:00Z",  // ISO 8601 timestamp
    "last_failed_run": null,  // ISO 8601 timestamp or null
    "last_run_duration_ms": 1250  // Duration in milliseconds
  },
  "failure_tracking": {
    "total_failures": 0,  // Total number of failures across all runs
    "consecutive_failures": 0,  // Number of consecutive failures
    "last_failure_time": null,  // ISO 8601 timestamp or null
    "last_failure_message": null  // Error message or null
  },
  "health_checks": {
    "database": "ok",  // "ok" | "degraded" | "error"
    "api_connection": "ok",  // "ok" | "degraded" | "error"
    "scheduler_service": "ok"  // "ok" | "degraded" | "error"
  }
}

Example Request

GET /auto-trade-healthz HTTP/1.1
Host: localhost:9101
Accept: application/json

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "system_status": "ok",
  "scheduler_status": "running",
  "job_counts": {
    "total_jobs": 10,
    "running_jobs": 0,
    "completed_jobs": 8,
    "failed_jobs": 0
  },
  "last_run_times": {
    "last_successful_run": "2026-04-11T06:30:00Z",
    "last_failed_run": null,
    "last_run_duration_ms": 1250
  },
  "failure_tracking": {
    "total_failures": 0,
    "consecutive_failures": 0,
    "last_failure_time": null,
    "last_failure_message": null
  },
  "health_checks": {
    "database": "ok",
    "api_connection": "ok",
    "scheduler_service": "ok"
  }
}

Error Responses

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "system_status": "error",
  "scheduler_status": "stopped",
  "job_counts": {
    "total_jobs": 10,
    "running_jobs": 0,
    "completed_jobs": 8,
    "failed_jobs": 2
  },
  "last_run_times": {
    "last_successful_run": "2026-04-11T06:28:00Z",
    "last_failed_run": "2026-04-11T06:29:00Z",
    "last_run_duration_ms": 1500
  },
  "failure_tracking": {
    "total_failures": 5,
    "consecutive_failures": 2,
    "last_failure_time": "2026-04-11T06:29:00Z",
    "last_failure_message": "Database connection timeout"
  },
  "health_checks": {
    "database": "error",
    "api_connection": "degraded",
    "scheduler_service": "error"
  }
}

Auto-Trade Readiness Check

Checks if the auto-trading system is ready to execute trades. Returns a readiness status with detailed information about the system's components.

Parameters

Response Schema

{
  "ready": true,  // Boolean indicating if the system is ready
  "ready_status": "ready",  // "ready" | "not_ready" | "degraded"
  "reasons": {
    "database": "ok",  // "ok" | "degraded" | "error"
    "api_connection": "ok",  // "ok" | "degraded" | "error"
    "scheduler_service": "ok",  // "ok" | "degraded" | "error"
    "portfolio_config": "ok",  // "ok" | "degraded" | "error"
    "api_credentials": "ok"  // "ok" | "degraded" | "error"
  },
  "details": {
    "database": {
      "status": "ok",
      "message": "Database connection established"
    },
    "api_connection": {
      "status": "ok",
      "message": "API connection established"
    },
    "scheduler_service": {
      "status": "ok",
      "message": "Scheduler service is running"
    },
    "portfolio_config": {
      "status": "ok",
      "message": "Portfolio configuration is valid"
    },
    "api_credentials": {
      "status": "ok",
      "message": "API credentials are valid"
    }
  },
  "last_check_time": "2026-04-11T06:30:00Z",  // ISO 8601 timestamp
  "next_check_time": "2026-04-11T06:31:00Z"  // ISO 8601 timestamp
}

Example Request

GET /auto-trade-readyz HTTP/1.1
Host: localhost:9101
Accept: application/json

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ready": true,
  "ready_status": "ready",
  "reasons": {
    "database": "ok",
    "api_connection": "ok",
    "scheduler_service": "ok",
    "portfolio_config": "ok",
    "api_credentials": "ok"
  },
  "details": {
    "database": {
      "status": "ok",
      "message": "Database connection established"
    },
    "api_connection": {
      "status": "ok",
      "message": "API connection established"
    },
    "scheduler_service": {
      "status": "ok",
      "message": "Scheduler service is running"
    },
    "portfolio_config": {
      "status": "ok",
      "message": "Portfolio configuration is valid"
    },
    "api_credentials": {
      "status": "ok",
      "message": "API credentials are valid"
    }
  },
  "last_check_time": "2026-04-11T06:30:00Z",
  "next_check_time": "2026-04-11T06:31:00Z"
}

Error Responses

HTTP/1.1 503 Service Unavailable
Content-Type: application/json

{
  "ready": false,
  "ready_status": "not_ready",
  "reasons": {
    "database": "error",
    "api_connection": "degraded",
    "scheduler_service": "error",
    "portfolio_config": "ok",
    "api_credentials": "ok"
  },
  "details": {
    "database": {
      "status": "error",
      "message": "Database connection failed"
    },
    "api_connection": {
      "status": "degraded",
      "message": "API connection is unstable"
    },
    "scheduler_service": {
      "status": "error",
      "message": "Scheduler service is not responding"
    },
    "portfolio_config": {
      "status": "ok",
      "message": "Portfolio configuration is valid"
    },
    "api_credentials": {
      "status": "ok",
      "message": "API credentials are valid"
    }
  },
  "last_check_time": "2026-04-11T06:30:00Z",
  "next_check_time": "2026-04-11T06:31:00Z"
}

Portfolio Health Dashboard

Returns comprehensive portfolio health metrics including performance, risk, diversification, and recent trades.

Parameters

Response Schema

{
  "portfolio_id": 123,  // Integer portfolio ID
  "portfolio_name": "My Portfolio",
  "user_id": 1,
  "environment": "dev",  // "dev" | "prod"
  "source": "alpaca",  // Source of portfolio data
  "broker": "alpaca",
  "broker_mode": "live",  // "live" | "paper"
  "is_active": true,
  "/api/portfolio-health-dashboard" endpoint added on: {date}  // ISO 8601 timestamp
}

Performance Metrics: returns, volatility, max_drawdown, sharpe_ratio, sortino_ratio.

Risk Metrics: beta, alpha, information_ratio, calmar_ratio.

Diversification Scores: concentration_risk, diversification_score, top_holdings_concentration.

Portfolio ROI / Win-Rate / Profitability

Computes total return vs baseline_capital, realized P&L + win rate via FIFO match of Transaction rows (works for both Alpaca-reconciled and manual fills), unrealized P&L from open Holding rows, and 7d/30d returns vs SPY from PerformanceHistory. Endpoint path retains paper-performance for backward compatibility.

Parameters

Authentication

This endpoint requires authentication. The user must be authorized to access the specified portfolio.

Response Schema

{
  "portfolio_id": 123,  // Integer portfolio ID
  "broker_mode": "paper",  // "paper" | "live"
  
  "trades": {
    "closed": 5,  // Number of closed (round-trip) trades
    "open_positions": 3,  // Number of open positions
    "wins": 4,  // Number of winning trades
    "losses": 1,  // Number of losing trades
    "win_rate_pct": 80.0  // Win rate as percentage
  },
  
  "pnl": {
    "realized": 500.00,  // Realized P&L in USD
    "unrealized": 150.00,  // Unrealized P&L in USD
    "total": 650.00  // Total P&L in USD
  },
  
  "capital": {
    "holdings_value": 25000.00,  // Current value of holdings
    "cash": 500.00,  // Available cash
    "current_value": 25500.00,  // Total current portfolio value
    "baseline_capital": 10000.00,  // Baseline capital for return calculation
    "total_return_pct": 155.0  // ((current_value - baseline_capital) / baseline_capital * 100)
  },
  
  "holdings": [
    {
      "symbol": "AAPL",
      "shares": 100,
      "current_price": 180.50,
      "purchase_price": 160.00,
      "cost_basis": 16000.00,
      "market_value": 18050.00,
      "unrealized_pnl": 2050.00,
      "unrealized_pnl_pct": 12.81
    }
  ],
  
  "performance_history": {
    "7d_return_pct": 2.5,  // 7-day return vs SPY
    "30d_return_pct": 5.8,  // 30-day return vs SPY
    "spy_7d_return_pct": 1.8,
    "spy_30d_return_pct": 4.2
  },
  
  "closed_trades": [
    {
      "id": 1,
      "symbol": "AAPL",
      "cost_basis": 1000.00,
      "proceeds": 1200.00,
      "realized": 200.00,
      "return_pct": 20.0,
      "transaction_date": "2026-01-15T00:00:00Z"
    }
  ],
  
  "open_positions": [
    {
      "id": 1,
      "symbol": "MSFT",
      "shares": 5,
      "purchase_price": 200.00,
      "current_price": 210.00,
      "cost_basis": 1000.00,
      "market_value": 1050.00,
      "unrealized_pnl": 50.00
    }
  ]
}

Error Responses

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "Forbidden",
  "message": "Access denied to portfolio with ID {id}"
}

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "Not Found",
  "message": "Portfolio with ID {id} not found"
}

Portfolio Performance Summary (Rollup)

Returns a rollup summary of all portfolios for the authenticated user or admin. Useful for operators who want top-line performance metrics across their environment.

Parameters

Authentication

This endpoint requires authentication. Admin users can see all portfolios; regular users see only their own.

Response Schema

{
  "rollup": {
    "n_portfolios": 5,  // Number of portfolios in rollup
    "closed_trades": 120,  // Total closed trades across all portfolios
    "open_positions": 23,  // Total open positions
    "wins": 85,  // Total winning trades
    "losses": 35,  // Total losing trades
    "win_rate_pct": 70.83,  // Overall win rate
    "total_realized": 12500.00,  // Total realized P&L in USD
    "total_unrealized": 4200.00,  // Total unrealized P&L in USD
    "best_trade_pct": 45.5,  // Best single trade return percentage
    "worst_trade_pct": -18.2  // Worst single trade loss percentage
  },
  
  "portfolios": [
    {
      "portfolio_id": 1,
      "portfolio_name": "Practice Environment",
      "closed_trades": 25,
      "open_positions": 4,
      "wins": 18,
      "losses": 7,
      "win_rate_pct": 72.0,
      "total_realized": 3500.00,
      "total_unrealized": 1200.00
    },
    {
      "portfolio_id": 2,
      "portfolio_name": "Strategies Lab",
      "closed_trades": 95,
      "open_positions": 19,
      "wins": 67,
      "losses": 28,
      "win_rate_pct": 70.53,
      "total_realized": 9000.00,
      "total_unrealized": 3000.00
    }
  ]
}

Example Request

GET /api/paper-performance-summary HTTP/1.1
Host: localhost:9101
Authorization: Bearer {admin_token}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "rollup": {
    "n_portfolios": 5,
    "closed_trades": 120,
    "open_positions": 23,
    "wins": 85,
    "losses": 35,
    "win_rate_pct": 70.83,
    "total_realized": 12500.00,
    "total_unrealized": 4200.00,
    "best_trade_pct": 45.5,
    "worst_trade_pct": -18.2
  },
  "portfolios": [
    {
      "portfolio_id": 1,
      "portfolio_name": "Practice Environment",
      "closed_trades": 25,
      "open_positions": 4,
      "wins": 18,
      "losses": 7,
      "win_rate_pct": 72.0,
      "total_realized": 3500.00,
      "total_unrealized": 1200.00
    },
    {
      "portfolio_id": 2,
      "portfolio_name": "Strategies Lab",
      "closed_trades": 95,
      "open_positions": 19,
      "wins": 67,
      "losses": 28,
      "win_rate_pct": 70.53,
      "total_realized": 9000.00,
      "total_unrealized": 3000.00
    }
  ]
}

Error Responses

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "Forbidden",
  "message": "Access denied to this portfolio"
}

Metrics Health Check

Health check for the metrics monitoring subsystem.

Parameters

Response Schema

{
  "status": "ok",
  "metrics_enabled": true,
  "tracked_endpoints": 12
}

Metrics Readiness Check

Readiness check for the metrics monitoring subsystem. Returns detailed status of the metrics infrastructure.

Parameters

Response Schema

{
  "status": "ok",
  "metrics_enabled": true,
  "database_connected": true,
  "request_duration_cache_hits": 15234,
  "request_duration_cache_misses": 89,
  "cache_hit_rate_pct": 99.4
}

Latency Statistics (All Endpoints)

Returns latency percentiles for all tracked API endpoints. Useful for identifying performance bottlenecks and comparing endpoint performance.

Parameters

Response Schema

{
  "endpoints": {
    "/api/portfolios": {"p50": 45.2, "p95": 120.5, "p99": 340.8, "total_requests": 1500},
    "/api/portfolio-health-dashboard": {"p50": 78.5, "p95": 195.2, "p99": 450.1, "total_requests": 320},
    "/auto-trade-healthz": {"p50": 8.1, "p95": 22.3, "p99": 55.6, "total_requests": 892}
  },
  "total_endpoints_tracked": 12,
  "last_updated": "2026-05-30T15:00:00Z"
}

Endpoint-Specific Latency Statistics

Returns latency statistics for a specific endpoint.

Parameters:

• <endpoint_path>: The endpoint path (e.g., /api/portfolios)

Response Schema

{
  "path": "/api/portfolios",
  "p50": 45.2,
  "p95": 120.5,
  "p99": 340.8,
  "total_requests": 1500,
  "min_latency_ms": 12.3,
  "max_latency_ms": 567.8
}

Global Percentile Analysis

Returns global percentile analysis across all tracked endpoints. Useful for system-wide performance monitoring.

Parameters:

• <p_value>: Percentile value (e.g., 50, 95, 99). Can be a number or percentage string like "95".

Response Schema

{
  "percentile": 95,
  "overall_p95_latency_ms": 245.8,
  "slowest_endpoint": "/api/portfolio-health-dashboard",
  "endpoint_breakdown": {
    "/api/portfolios": {"p95": 120.5, "total_requests": 1500},
    "/api/metrics/latency-stats": {"p95": 15.2, "total_requests": 234}
  },
  "timestamp": "2026-05-30T15:00:00Z"
}

Trade Executions Dashboard

Admin dashboard endpoint for trade execution analytics and monitoring. Returns aggregated statistics, status breakdowns, error aggregations, date range information, and detailed execution records with payload parsing.

Parameters

Authentication

This endpoint requires authentication. Only users with ADMIN role can access this endpoint.

Response Schema

{
  "stats": {
    "total_executions": 125  // Total number of executions in the date range (last 30 days by default)
  },
  "portfolio_counts": {  // Executions grouped by portfolio_id
    "1": 45,
    "2": 30,
    "3": 50
  },
  "status_counts": {
    "completed": 95,
    "failed": 20,
    "in_progress": 10  // Status breakdown
  },
  "error_code_counts": {
    "TIMEOUT_ERROR": 15,  // Categorized error types from error messages
    "API_ERROR": 8,
    "OTHER_ERROR": 3
  },
  "date_ranges": {
    "earliest": "2026-04-29T06:30:00Z",
    "latest": "2026-05-29T10:15:00Z"
  },
  "executions": [
    {
      "id": 1,
      "portfolio_id": 1,
      "broker_mode": "paper",
      "status": "completed",
      "error_message": null,
      "created_at": "2026-05-29T10:15:00Z",
      "run_label": "dev-auto-trade",  // From payload.run_label
      "cash_source": "recurring",  // From payload.cash_source
      "orders": [
        {
          "id": 1,
          "status": "completed",
          "symbol": "AAPL",
          "side": "buy",
          "quantity": 10,
          "filled_qty": 10,
          "avg_fill_price": 180.50,
          "client_order_id": "oc-abc123"
        }
      ],
      "failed": [],
      "skipped": [],
      "skip_counts": {},
      "warnings": []
    }
  ],
  "sample_executions": [
    {
      "id": 1,
      "portfolio_id": 1,
      "broker_mode": "paper",
      "status": "completed",
      "error_message": null,
      "created_at": "2026-05-29T10:15:00Z"
    }
  ],
  "total_executions": 125
}

Example Request

GET /api/trade-executions-dashboard HTTP/1.1
Host: localhost:9101
Authorization: Bearer {admin_token}
Accept: application/json

GET /api/trade-executions-dashboard?status=failed&portfolio_id=1&limit=100 HTTP/1.1
Host: localhost:9101
Authorization: Bearer {admin_token}
Accept: application/json

Example Request CSV Format

GET /api/metrics/healthz

Health check for metrics subsystem.

{
  "status": "ok",
  "metrics_enabled": true,
  "tracked_endpoints": 42
}

GET /api/metrics/readyz

Readiness check for metrics subsystem.

{
  "status": "ok",
  "metrics_enabled": true,
  "database_connected": true
}

GET /api/metrics/latency-stats

Returns latency percentiles for all tracked API endpoints.

{
  "endpoints": {
    "/api/portfolios": {"p50": 45.2, "p95": 120.5, "p99": 340.8, "total_requests": 1500},
    "/auto-trade-healthz": {"p50": 8.1, "p95": 22.3, "p99": 55.6, "total_requests": 892}
  },
  "total_endpoints_tracked": 12
}

GET /api/metrics/

Returns latency statistics for a specific endpoint.

Parameters:

• <endpoint_path>: The endpoint path (e.g., /api/portfolios)

{
  "path": "/api/portfolios",
  "p50": 45.2,
  "p95": 120.5,
  "p99": 340.8,
  "total_requests": 1500
}