API Reference

The CuteMarkets options and stocks APIs have a published OpenAPI 3.1 specification:

• OpenAPI JSON

Use it with API clients, code generators, docs tools, or agent frameworks that can ingest OpenAPI.

Authentication

The spec uses a bearer security scheme for API keys:

Authorization: Bearer YOUR_API_KEY

Scope

The specification covers the documented REST market-data surface:

• option chains and contract snapshots
• contract reference lookups
• options trades and quotes
• stock snapshots, movers, and ticker reference
• stock trades and quotes
• aggregate bars, previous-day bars, and open-close snapshots
• SMA, EMA, MACD, and RSI indicators
• ticker search and expiration lookup

The WebSocket gateway is documented separately in WebSockets, because OpenAPI does not model the live streaming protocol.

Base URLs

Production:

https://api.cutemarkets.com

Local development:

http://localhost:8000

Related docs

• Overview
• Authentication
• Stocks REST Overview
• Error Handling
• Agents.md

Code generation checklist

The OpenAPI file is useful for typed clients, smoke tests, and agent tooling, but generated clients still need product-specific configuration. Keep the base URL, bearer token injection, retry policy, and pagination handling outside generated endpoint methods so they can be changed without regenerating the entire client.

Agent and CI usage

For CI, use the specification to validate request shapes and response envelopes before hitting live endpoints. For coding agents, pair the OpenAPI file with Agents.md, because the agent doc explains product intent, endpoint order, and common workflow boundaries that a schema alone cannot express.

What the schema does not decide

The OpenAPI schema describes endpoint paths, parameters, response shapes, and authentication mechanics. It does not decide which endpoint should be called first in a workflow. For example, an options application should usually discover expirations before requesting a chain, then select a contract before requesting historical quotes or trades. A generated client can call every endpoint, but the application still needs product logic.

The schema also does not replace plan checks. A route can be valid while the current key lacks the product scope, quote entitlement, or historical lookback required by the request. Generated clients should expose the full error envelope so callers can distinguish bad parameters from missing entitlement.

Recommended client structure

Keep generated endpoint methods small and deterministic. Wrap them with a hand-written client layer that owns authentication, product key selection, retries, logging, and pagination. That layer should attach the correct Options or Stocks API key, preserve the request_id from every response, and treat next_url as an opaque URL instead of rebuilding cursor parameters.

For teams using agentic coding tools, check the generated code into version control and regenerate it deliberately when the OpenAPI file changes. Do not let every agent run a different generator configuration. Stable generated clients make documentation examples, CI tests, and application code easier to compare.

OpenAPI implementation notes

Use OpenAPI for typed method generation, schema checks, and smoke tests. Keep workflow policy outside the generated code. The client wrapper should own bearer-token injection, product key selection, retries, pagination, request id logging, and error-envelope handling. That wrapper can change without regenerating every endpoint method.

Generated methods also need market-data context from the docs. The schema can say that Quotes, Trades, Aggregates, and Contracts exist, but it cannot decide the safe request order for a backtest or scanner. Pair this file with Agents.md when feeding an LLM or code generator so endpoint shape and product intent stay together.

Additional implementation review

Review the OpenAPI client workflow as a sequence of named data objects, not as a single helper call. The implementation should preserve base URL, bearer token, response envelope, request id, pagination cursor, retry policy, product scope, and endpoint family. Those fields make support tickets, CI fixtures, and replay notebooks easier to compare because every step can point to the exact request and response that created the displayed value.

The main failure mode is that generated methods can be mechanically correct while the application calls endpoints in the wrong order for the workflow. Before promoting the workflow, run one concrete example through discovery, retrieval, display, logging, and error handling. Keep the resulting artifact beside the code path so future changes can prove they still use the same terminology and the same market-data assumptions.