# Quantum Portfolio Product API Guide

## Integration Modes

- **Production mode (recommended):** send `returns` + `covariance` directly.
- **Research/demo mode:** send `tickers` + dates (uses yfinance fallback).

Set `REQUIRE_MATRIX_INPUT=true` in production to disable yfinance path.

## Core Endpoints

- `POST /api/portfolio/optimize`
- `POST /api/portfolio/optimize/batch`
- `POST /api/portfolio/backtest`
- `POST /api/portfolio/efficient-frontier`

## Async Jobs

- Submit optimization: `POST /api/jobs/optimize`
- Submit backtest: `POST /api/jobs/backtest`
- Poll status: `GET /api/jobs/{job_id}`

Each async submit endpoint accepts:

```json
{
  "payload": { "...": "endpoint payload" },
  "webhook_url": "https://your-system/callback"
}
```

## Authentication

Use `X-API-Key` header.

- Static mode: `API_KEY=<secret>`
- Multi-tenant mode: store hashed keys in `api_keys` table in `data/api.sqlite3`.

Admin key management endpoints:
- `POST /api/admin/api-keys` with `X-Admin-Key` header (`ADMIN_API_KEY` env var)
- `GET /api/admin/api-keys` with `X-Admin-Key` header

## SDK

Use `quantum_portfolio_sdk.QuantumPortfolioClient`:

```python
from quantum_portfolio_sdk import QuantumPortfolioClient

client = QuantumPortfolioClient("http://localhost:5000", api_key="...")
res = client.optimize({...})
```

See `examples/sdk/basic_client_example.py`.