THESIS Start
Docs · Connecting an Alpaca API key
Brokers

Connecting an Alpaca API key

Step-by-step for generating Alpaca paper and live API keys and connecting them to Thesis. Includes troubleshooting for the common error cases.

Thesis runs trades on your Alpaca account, not ours. You generate API keys in Alpaca’s dashboard, paste them into Thesis, and we encrypt + use them server-side to place orders.

This page walks through both paper and live key setup.

  1. Sign in to app.alpaca.markets.

  2. Top-right toggle: switch to Paper. The dashboard background turns yellow.

  3. Left nav: API Keys. Click Generate New Key.

  4. You’ll get two values:

    • Key ID (looks like PKABC123...)
    • Secret Key (longer string)

    Copy both immediately. Alpaca only shows the secret once.

  5. In Thesis: Settings → Connect Alpaca.

  6. Paste Key ID and Secret Key. Confirm Paper Mode is selected.

  7. Click Validate & save.

Thesis checks the keys with Alpaca to confirm they work and that you’re in paper mode. If anything’s off you’ll see the error inline — most often it’s a stray space at the end of a pasted key, or the secret was pasted into the Key ID field.

Live keys

Read Paper vs. live mode before doing this. Live trading uses real money. Losses are real.

  1. In Alpaca’s dashboard, switch off Paper — toggle to Live.
  2. Left nav: API Keys → Generate New Key.
  3. Copy the Key ID and Secret Key.
  4. In Thesis: Settings → Connect Alpaca → Add new connection.
  5. Paste the keys. Uncheck Paper Mode so Thesis knows to treat this as live.
  6. Validate & save.

Thesis allows multiple Alpaca connections per user. The active one (toggleable in Settings) is where new trades route. Closed-trade history is scoped to the connection that opened it — switching connections doesn’t blend a paper P/L with a live P/L.

What changes the moment you flip to a live connection

  • Trades route to your real Alpaca live account.
  • Thesis starts pulling real broker fees from Alpaca every few minutes and writing them to your trade ledger. The (modeled) label on crypto fees drops.
  • PDT rules apply (if account < $25k).
  • Margin / shorting rules are real broker rules, not simulated.

Key permissions

Alpaca API keys have full account control by default — including the ability to:

  • Place market and limit orders
  • Read positions, balances, and account state
  • Cancel pending orders

There’s no “trade-only” scope at Alpaca. If you want to limit what Thesis can do, the best approach is to fund your Alpaca account only with what you’re willing to risk, and rotate keys periodically.

Thesis does not request withdrawal permissions and doesn’t use them — withdrawals require a separate signed authorization flow on Alpaca’s side that we never trigger.

How your keys are stored

  • Server-side only, encrypted with industry-standard envelope encryption (AES-256-GCM).
  • The master encryption key is held in a managed secrets vault, isolated from the app code.
  • Per-user data-encryption keys are derived per session and discarded after each request.
  • We never log keys, even partially.

If you revoke a key in Alpaca’s dashboard, Thesis loses the ability to place trades on it instantly. Your data in Thesis stays intact; you’d just connect a new key to resume.

Troubleshooting

”Invalid Alpaca credentials”

  • Re-copy the keys from Alpaca’s dashboard. The most common cause is a trailing space or copy-paste corruption.
  • Confirm you’re pasting paper keys into a paper-mode connection (and live into live). Alpaca uses different key prefixes (PK... vs AK...).

”Paper mode mismatch”

  • The keys you entered are live keys but you set Paper mode (or vice versa). Re-generate the appropriate keys in the matching Alpaca environment.

”Account inactive”

  • Alpaca has restricted the account — usually a verification issue on Alpaca’s side. Resolve in their dashboard first; Thesis will pick up the change on the next validation.

”No trades firing after connection”

  • Confirm Trading paused is OFF (Settings → Trading paused).
  • Confirm a trading mode is selected (Autopilot / Copilot / Manual). Manual mode never auto-trades.
  • Confirm market hours — equity patterns only fire 9:30am–4:00pm ET on weekdays. Crypto runs 24/7.
  • Check Pattern Feed. If patterns are firing but not converting to trades, look at the Skipped tab — the system records why each one was rejected (AI confidence too low, news conflict, position cap, etc.).

If you’re still stuck, email support@thesistrade.app with your email + approximate time of the issue.