API Key Management
Generate and manage API keys for programmatic access
API keys allow you to access Optionomics data programmatically through the REST API and the MCP Server. Keys are managed in the developer console. This feature is part of the Vega plan.
Generating API Keys
Prerequisites
- Active Vega plan subscription
- Verified email address
Steps to Generate a Key
- Open the developer console
- Log into your account
- Choose Developer in the sidebar, or go to optionomics.ai/developers/keys
- Click Create key
- Configure Your Key
- Name: A descriptive name (e.g., “trading-bot”, “research-script”)—one credential per client is the intended pattern, so each can be revoked on its own
- Expires in (optional): A number of days, or blank for a key that lasts until revoked
- Save Your Token
- Copy the token from the banner immediately
- Important: The token is stored hashed, so this is the only time it can be shown
- Store it securely in your application
The keys table shows each key’s name, creation date, expiry, and last used time—so a leaked or forgotten key is easy to spot—with a revoke action per row. Keys inside their final week are flagged as expiring soon.
Using Your API Key
Authentication Headers
Include both headers in API requests:
X-USER-EMAIL: [email protected]
X-USER-TOKEN: your-api-token
The pair must match—a token presented against a different account’s email is refused. Standard bearer authentication is also accepted:
Authorization: Bearer your-api-token
Example Request
Fetch SPY options:
curl "https://optionomics.ai/api/v1/stocks/SPY/options" \
-H "X-USER-EMAIL: [email protected]" \
-H "X-USER-TOKEN: your-api-token"
List supported symbols:
curl "https://optionomics.ai/api/v1/tickers" \
-H "X-USER-EMAIL: [email protected]" \
-H "X-USER-TOKEN: your-api-token"
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, and trade ideas. 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) that exists so you can explore without minting a permanent credential.
Rate limits
The documented allowance is 1,000 requests per minute per account, shared across the REST API, the MCP server, and the reference page’s playground—two keys on one account share one allowance. Every authenticated response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers; requests above the limit return 429 Too Many Requests with a Retry-After header. Build clients with backoff rather than immediate retries.
Monitoring your integration
The developer console’s API requests tab logs every REST call made with your keys—endpoint, outcome, response size, and latency—and the MCP logs tab does the same for tool calls. Start there when a client misbehaves.
Troubleshooting
Common Issues
- 401 Unauthorized: Invalid token or email, or a mismatched pair
- 402 Payment Required: No active subscription
- 403 Forbidden: Your plan does not include API access (upgrade to Vega)
- 429 Too Many Requests: Rate limit exceeded—honor
Retry-After
Getting Help
- Review the API Reference
- Review the MCP Server Guide
- Contact [email protected]
Security Note: Treat API keys as passwords. If a key is compromised, revoke it immediately and generate a new one. Name keys per client so a revocation touches only the client that leaked.
