API Key Management

Create and manage API keys for the MCP server, REST API, and websocket

An API key lets a program act as your Optionomics account: an AI client connected to the MCP Server, your own code calling the REST API, or a program holding the websocket. Keys are managed at optionomics.ai/developers/keys, the first page of the developer console.

Availability: Any signed-in account can create API keys. Without the Developer plan a key is a free MCP key: it reads the previous trading session through a set of MCP tools. The REST API, the live session, and every MCP tool require Developer; the websocket requires Developer Pro.

What a key reaches on your plan

The keys page has a panel titled What your keys reach on your plan that states this for your own account. One key opens all three surfaces; what each one answers depends on the plan:

  No Developer plan (free MCP key) Developer Developer Pro
MCP server The previous session’s readings, through expected_move, earnings_move, pulse, session_list, track_record, price_history, stock_quote, and events The live session, every tool The live session, every tool
REST API Refused—402 without a subscription, 403 on the Trader plan, with a message saying so The live session, every endpoint The live session, every endpoint
Websocket — — trade_ideas, market_commentaries and readings:signals
Requests per minute 1,000 (MCP) 1,000, REST and MCP together 5,000, REST and MCP together

See Subscription Plans for plan prices.

Creating a key

  1. Open the keys page
    • Sign in to your account.
    • Go to optionomics.ai/developers/keys, or choose Developer in the sidebar (under Desk) or Developer console in the account menu.
    • Choose Create key.
  2. Configure the key
    • Name: a descriptive name, such as claude-desktop, trading-bot, or research-script. Name it after the thing that will hold it—one key per client is the intended pattern, so each can be revoked on its own later.
    • Expires in (optional): a number of days between 1 and 3,650, or leave it blank for a key that lasts until you revoke it.
  3. Copy the key
    • The new key appears in a Your new API key panel at the top of the page, with a ready-made cURL request beneath it.
    • Copy it now. The key is stored hashed, so this is the only time it can be shown. If you lose it, revoke it and create another.
    • Store it somewhere safe, such as an environment variable or a password manager.

The keys page

  • Keys — a table of your keys with each key’s name, creation date, expiry, and last used time, so a leaked or forgotten key is easy to spot. A key in its final week shows its expiry date highlighted; an expired key is struck through and marked Expired. The trash button on each row revokes that key—anything using it stops working immediately.
  • What your keys reach on your plan — the panel described above: what the REST API and MCP answer for your account, whether the websocket is open to it (on Developer Pro, with a link to the Websocket tab for its address and topics), and your request allowance a minute.
  • Where the key goes — your account email ready to copy (the X-USER-EMAIL value) and the REST base URL (https://optionomics.ai/api/v1) with a note that MCP clients post to https://optionomics.ai/mcp instead. Below them is Your first request, a cURL example that reads the key from an $OPTIONOMICS_API_KEY shell variable, so you never paste the key itself into your shell history.

Using your key

Authentication headers

Send both headers on every request:

X-USER-EMAIL: your-email@example.com
X-USER-TOKEN: your-api-key

The pair must match—a key presented with a different account’s email is refused.

The REST API also accepts standard bearer authentication with the key alone:

Authorization: Bearer your-api-key

MCP clients that can send only one header use a slightly different bearer form, with the email and key joined and base64-encoded: Authorization: Bearer base64("email:key"). See the MCP Server guide.

The websocket takes the key as the token connect parameter instead of a header.

Example requests (Developer)

Fetch SPY’s options metrics:

curl "https://optionomics.ai/api/v1/stocks/SPY/metrics" \
  -H "X-USER-EMAIL: you@example.com" \
  -H "X-USER-TOKEN: $OPTIONOMICS_API_KEY"

List supported symbols:

curl "https://optionomics.ai/api/v1/tickers" \
  -H "X-USER-EMAIL: you@example.com" \
  -H "X-USER-TOKEN: $OPTIONOMICS_API_KEY"

The currently supported REST endpoints and schemas are listed in the API Reference, which covers market data, options flow, insider and Congress trading, news and events, earnings analyses, trade ideas, and the websocket. Application routes that are not listed there are not part of the public developer contract.

Try it from the reference page

Every endpoint on the API Reference carries a Try it bar that sends the request from your browser and shows the live answer. If you are signed in on a plan with API access, the page can issue a playground key in one click—a short-lived key (24 hours) so you can explore without creating a permanent credential. It appears in your keys table with its expiry like any other key.

Rate limits

Each account may make 1,000 requests a minute, or 5,000 a minute on Developer Pro. The allowance is per account, not per key, and it is shared across the REST API, the MCP server, and the reference page’s playground—two keys on one account share one allowance. The minute is a fixed window that starts on the clock minute.

Every rate-limited response carries three headers:

Header Meaning
X-RateLimit-Limit Your allowance for the minute
X-RateLimit-Remaining Requests left in the current minute
X-RateLimit-Reset When the current minute ends, as a Unix timestamp in seconds

A request above the limit is answered 429 Too Many Requests with a Retry-After header (seconds to wait) and a JSON body that states the rule, so a client that logs bodies but drops headers still knows it:

{
  "error": "Rate limit exceeded: 1000 requests per 60 seconds per account. Retry after 12 seconds.",
  "limit": 1000,
  "window_seconds": 60,
  "retry_after": 12
}

Build clients that wait for Retry-After rather than retrying immediately. The API requests page shows your allowance and how much of it you have used this minute.

Monitoring your integration

On Developer and Developer Pro, the developer console’s API requests page logs every REST call made with your keys—endpoint, outcome, response size, and latency—and the MCP logs page does the same for tool calls. Start there when a client misbehaves. See the Developer Console guide.

Troubleshooting

  • 401 Unauthorized: the key is wrong, expired, or revoked, or the email does not belong to the same account as the key.
  • 402 Payment Required: the REST API was called by an account with no active subscription.
  • 403 Forbidden: your plan does not include the REST API (it needs Developer). A free key still works on the MCP server.
  • 429 Too Many Requests: you crossed your per-minute allowance—wait for Retry-After.
  • An MCP tool says it “needs the Developer plan”: you are on a free MCP key, which reads only the free tools listed above.

Getting help

Security note: Treat API keys as passwords. If a key is compromised, revoke it immediately and create a new one. Name keys per client so a revocation touches only the client that leaked.


Optionomics Documentation

Getting Started
Workspaces
Live Data
AI, Alerts, and Research
Daily Analytics
Historical Research
Mobile and Integrations

Optionomics Documentation