# Overview

**CuteMarkets** provides a clean, developer-friendly REST API for U.S. options and stocks market data - built for quants, traders, and AI applications. Data is delivered through a simple HTTP API with consistent authentication, response envelopes, and pagination.

## Base URL

```
https://api.cutemarkets.com
```

All endpoints are versioned under `/v1/`.

WebSocket streams are available at `wss://api.cutemarkets.com/v1/ws/{market}/` on Expert (€99/mo yearly or €119/mo monthly) and Commercial (€399/mo yearly or €469/mo monthly) plans only. See [WebSockets](/docs/websockets) for authentication, subscription, and single-connection rules.

## OpenAPI

The OpenAPI 3.1 specification is published at [https://cutemarkets.com/openapi.json](https://cutemarkets.com/openapi.json). See [OpenAPI](/docs/openapi) for scope and usage notes.

## Quick Start

```bash
curl \
  "https://api.cutemarkets.com/v1/options/chain/NFLX/?limit=1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```bash
curl \
  "https://api.cutemarkets.com/v1/stocks/snapshot/AAPL/" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Sample Response (Option Chain)

```json
{
  "status": "OK",
  "request_id": "cm_adce10cb073745c7b859fc8131b203b0",
  "results": [
    {
      "break_even_price": 100.025,
      "details": {
        "contract_type": "call",
        "expiration_date": "2026-04-02",
        "strike_price": 100,
        "ticker": "O:NFLX260402C00100000"
      }
    }
  ]
}
```

## What's available

| Category | Endpoints |
|---|---|
| Option Chain | Full chain snapshot by underlying ticker |
| Contract snapshot | One contract snapshot (Greeks, IV, quote, trade, underlying) |
| Contracts | List and detail view of contracts |
| Options trades | Tick-level options trade data |
| Options quotes | Bid/ask quotes - **Expert or Commercial options plan** |
| Stocks | Snapshots, movers, ticker reference, trades, quotes, grouped bars, open-close, aggregates, indicators |
| Aggregates | OHLC bars at any timespan |
| Indicators | SMA, EMA, MACD, RSI |
| Reference | Ticker search, expiration dates, stock ticker reference |
| WebSockets | Live event streams for options and stocks - **Expert or Commercial only** |

## Research and backtesting

If you are building a simulator instead of a simple data integration, start with the [Backtesting Framework](/docs/backtesting-framework) knowledge base. It covers the architecture spine for realistic options backtests: point-in-time contract discovery, causal replay loops, quote-aware execution, contract selection, robustness checks, and regression tests.

The public CuteMarkets backtesting package is documented in [cutebacktests](/docs/cutebacktests).

## Response format

Every response follows a standard envelope:

```json
{
  "status": "OK",
  "request_id": "cm_6a7e466379af0a71039d60cc78e72282",
  "results": [ ... ],
  "next_url": "https://api.cutemarkets.com/v1/options/contracts/?page=..."
}
```

`request_id` is unique to every request and useful for debugging. On a few routes (for example [Contract snapshot](/docs/option-contract-snapshot)), `results` is a **single object** instead of an array.

The `next_url` field appears only on **paginated** list endpoints when more data is available after the current page. It is a full URL you can request as-is with the same `Authorization` header. When there is no next page, `next_url` is omitted.

## Error responses

```json
{
  "status": "ERROR",
  "request_id": "cm_abc123...",
  "error": {
    "code": "unauthorized",
    "message": "Invalid or inactive API key."
  }
}
```

See [Error Handling](/docs/errors) for the full list of error codes. Start stock integrations at [Stocks REST Overview](/docs/stocks).

## System Status

CuteMarkets provides a public health endpoint you can poll from your own uptime monitors — no authentication required.

```bash
curl https://api.cutemarkets.com/v1/status/
```

```json
{
  "status": "ok",
  "request_id": "cm_a1b2c3...",
  "services": {
    "api":      { "status": "ok" },
    "database": { "status": "ok", "latency_ms": 1.42 },
    "cache":    { "status": "ok", "latency_ms": 0.87 }
  }
}
```

`status` is either `"ok"` (all systems nominal) or `"degraded"` (one or more services impacted). You can also view the live dashboard at [cutemarkets.com/status](/status).