---
title: Getting Started
description: Install, configure credentials, and ship your first Neural workflow
---

Follow these steps in order. Every command has a matching verification check so you know the environment is ready before moving on.

## Prerequisites

- Python 3.10 or newer
- `pip` or `uv`
- Kalshi API key ID and RSA private key (downloadable from the Kalshi console)

## Step 1 – Install Neural

Using `pip`:

```bash
pip install neural-sdk
pip install "neural-sdk[trading]"       # adds kalshi-python + streaming extras
```

Using `uv`:

```bash
uv add neural-sdk
uv add "neural-sdk[trading]"
```

**Verify:**

```bash
python - <<'PY'
import neural
print("Neural version:", neural.__version__)
PY
```

## Step 2 – Configure credentials

1. Place your keys in `secrets/` (keep the directory out of version control):

   ```bash
   mkdir -p secrets
   cat <<'ENV' > secrets/.env
   KALSHI_API_KEY_ID=your_api_key_id
   # choose exactly one of the following two lines
   KALSHI_PRIVATE_KEY_BASE64=base64_encoded_private_key
   # KALSHI_PRIVATE_KEY_PATH=secrets/kalshi_private_key.pem
   KALSHI_ENV=prod
   ENV
   ```

2. Load them into the shell whenever you start a session:

   ```bash
   export $(grep -v '^#' secrets/.env | xargs)
   ```

3. Sanity check that Neural can read them:

   ```bash
   python - <<'PY'
from neural.auth.env import get_api_key_id
print("API key detected:", get_api_key_id()[:6] + "…")
PY
   ```

4. Call a real Kalshi endpoint:

   ```bash
   python examples/01_init_user.py
   ```

   You should see a JSON response containing your portfolio balance. Authentication errors mean the key ID / private key pair does not match.

## Step 3 – Pull live market data

Run this snippet to fetch a handful of open NFL markets. The helper returns a `pandas.DataFrame` we can inspect immediately.

```bash
python - <<'PY'
import pandas as pd
from neural.auth.http_client import KalshiHTTPClient

client = KalshiHTTPClient()
try:
    payload = client.get("/markets", params={"series_ticker": "KXNFLGAME", "status": "open", "limit": 5})
finally:
    client.close()

df = pd.DataFrame(payload.get("markets", []))
print(df[["ticker", "title", "yes_ask", "no_ask"]])
PY
```

Expected: a small table of tickers (e.g., `KXNFLGAME-…`) with YES/NO prices in cents. If the DataFrame is empty, Kalshi may not have active markets in that sport—switch `sports` or drop the filter to confirm connectivity.

## Step 4 – Collect historical trades for backtesting

Use the historical data source to pull recent trades and save them to CSV for analysis:

```bash
python examples/test_historical_data.py
```

Look for the `✅ SUCCESS` line and the generated `test_historical_trades.csv`. These trades feed directly into the backtester.

## Step 5 – Dry-run a strategy

The mean-reversion example wires data collection, strategy logic, and the order manager together. It runs in `dry_run` mode so no orders hit Kalshi.

```bash
python examples/05_mean_reversion_strategy.py
```

You should see a per-game summary along with simulated signals and portfolio metrics. If no signals appear, markets might not meet the divergence threshold—adjust the parameters at the top of the script and rerun.

## Step 6 – Run the end-to-end quickstart

```bash
python examples/build_first_bot.py
```

This script fetches live markets, applies a toy signal, and routes simulated orders through `PaperTradingClient`. Use it as a template before wiring in your own strategy.

## Step 7 – Move into paper or live trading

1. Swap `TradingClient` in for live trading (credentials required).
2. Keep `PaperTradingClient` for rehearsals and backtesting comparisons.
3. Use `OrderManager` to keep strategy logic independent from the execution target.

## Step 8 – Run tests

```bash
pytest -q
```

- Always run without credentials first; unit tests will pass.
- Export your `.env` and rerun to trigger integration tests that hit Kalshi.
- Investigate any failing integration tests before trading live.

## Next steps

- **Overview of the architecture:** `architecture/start-here`
- **End-to-end quickstart:** `workflows/build-first-bot`
- **Deep dive into data collection:** `data-collection/overview`
- **Build your own strategy:** `analysis/strategy-foundations`
- **Progression checklist:** `workflows/promotion-checklist`

Come back to this guide whenever you need the essential commands to bootstrap a new machine.
