> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stratalerts.com/llms.txt
> Use this file to discover all available pages before exploring further.

# REST and WebSockets

> Access StratAlerts market data programmatically. REST endpoints for snapshots and history; WebSocket streams for live prices, state changes, and alert events.

The StratAlerts Partner API gives you direct, programmatic access to the same market data that powers the scanner — instrument metadata, OHLCV candles, TFC states, setup detection, and live alerts. You can pull current snapshots over REST or subscribe to live streams over WebSocket, depending on whether you need point-in-time data or continuous updates.

<Note>
  API access requires a separate **API Access** subscription plan. Your standard StratAlerts subscription does not include API access. [Subscribe at app.stratalerts.com](https://app.stratalerts.com/billing/subscribe/?plan=market_api) to get started.
</Note>

## Delivery modes

<CardGroup cols={2}>
  <Card title="REST" icon="arrow-right-arrow-left">
    Request historical data, current snapshots, and batch lookups over HTTPS. Best for periodic polling, backtesting, and on-demand queries.
  </Card>

  <Card title="WebSocket" icon="bolt">
    Maintain a persistent connection and receive pushed updates as they happen. Best for live dashboards, execution systems, and alert ingestion.
  </Card>
</CardGroup>

## Base URLs

| Transport | Base URL                                    |
| --------- | ------------------------------------------- |
| REST      | `https://app.stratalerts.com/api/market/v1` |
| WebSocket | `wss://app.stratalerts.com/ws/market/v1`    |

## REST endpoints

Every endpoint requires a valid API key with the appropriate scope. See [Authentication](/api/authentication) for how to pass your key.

| Method | Path                          | Scope           | Description                                            |
| ------ | ----------------------------- | --------------- | ------------------------------------------------------ |
| `GET`  | `/instruments`                | `metadata:read` | List instruments with name, exchange, type, and sector |
| `GET`  | `/instruments/{symbol}`       | `metadata:read` | Fetch metadata for a single instrument                 |
| `GET`  | `/prices/latest`              | `prices:read`   | Latest trade price for one or more symbols             |
| `GET`  | `/candles/{symbol}`           | `candles:read`  | OHLCV bars at any supported timeframe                  |
| `GET`  | `/states/{symbol}`            | `states:read`   | TFC color state and active setups for a symbol         |
| `GET`  | `/setups/current`             | `states:read`   | All active Strat setups across the scan universe       |
| `GET`  | `/alerts/in-force`            | `alerts:read`   | In-force alerts within a rolling time window           |
| `GET`  | `/alerts/simultaneous-breaks` | `alerts:read`   | Simultaneous break alerts across timeframes            |
| `GET`  | `/market-status`              | `metadata:read` | Current market open/close status and session times     |

## WebSocket channels

After connecting to `wss://app.stratalerts.com/ws/market/v1`, you subscribe to channels by sending a JSON message with `"op": "subscribe"`. Your key must have `ws:connect` scope plus the scope corresponding to each channel.

| Channel                      | Scope         | Description                                          |
| ---------------------------- | ------------- | ---------------------------------------------------- |
| `quotes`                     | `prices:read` | Real-time trade price updates for subscribed symbols |
| `states`                     | `states:read` | Live TFC state changes and setup updates per symbol  |
| `alerts.in_force`            | `alerts:read` | Pushed in-force alert events as they fire            |
| `alerts.simultaneous_breaks` | `alerts:read` | Pushed simultaneous break alert events               |

## Quick example

The following request fetches the current market status using `curl`. Replace `YOUR_API_KEY` with your actual key.

```bash theme={null}
curl -s \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://app.stratalerts.com/api/market/v1/market-status
```

A successful response looks like this:

```json theme={null}
{
  "market": "stocks",
  "timezone": "America/New_York",
  "is_open": true,
  "session": {
    "label": "RTH",
    "session_date": "2026-04-10",
    "open_ts": "2026-04-10T09:30:00-04:00",
    "close_ts": "2026-04-10T16:00:00-04:00"
  },
  "now": "2026-04-10T11:22:00-04:00"
}
```

## Error format

All error responses use a consistent JSON envelope regardless of the endpoint or HTTP status code.

```json theme={null}
{
  "error": {
    "code": "error_code_here",
    "message": "Human readable message"
  }
}
```

See [Authentication](/api/authentication) for the specific error codes returned for missing or invalid keys, and [Rate Limits](/api/rate-limits) for throughput-related errors.

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api/authentication">
    Learn how to obtain an API key, pass it in requests, and understand scope requirements.
  </Card>

  <Card title="Rate limits" icon="gauge" href="/api/rate-limits">
    Understand per-key throughput limits, burst behavior, and WebSocket connection rules.
  </Card>
</CardGroup>