> ## Documentation Index
> Fetch the complete documentation index at: https://docs.traderos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Use TraderOS from a script with an API key

> Pull TraderOS levels, GEX, options chains and studies into your own script, spreadsheet or trading platform with an API key: the address, the header, a curl, PowerShell and Python example, and the answer format.

Use an API key when no assistant is involved: a script that runs every 15 minutes, a spreadsheet, or a charting platform that reads a file. The key reads the same tools your assistant uses, with the same sources, as-of times and ages.

> [!NOTE]
>
> A new API key is **read-only**. It can read market data and your own results. It cannot change your account, save anything for you, or start a paid run. Keep the key secret, because anyone who holds it can read through your account and use your credits.

## Create a key

**1. Open API Keys**

In TraderOS, open your account menu, then **Settings**, then **API Keys**.

**2. Create the key**

Choose **Create API key**, give it a name that says where it will be used, and copy the key. It starts with `tros_` and is shown **once**.

**3. Revoke it when you are done**

To stop a key working, revoke it on the same screen. A revoked key is refused at once.

## Where to send the key

Send a JSON request to this address and put the key in an `Authorization` header:

```text theme={"dark"}
POST https://api.traderos.ai/api/v1/harness/mcp
Authorization: Bearer YOUR_KEY
Content-Type: application/json
```

The hosted assistant address, `https://mcp.traderos.ai/mcp`, takes the same key in the same header, for assistants and tools that connect over MCP and cannot sign in. A script that just wants an answer is simpler against the address above, because it needs no setup call.

## Ask for an answer

The request names a tool and its arguments. This one asks for the GEX levels of NQ:

```json theme={"dark"}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "market_gex_levels",
    "arguments": { "ticker": "NQ" }
  }
}
```

Change `name` and `arguments` for any tool in the [tool reference](https://docs.traderos.ai/mcp/tools.md): `market_key_levels`, `market_options_chain`, `market_ohlcv`, `market_quote` and the rest.

To list the tools your key can use, send:

```json theme={"dark"}
{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }
```

### curl

```bash theme={"dark"}
curl -s -X POST https://api.traderos.ai/api/v1/harness/mcp \
  -H "Authorization: Bearer $TRADEROS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"market_gex_levels","arguments":{"ticker":"NQ"}}}'
```

### Python

```python theme={"dark"}
import os, requests

def ask(tool, **arguments):
    reply = requests.post(
        "https://api.traderos.ai/api/v1/harness/mcp",
        headers={"Authorization": f"Bearer {os.environ['TRADEROS_KEY']}"},
        json={
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {"name": tool, "arguments": arguments},
        },
        timeout=60,
    )
    reply.raise_for_status()
    return reply.json()["result"]["structuredContent"]["data"]

levels = ask("market_gex_levels", ticker="NQ")
print(levels["call_wall"], levels["put_wall"], levels["gamma_flip"], levels["as_of"])
```

### PowerShell

```powershell theme={"dark"}
$body = @{
  jsonrpc = "2.0"; id = 1; method = "tools/call"
  params  = @{ name = "market_gex_levels"; arguments = @{ ticker = "NQ" } }
} | ConvertTo-Json -Depth 5

$reply = Invoke-RestMethod -Method Post `
  -Uri "https://api.traderos.ai/api/v1/harness/mcp" `
  -Headers @{ Authorization = "Bearer $env:TRADEROS_KEY" } `
  -ContentType "application/json" -Body $body

$levels = $reply.result.structuredContent.data
"$($levels.call_wall) $($levels.put_wall) $($levels.gamma_flip) $($levels.as_of)"
```

Put the key in an environment variable or a file only you can read. Do not paste it into a script you share.

## What comes back

The answer is in `result.structuredContent.data`. The same JSON is also in `result.content[0].text`. Every answer carries its source, `as_of` time and age. See [How to read MCP results](https://docs.traderos.ai/mcp/read-the-results.md).

If a request fails, the reply says why in plain words: a key that is missing, revoked or expired, a ticker we do not hold, or a call that needs the app.

## How often to ask

Ask no more often than the data changes. Futures GEX is calculated every 15 minutes from options data that arrives 20 to 35 minutes late, so a snapshot is usually 35 to 60 minutes old. Asking every minute only returns the same snapshot. Most other levels are fixed for the day. Calls use your own credits where a tool has a price, and the rate limits that apply to every connection.

## Troubleshooting

* **401 or "unauthorized"**: the key is wrong, revoked or expired. Check you copied the whole key, starting with `tros_`, and send it as `Authorization: Bearer YOUR_KEY`. Do not send it as `X-API-Key` or in the address.
* **"This API key is read-only"**: the call tried to change something. Read-only keys read market data and your results only.
* **A ticker is missing**: ask `market_coverage` what we hold for it. An unknown ticker starts a request to add it.
* **Still stuck**: use **Report a problem** in the app and include the time of the call and the error text. Never include the key.

## Frequently asked questions

### Can I use my TraderOS API key with the Claude connector address?

Yes. The hosted address `https://mcp.traderos.ai/mcp` takes the key as `Authorization: Bearer YOUR_KEY`. A script is simpler against `https://api.traderos.ai/api/v1/harness/mcp`.

### Can an API key place trades or change my account?

No. A new key is read-only: it reads market data and your results. TraderOS never places orders.

### Where do I get an API key?

In TraderOS, open your account menu, then **Settings**, then **API Keys**, and choose **Create API key**.

### How do I stop a key working?

Revoke it in **Settings**, **API Keys**. It is refused immediately.

### Can I pull TraderOS GEX levels into Sierra Chart, Excel or my own platform?

Yes. A script that calls the address above with your key can write the levels to a file, a sheet or a chart study. Ask no more often than every 15 minutes for GEX.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.