Get connected

One key. Three ways to work.

Start with a saved API key, check your access, then choose Python, a direct API request or your AI research client.

1 Install2 Paste your key3 Check access4 Run a query

Before you start

You need an OptionSpace account, an API key and a terminal. The steps are the same on Windows, macOS and Linux; the few places that differ show each system side by side.

Windows: open PowerShell (Start menu, type PowerShell).
macOS: open Terminal (Applications → Utilities → Terminal).
Linux: open your terminal.

Already have a key? Keep it ready to paste at the login prompt in step 2. You do not enter it into this documentation page, your AI conversation or a Python source file.

Need a key? Sign in to your account, create a key and copy its one-time secret. Your account must have permission to create keys. If the option is unavailable, contact your organization's administrator or [email protected].

1. Install

The package installs with uv, a free Python installer. It sets up the right Python version for you, keeps this installation separate from your other projects, and needs nothing activated afterwards.

a. Install uv once. Skip this if you already have it.

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 close the terminal and open a new one, so it finds uv.

b. Create your research folder and install. These lines are the same on every system:

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

Run the lines in order. The last one should print optionspace 0.9.0. Every command after this starts with uv run from inside this folder; next time, open a terminal and cd optionspace-research first. (Name the folder anything except optionspace.)

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.

The extras are optional: uv add optionspace installs the data client alone; [charts] adds charts and session replays, and [mcp] adds the local server for AI research clients.

Prefer pip? In a virtual environment, use that environment's Python wherever this guide says uv run: python3 -m venv .venv then .venv/bin/python -m pip install "optionspace[charts,mcp]" on macOS and Linux, or py -m venv .venv then .venv\Scripts\python -m pip install "optionspace[charts,mcp]" on Windows. Then .venv/bin/python -m optionspace login (Windows: .venv\Scripts\python -m optionspace login), and so on.

Only need direct REST requests? You can use the API guide without installing the OptionSpace package.

In the research folder, run:

uv run optionspace login

The terminal will show:

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) to submit it.

You will not see letters, dots or asterisks while pasting. This is normal. Do not paste a second time just because the prompt looks unchanged. If you think you pasted the wrong text, press Ctrl+C and run uv run optionspace login again.

OptionSpace checks the key before saving it, then keeps it in your system's credential store: Credential Manager on Windows, Keychain on macOS, the Secret Service (GNOME Keyring or KWallet) on Linux. If macOS asks whether Python may use the saved credential, allow it. On a Linux server with no desktop, see login troubleshooting.

How to know it worked

The success message begins with “stored in the keyring store as profile 'default'” and names https://optionspace.ai. It then shows a public key identifier and your account's access information. It does not print the secret key.

What you see	What it is	How to handle it
`sk_os_…`	Secret API key, used to authenticate	Paste only at the hidden login prompt; keep private
`osk_…`	Public key ID, identifying which key is in use	Safe to share for troubleshooting; cannot authenticate requests

Seeing an osk_… identifier in whoami does not mean your secret has been printed.

If you see “key was rejected” or “nothing stored,” follow login troubleshooting. Do not continue until login succeeds.

3. Check your access

uv run optionspace whoami

Look for the credential source, profile, server, grants and today's usage.

Your key controls the symbols, dates, snapshot frequency and quote fields available to you. The April 2025 examples in these guides require access to that period; not every account or free sample includes it.

4. Choose your first result

PythonFetch a smile. Open a chart.

DataFrames and editable figures in your own research environment.

REST APIMake a direct request.

Authenticate over HTTPS and inspect the JSON response.

MCPAsk your research question.

Connect Claude Code to the same saved credential and data tools.

Prefer to learn from runnable examples? Download the starter notebooks. Check the known issues before reporting a problem.

Keep your key private

Save the key through uv run optionspace login. Do not put it into a notebook cell, repository, screenshot, support email or agent prompt. Python and MCP can use the saved credential without copying the secret into their configuration.

uv run optionspace logout removes the local saved credential. It does not revoke the key on the server. To disable a key, revoke it on your account page. After rotating a key, run uv run optionspace login with the replacement.

For named profiles, environment variables and common setup problems, see Troubleshooting.

Continue exploring