# Overview

**CuteMarkets** is backtesting built by traders: a clean, developer-friendly REST and WebSocket API for U.S. options and stocks market data. Data is delivered with consistent authentication, response envelopes, pagination, and live stream behavior.

New to options mechanics? Start with [Learn Options Trading From Zero](/learn-options) before you wire chains, quotes, Greeks, or historical contracts into an app.

## 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).

## Market data sources

Options integrations should keep source, freshness, and field semantics visible. Start with [Data Sources and OPRA](/docs/data-sources-opra) when you need to explain OPRA-originating options data. The related guides cover the common questions teams run into when evaluating or building with market data:

- [Market Data SIPs and Direct Feeds](/docs/market-data-sips-direct-feeds) for OPRA, CTA, UTP, SIP, and direct-feed distinctions.
- [Quotes, Trades, and Aggregates](/docs/quotes-trades-aggregates-semantics) for field semantics and "what is a price?" decisions.
- [Option Symbols and Contract Identity](/docs/option-symbols-contract-identity) for OCC-style tickers and point-in-time contract identity.
- [Live, Delayed, and Entitlements](/docs/live-delayed-entitlements) for plan-aware freshness, quote access, and WebSocket eligibility.
- [Corporate Actions and Adjusted Options](/docs/corporate-actions-adjusted-options) for splits, mergers, adjusted deliverables, and contract sizing.
- [Backtesting Data Quality Checklist](/docs/backtesting-data-quality-checklist) for production-grade research artifacts.

## 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).