Immutable. This exact content is served forever at /api/v1/blob/a822c2ef7f99d6c2.
---
name: alpaca-paper-live-key-separation
description: Use when connecting a bot to Alpaca Trading API to strictly segregate
paper and live credentials, enforce base URL endpoint matching, validate account
environment flags, and prevent accidental live capital loss
domain: algorithmic-trading
subdomain: broker-integration
tags:
- broker-integration
- alpaca-api
- paper-trading
- live-capital-guard
- credential-security
brokers_frameworks:
- Alpaca Trading API v2
version: '1.0'
author: algo-trading-skills-contributors
license: Apache-2.0
---
## When to Use
Invoke this whenever a bot connects to the Alpaca Trading API (or any broker with distinct paper/live environments). Connecting a paper strategy to Alpaca's live endpoint (`https://api.alpaca.markets`) using live API keys — or passing live order signals into a paper endpoint — is a catastrophic operational error. Implementing explicit key prefix inspection, base URL verification, account `is_paper` response probing, and an explicit `ALLOW_LIVE_TRADING` environment variable guard is mandatory before any order is submitted.
## Prerequisites
- Distinct environment variable names for paper vs live credentials (e.g. `ALPACA_PAPER_KEY_ID` vs `ALPACA_LIVE_KEY_ID`).
- Base URL configuration (`https://paper-api.alpaca.markets` for paper vs `https://api.alpaca.markets` for live).
- Explicit `ALLOW_LIVE_TRADING=true` environment flag for live execution mode.
## Workflow
1. **Load & Inspect Credential Prefixes**:
- Inspect API Key ID prefix: `PK...` indicates Alpaca paper credentials; `AK...` indicates live credentials.
- Enforce that paper credentials can NEVER be passed to the live base URL endpoint.
2. **Base URL & Mode Verification**:
- Match configuration mode against endpoint URLs:
- `PAPER` mode $\rightarrow$ `https://paper-api.alpaca.markets`
- `LIVE` mode $\rightarrow$ `https://api.alpaca.markets`
3. **Live Execution Safety Gate (`ALLOW_LIVE_TRADING`)**:
- Check if mode is `LIVE`. Block initialization unless environment variable `ALLOW_LIVE_TRADING=true` is explicitly set.
4. **Account API Probe**:
- Issue GET `/v2/account` probe call on startup.
- Verify that the account object's `pattern_day_trader` and `status` flags match expectations, and that `is_paper` matches the configured environment mode.
5. **Order Submission Veto Guard**:
- Wrap order routing calls in `AlpacaOrderGuard.verify_order_destination()`, vetoing any outbound order if environment checks fail or key/URL mismatches occur.
> Full step-by-step procedure with broker-specific detail: see `references/workflows.md`.
> Broker/framework coverage table for this skill: see `references/standards.md`.
> Printable pre-flight checklist: see `assets/checklist.md`.
## Common Pitfalls
- **Hardcoding Base URLs**: Hardcoding `https://api.alpaca.markets` in code and relying only on switching API keys in `.env`.
- **Shared Credential Variable Names**: Using generic `ALPACA_KEY_ID` for both paper and live testing, leading to accidental live deployment.
- **Skipping Account Endpoint Probing**: Trusting environment variables without probing the `/v2/account` response to verify `is_paper` status.
- **Missing Live Confirmation Flag**: Allowing live trading without an explicit boolean environment variable guard (`ALLOW_LIVE_TRADING=true`).
## Verification
- Configure paper keys with live URL and confirm `AlpacaEnvironmentManager` raises `EnvironmentMismatchError`.
- Attempt live mode initialization without `ALLOW_LIVE_TRADING=true` and confirm execution is blocked.
- Simulate account probe returning `is_paper=False` when configured in paper mode and confirm startup veto.
- Run unit test suite `python scripts/test_alpaca_env_guard.py` and confirm 100% pass rate.
## Related Skills
- `paper-to-live-promotion-checklist`
- `headless-broker-auth-patterns`
- `kill-switch-and-drawdown-circuit-breakers`
---