API Reference

The WebSocket API provides continuous market-data events through CuteMarkets authentication, plan controls, and connection limits. WebSocket access is available only on Expert (€99/mo yearly or €119/mo monthly) or Commercial (€399/mo yearly or €469/mo monthly) plans.

Endpoint

wss://api.cutemarkets.com/v1/ws/{market}/

Local development:

ws://localhost:8000/v1/ws/options/

Authentication

API clients should pass a product-scoped bearer API key during the WebSocket handshake:

npx wscat \
  -c "wss://api.cutemarkets.com/v1/ws/options/" \
  -H "Authorization: Bearer YOUR_API_KEY"

Browser clients cannot set custom WebSocket headers, so api_key is also accepted as a query parameter:

const ws = new WebSocket(
  `wss://api.cutemarkets.com/v1/ws/stocks/?api_key=${encodeURIComponent('YOUR_API_KEY')}`,
);

Prefer the Authorization header outside browser-only integrations because query strings can be captured in logs.

Protocol

CuteMarkets authenticates the stream automatically. After the socket opens, send subscribe and unsubscribe messages; no extra login message is required.

Subscribe to option trades:

{"action":"subscribe","params":"T.O:SPY260515C00500000"}

Subscribe to stock minute aggregates:

{"action":"subscribe","params":"AM.AAPL"}

Unsubscribe:

{"action":"unsubscribe","params":"AM.AAPL"}

Stream messages are forwarded without schema changes. Status messages and event arrays use the market-data stream shape.

Connection limit

Only one WebSocket connection is allowed per CuteMarkets user across all API keys and markets. If the same user opens a second connection, the second connection is rejected with close code 4409.

The lock is stored in Redis with a short TTL and refreshed while the socket is alive. If a process dies without a clean disconnect, the stale lock expires automatically.

Plan behavior

For stocks, use a Stocks API key and the stock product tier is used. For options, use an Options API key and the options tier is used. Connections without Expert or Commercial access are rejected before any market-data stream is opened.

Close codes

Example client

import WebSocket from 'ws';

const ws = new WebSocket('wss://api.cutemarkets.com/v1/ws/options/', {
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});

ws.on('open', () => {
  ws.send(JSON.stringify({
    action: 'subscribe',
    params: 'T.O:SPY260515C00500000',
  }));
});

ws.on('message', (data) => {
  console.log(JSON.parse(data.toString()));
});

Related docs

• Authentication
• Rate Limits & Plans
• Trades
• Quotes

Connection lifecycle guidance

Treat the socket as a shared account resource because only one WebSocket connection is allowed per user. If your application has multiple browser tabs, workers, or backend services, coordinate them through one stream consumer instead of opening independent connections. A common pattern is to run one backend stream process, normalize events internally, and fan out updates to your own clients.

Reconnect logic should be conservative. If the close code is 4401, fix the credential, product key, market path, or plan before retrying. If the close code is 4409, another connection already owns the account stream, so immediate retries will keep failing. If the stream closes with a gateway error after acceptance, retry with backoff and resubscribe only after the socket opens again.

Subscription design

Keep subscription strings explicit and versioned in your application. A trade stream for one option contract and an aggregate stream for one stock ticker serve different product surfaces, and the subscription string should make that visible in logs. Store the requested params, market, account-side stream name, and connection start time so reconnects can restore the same state.

For dashboards, separate live stream updates from historical REST backfills. WebSockets provide current events; REST endpoints provide reproducible history. When a user opens a chart, load the recent history through REST, then use the socket to append new events. That design avoids blank charts after reconnects and keeps the historical record auditable.