# Top 5 Stocks API

Top 5 Stocks provides daily ranked stock, crypto, and macro research data for apps, bots, dashboards, newsletters, finance creators, and AI coding-agent prototypes.

Use this file as the AI-agent entry point for integrating the API in Claude Code, Codex, Cursor, Replit Agent, and other coding assistants.

## Primary API Resources

- API metadata: https://top5stocks.netlify.app/api/v1/metadata.json
- OpenAPI spec: https://top5stocks.netlify.app/api/v1/openapi.json
- Free daily watchlist: https://top5stocks.netlify.app/api/v1/free/today.json
- Developer docs: https://top5stocks.netlify.app/developers
- Public performance: https://top5stocks.netlify.app/api/performance

## Endpoints

Free endpoint:

`GET /api/v1/free/today.json`

Authenticated gateway endpoints:

- `GET /api/v1/watchlist/today.json`
- `GET /api/v1/stocks/today.json`
- `GET /api/v1/macro/today.json`
- `GET /api/v1/performance.json`
- `GET /api/v1/alerts/today.json`
- `GET /api/v1/undervalued/latest.json`
- `GET /api/v1/beta-readiness.json`

Additional public endpoints:

- `GET /api/v1/crypto/today.json`
- `GET /api/v1/performance/cumulative.json`
- `GET /api/v1/metadata.json`
- `GET /api/v1/openapi.json`

## Important Fields

- `data.stocks[].symbol`
- `data.stocks[].asset_type`
- `data.stocks[].selection_score`
- `data.stocks[].model_bias`
- `data.stocks[].risk_level`
- `data.stocks[].catalyst_summary`
- `data.stocks[].thesis`
- `data.stocks[].technical_levels.current_price`
- `data.stocks[].technical_levels.moving_average_50`
- `data.stocks[].technical_levels.moving_average_200`
- `data.stocks[].technical_levels.vwap_reference`
- `data.stocks[].why_ranked`
- `data.macro.macro_regime`
- `data_freshness.status`

## Integration Notes For Agents

- Treat the API as educational market research and watchlist data.
- Do not present responses as personalized investment advice or guaranteed outcomes.
- Treat `technical_levels` as public market-data context. Private model levels are not exposed.
- Use `/metadata.json` to discover available endpoints and `/openapi.json` for generated clients.
- Use `/api/performance` for public tracking context.
- Send `X-API-Key` or `Authorization: Bearer <key>` to authenticated gateway endpoints.

## Example

```bash
curl -s https://top5stocks.netlify.app/api/v1/free/today.json
```