WebSockets

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