# Simetrix Integration Guides (Condensed)

## Guide 1: First simulation (HTTP)

```bash
# 1) Set the base URL and token
API_BASE="https://api.simetrix.io"
SIMETRIX_API_TOKEN="sk_live_xxx"

# 2) Launch a quick simulation
curl -X POST "$API_BASE/simulate" \
  -H "Authorization: Bearer $SIMETRIX_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "X:NVDA",
    "horizon_days": 45,
    "n_paths": 2000,
    "profile": "quick",
    "timespan": "day",
    "include_news": true,
    "engine": "hybrid"
  }'

# 3) Poll status (replace RUN_ID)
RUN_ID="run_abc123"
curl -H "Authorization: Bearer $SIMETRIX_API_TOKEN" \
  "$API_BASE/simulate/$RUN_ID"

# 4) Fetch the artifact
curl -H "Authorization: Bearer $SIMETRIX_API_TOKEN" \
  "$API_BASE/simulate/$RUN_ID/artifact"
```

## Guide 2: Forecast a symbol (SDK)

```python
# pip install simetrix-sdk
from simetrix_sdk import SimetrixClient

# Create an authenticated client
client = SimetrixClient(token="YOUR_API_TOKEN")

# Request a symbol forecast
forecast = client.forecast_symbol("X:NVDA", horizon_days=45)
print(forecast.get("prob_up"))
```

## Guide 3: Scenario conditioning + targets ladder (SDK)

```python
# Create the client
from simetrix_sdk import SimetrixClient
client = SimetrixClient(token="YOUR_API_TOKEN")

# Apply a scenario hash to a forecast
conditioned = client.condition_scenario(
    symbol="X:NVDA",
    horizon_days=60,
    scenario_hash="scn_abcd1234",
    scenario_summary={"title": "CPI surprise"},
)

# Fetch a targets ladder for the same scenario
ladder = client.targets("X:NVDA", scenario_hash="scn_abcd1234")
```

## Guide 4: Portfolio forecast (SDK)

```python
from simetrix_sdk import SimetrixClient
client = SimetrixClient(token="YOUR_API_TOKEN")

# Build a portfolio as weights
portfolio = [
    {"symbol": "X:AAPL", "weight": 0.6},
    ("X:NVDA", 0.4),
]

# Request a portfolio forecast
forecast = client.forecast_portfolio(portfolio, horizon_days=45)
```

## Troubleshooting
- 401 or 403: verify token and scopes.
- 429: retry with lower n_paths or slower cadence.
- Missing data: portfolio forecasts can fall back to synthetic blends if the feature store is unseeded.

## Reference
- OpenAPI: https://api.simetrix.io/api-docs
- API ref: https://simetrix.io/docs/contexts/api-ref.md