NeuFin API documentation

1) Authentication

Base URL: https://neufin101-production.up.railway.app

Auth: Bearer token in Authorization header.

Getting started: create account → Developer → copy API key.

Authorization: Bearer nf_live_sk_xxxxxxxxxxxx

2) POST /api/swarm/analyze

Submit a portfolio for 7-agent IC analysis. Returns immediately with job_id. Poll /status/{job_id} for progress.

{
  "positions": [
    {"symbol": "AAPL", "shares": 100, "cost_basis": 150.00},
    {"symbol": "NVDA", "shares": 50, "cost_basis": 400.00}
  ],
  "total_value": 35000
}

{
  "job_id": "8f2a4b1c-...",
  "status": "queued",
  "poll_url": "/api/swarm/status/8f2a4b1c-...",
  "estimated_seconds": 75
}

3) GET /api/swarm/status/{job_id}

Poll every 3s to track agent progress and get results.

{
  "job_id": "8f2a4b1c-...",
  "status": "running",
  "progress_pct": 57,
  "agent_trace": [
    {"agent": "risk_agent", "status": "complete", "summary": "..."},
    {"agent": "sector_agent", "status": "running", "summary": "..."}
  ]
}

4) GET /api/swarm/result/{job_id}

Fetch full IC briefing when status == complete.

{
  "ic_briefing": {
    "portfolio_analyst": {...},
    "macro_strategist": {...},
    "risk_manager": {...},
    "sector_specialist": {...},
    "factor_quant": {...},
    "behavioral_agent": {...},
    "synthesis_agent": {...}
  }
}

5) GET /api/research/regime

Get current macro regime classification.

{
  "regime": "risk_off",
  "confidence": 0.82,
  "signals": ["vix_elevated", "yield_curve_inverted"],
  "narrative": "...",
  "updated_at": "2026-04-10T08:00:00Z"
}

6) GET /api/portfolio/chart/{ticker}

OHLCV chart data for candlestick rendering.

Params: period = 1mo | 3mo | 6mo | 1y | 3y

[{"date":"2026-04-01","open":181.2,"high":184.3,"low":179.5,"close":183.7,"volume":61439200}]

Sandbox

{
  "message": "Send a request to start."
}