Private beta

Tester checklist.

Thank you for testing OptionSpace. Work through these steps in order, then push on anything that looks fragile. Each step says what success looks like. When something goes wrong, note the time and the exact error text, and tell us.

Before the first step, finish the month-to-month Pro checkout with your personal code. Do not create an API key yet: step 2 tells you when, so you can paste it straight in. Check the known issues so you do not spend time on something we already know about.

1. Install

Works on Windows (in PowerShell), macOS and Linux. If you do not have uv yet, install it once, then close the terminal and open a new one.

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS or Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then, on every system, in a new folder for your research:

mkdir optionspace-beta
cd optionspace-beta
uv init --bare --python 3.12
uv add "optionspace[charts,mcp]" notebook
uv run optionspace --version

Done when the last line prints optionspace 0.9.0 or later. Every command below starts with uv run and runs from this folder. Full instructions: Getting started.

If uv warns that VIRTUAL_ENV=… does not match the project environment, another Python environment (conda or a virtualenv) is switched on in your terminal. It is harmless: uv still installs into this folder. To silence it, run deactivate (or conda deactivate) first.

2. Save your key and make a first call

Save your key (once)

On your account page, create an API key and copy it. It is shown only once. Then, straight away, in your research folder, run:

uv run optionspace login

In the terminal

OptionSpace API key (input hidden): ▏

Paste, then press Enter.

Click inside the terminal window.
Paste your API key: Ctrl+V in Windows PowerShell (or right-click), Command+V on macOS, Ctrl+Shift+V in most Linux terminals.
Press Enter (Return on a Mac).

Nothing appears while you paste. This is normal. Do not paste a second time. If you think you pasted the wrong text, press Ctrl+C and run uv run optionspace login again.

OptionSpace checks the key, then saves it in your system's credential store: Credential Manager on Windows, Keychain on macOS, the Secret Service on Linux. If macOS asks whether Python may use the saved credential, allow it. From now on Python, the notebooks and MCP find the key on their own: never paste it into a script, a notebook cell or an AI chat.

Check it:

uv run optionspace whoami

uv run optionspace logout removes the saved key from this computer only; to switch a key off everywhere, revoke it on your account page.

First call

Then save this as first_smile.py in the same folder and run uv run python first_smile.py:

import optionspace as osp

client = osp.Client()
smile = client.smile("SPY", "2025-04-10", expiration="2025-04-17")
print(smile.attrs["snapshot_time"], smile.attrs["atm_vol"])
print(smile.head())

Done when whoami names the default profile and your plan, and the script prints a time, an ATM volatility (a decimal: 0.20 means 20%) and a table. Help: login troubleshooting.

3. Run each starter notebook

Download the four starter notebooks into this folder, start Jupyter with uv run jupyter notebook and run each from top to bottom: quickstart, chains and surfaces, intraday ATM history, earnings research.

Done when every cell runs without an error and every chart appears. Note anything that is slow, confusing or looks wrong, with the cell number.

4. MCP in Claude Code

Print your setup, run the Claude Code line it shows once, then start Claude Code:

uv run optionspace mcp --print-config
claude

Inside Claude Code, type /mcp and check that optionspace is connected. Then ask:

What data can I access through OptionSpace?

Show me a chart of the ATM vol term structure for SPY on 2025-04-09 and 2025-04-10.

Done when the answers use your access and data, and the chart path opens in your browser. Then ask a question of your own. Full setup: MCP. Claude Desktop and Cursor should work but are not tested; if you try one, tell us how it went.

5. Hit a limit on purpose

Your plan allows a few requests at a time (four on Pro). This script sends twelve at once, so some should be refused. It uses about a dozen requests of your daily allowance.

from concurrent.futures import ThreadPoolExecutor

import optionspace as osp

WORKERS = 12
clients = [osp.Client() for _ in range(WORKERS)]


def one(c):
    try:
        c.smile("SPY", "2025-04-10", expiration="2025-04-17")
        return "ok"
    except osp.QuotaExceeded as refused:
        return f"refused: {refused.reason}, retry after {refused.retry_after_seconds} s"


with ThreadPoolExecutor(WORKERS) as pool:
    for result in pool.map(one, clients):
        print(result)

Done when at least one line says refused: concurrent with a short wait time. If none are refused, set WORKERS = 24 and run it again. Check that the message makes sense to you and that a call made a few seconds later succeeds.

6. Try a research call

Research calls answer a whole question in one request. They take longer than a lookup (several seconds to a minute), and each result's credits says what it cost. Try estimate=True first to see the most a call can cost. They run one at a time per account.

import time

import optionspace as osp

client = osp.Client()
started = time.perf_counter()
history = client.earnings_history("NVDA", "2026-09-16", count=8)
print(f"{time.perf_counter() - started:.1f} s")
for event in history["events"]:
    print(event["earnings_date"], event["implied_move"], event["actual_move"], event["status"])

Done when it prints the time taken and one line per report. Try a second research call while the first is running (for example from notebook 4 in another window) and read the refusal. Reference: research routes.

7. Optional: the REST API with curl

Only if you will call the REST API directly, without Python. curl cannot use the key you saved in step 2, so this asks for it once more at a hidden prompt, makes two calls and clears it again. Nothing is saved.

macOS or Linux, in two parts. Pasted as one block, the first line would read the next line as your key.

Run this line on its own first, then paste your key and press Enter (nothing appears as you paste, which is normal):

printf 'OptionSpace API key (hidden): '; read -rs OPTIONSPACE_API_KEY; echo; export OPTIONSPACE_API_KEY

Then run the calls:

curl -sS -H "Authorization: Bearer $OPTIONSPACE_API_KEY" \
  https://optionspace.ai/api/v1/data/entitlements
curl -sS -H "Authorization: Bearer $OPTIONSPACE_API_KEY" \
  "https://optionspace.ai/api/v1/data/smile?symbol=SPY&data_date=2025-04-10&expiration=2025-04-17&snapshot=EOD" \
  | head -c 800
unset OPTIONSPACE_API_KEY

Windows PowerShell, also in two parts (the prompt shows asterisks as you paste):

Run this line on its own first, then paste your key and press Enter:

$key = [Net.NetworkCredential]::new('', (Read-Host 'OptionSpace API key' -AsSecureString)).Password

Then run the calls:

curl.exe -sS -H "Authorization: Bearer $key" https://optionspace.ai/api/v1/data/entitlements
$r = curl.exe -sS -H "Authorization: Bearer $key" "https://optionspace.ai/api/v1/data/smile?symbol=SPY&data_date=2025-04-10&expiration=2025-04-17&snapshot=EOD"
$r.Substring(0, [Math]::Min(800, $r.Length))
Remove-Variable key, r

Done when the first call prints your plan, limits and usage as JSON, and the second prints the start of a smile. The key stays in that terminal window only and is cleared by the last line. Try one deliberate mistake too, such as data_date=2025-13-40, and read the error. Reference: REST API.

8. Push on it

Use the dashboards, other symbols and dates, larger pulls and the questions you would really ask. We want to hear about anything that is wrong, slow, confusing or missing, including things that worked but took you too long to figure out.

How to report

Email [email protected] with:

What you did: the step, the command or code, and the symbol, date and other inputs.
When: the time, with your time zone.
What happened: the full error text or a screenshot, and what you expected instead.
Your setup: the output of uv run optionspace --version, your operating system, and for MCP the client name.

Never send your API key, an Authorization header or a credential file. Check screenshots before sending. The public key ID (it starts with osk_) is safe to share and helps us find your calls.

Continue exploring