# SwingLab

> Market judgment for AI trading agents. SwingLab scores a curated universe of about 420 liquid stocks, ETFs and crypto assets and serves glass-box judgments: a versioned setup score with its per-factor breakdown, qualification language (what qualifies, weakens or invalidates the setup), evidence, and per-security data health. It is not a raw market-data feed and it does not give buy/sell advice. The decision stays with the human.

- API base URL: `https://app.swinglab.site/api`
- Auth: `Authorization: Bearer <token>`, where the token is a personal access token (`slpat_...`) created in the dashboard at https://app.swinglab.site (sign in, then open "API Tokens" in the header).
- Errors are RFC 7807 `application/problem+json`. There is no quota and no rate-limit header: requests are not metered.

## Docs

- [OpenAPI spec](https://app.swinglab.site/api/openapi.json): the full machine-readable contract
- [API reference](https://app.swinglab.site/api/docs): the same spec in Swagger UI

## Try it without an account

- `curl https://app.swinglab.site/api/securities/by-symbol/AAPL/snapshot` returns one security's `setupScore`, `setupCategory`, `scoreBreakdown` (each factor with points, max points and evidence), `setupEvaluation` (qualifies / weakens / invalidates) and `dataHealth`.

## Agent endpoints (bearer token)

- `GET /api/agent/v1/scans`: the available scans (`strong-setup-score`, `top-rs`, `near-highs`, `recent-gap-breakout`)
- `GET /api/agent/v1/scans/{ref}/results?limit=10&page=1`: one scan's ranked results
- `GET /api/agent/v1/context/scans/{ref}?limit=10`: a scan's results with a brief per symbol
- `GET /api/agent/v1/context/symbols/{symbol}`: the context packet for one symbol
- `GET /api/agent/v1/briefs/{symbol}`: a compact brief for one symbol
- `POST /api/agent/v1/analysis` with `{"tickers": ["AAPL", "MSFT"]}` (up to 50): score, factor breakdown and evaluation per ticker
- `GET /api/agent/v1/watchlists`, `GET /api/agent/v1/watchlists/{ref}/securities`: system and personal watchlists. Refs are `kind:id` (`system:510`, `personal:42`) everywhere — the list publishes the ref the other endpoints take.
- `GET /api/agent/v1/news?tickers=AAPL,MSFT`: recent headlines per ticker

## Reading the output correctly

- A null setup score means "no judgment" (for example, data health is `SUSPECT`). It never means zero.
- Check data health and timestamps before relying on a score; stale inputs are flagged, not hidden.
- Scores are versioned. Compare scores only within the same version.
- Present SwingLab output as research context with its evidence, never as a recommendation to buy or sell.