🐋 WhaleShadow Setup

Guided

Welcome

This wizard walks you through everything WhaleShadow needs to trade safely:

  1. Pick a broker with native multi-leg spread support.
  2. Plug in Unusual Whales for signals.
  3. Enable the OpenRouter LLM advisor (optional, recommended).
  4. Tune risk & exit policy to your account size.
  5. Verify paper-mode plumbing and kill-switch behavior.
  6. Export a ready-to-use .env.
Ground rules: WhaleShadow only submits defined-risk vertical debit spreads. Never a naked call or put. The emergency kill button on every page flattens every position through your broker's atomic close-all path.

1 · Broker

Choose the broker that will execute your spreads. All three support native multi-leg orders.

Get sandbox creds at https://developer.tradier.com/. Live creds require a funded Tradier Brokerage account with options approval.

Paper-mode uses TastyTrade's test environment (is_test=True in the SDK).

Alpaca requires Options Trading Level 3+ for multi-leg. WhaleShadow never falls back to manual legging — if your account can't submit mleg, the engine will trip the kill switch rather than risk a naked leg.

2 · Signals (Unusual Whales)

Primary signal feed. Paid subscription required (unusualwhales.com).

Universe is agnostic — start with the default broad set, trim or expand as your thesis evolves.

3 · LLM Advisor (optional)

Final gate after deterministic checks. Any OpenRouter-compatible model works — use a cheap one.

The advisor re-reads the whale context through the playbook and returns a JSON {decision, size_multiplier, confidence}. If the call fails, the engine fails closed — safer than submitting blindly.

4 · Risk & Exit Policy

The defaults implement the playbook. Tighten if you're new or under-capitalized.

If equity falls this many dollars below the first-tick snapshot on any given day, the kill switch trips and every position flattens. Set to 0 to disable.

Exit policy (principle: catch the wave, don't ride to zero)

Hard stop          -40%  of debit paid
Scale-out trigger  +50%  of debit paid   (close half, let runners run)
Trailing armed at  +30%  of debit paid
Trailing drawdown  30pp  from peak
Hard target        +120% of debit paid
Max hold           72 h
Min DTE to hold    2 days

These are compiled in via Settings. Override through env vars only if you understand the trade-off.

5 · Control Plane

The FastAPI control plane exposes /status, /tracked, and the emergency /control/kill endpoint.

Emergency kill test: once WhaleShadow is running, verify with 
curl -X POST -H "X-API-Token: $WS_API_TOKEN" \
  http://$WS_API_HOST:$WS_API_PORT/control/kill
It should cancel every order and flatten every position.

6 · Pre-flight Checklist

Make sure each of these is true before you go live.

7 · Your env vars

Pick a destination. WhaleShadow reads the same variables whether you deploy locally, on Railway, on Render, or in Docker.

  1. Open your Railway project → Variables tab → Raw Editor.
  2. Paste the block below.
  3. Ensure the service's Start Command is python -m whaleshadow (default from railway.json).
  4. Redeploy. Railway will route $PORT automatically.
  5. Visit https://<your-service>.up.railway.app/health — should return {"ok": true}.

      

        Do not set PORT or WS_API_HOST yourself — Railway supplies PORT, and the Dockerfile pins the host to 0.0.0.0.
      

      

        
      

    


    

    

    

      After deploy: open /status on your deploy URL. If mode: setup appears, your broker creds didn't parse — edit and redeploy. Once you see live equity, run five paper sessions and review trade_log.jsonl before flipping WS_PAPER_MODE=false.
    


    

      Emergency kill from anywhere:
      
curl -X POST -H "X-API-Token: $WS_API_TOKEN" \
  https://<your-railway-url>/control/kill