Alpaca Trading (Python CLI) - OpenClaw Agent Skill

Trade stocks and crypto programmatically via Alpaca's API using a Python-based CLI tool.

⚠️ Security & Setup Requirements

IMPORTANT - READ BEFORE USE:

This skill stores API keys as environment variables in your shell config file.

What happens during setup:

• alpaca init displays registration steps for agent automation
• alpaca auth saves API keys to shell startup files (~/.zshrc, ~/.bashrc, or ~/.profile)
• This creates persistent environment variables accessible to all shell sessions

Security considerations:

• ✅ API keys are stored as environment variables (standard practice)
• ✅ Paper trading by default (virtual money, no risk)
• ⚠️ Keys in shell config are accessible to any process in that shell
• ⚠️ Setup modifies user's shell configuration files

Recommended practices:

1. Get user consent - Explain that setup will modify shell config
2. Use paper trading keys - Test with virtual money first ($100k virtual)
3. Least privilege - Use API keys with minimal required permissions
4. Monitor activity - Check your Alpaca account regularly

For agents:

• Get explicit user permission before running alpaca auth (saves keys to shell config)
• alpaca init is safe to run - it only displays instructions
• Use browser automation to complete registration steps automatically
• After obtaining keys via browser, call alpaca auth to save them

Links:

• ClawHub: https://clawhub.ai/skills/alpaca-py-cli
• GitHub: https://github.com/zijunl/alpaca-py-cli
• Alpaca Markets: https://alpaca.markets

Alpaca Trading (Python CLI)

Trade stocks and crypto programmatically via Alpaca's API using a Python-based CLI tool.

Links:

• ClawHub: https://clawhub.ai/skills/alpaca-py-cli
• GitHub: https://github.com/zijunl/alpaca-py-cli
• Alpaca Markets: https://alpaca.markets

Overview

Manage your Alpaca Markets trading account using the alpaca CLI tool and Python SDK. Supports both paper trading (simulated) and live trading.

Installation

Recommended: Homebrew Python (avoids urllib3/LibreSSL warnings)

# Install Homebrew Python 3.11+
brew install python@3.11

# Install alpaca-py
/opt/homebrew/bin/pip3.11 install alpaca-py pytz

Alternative: System Python

pip3 install alpaca-py pytz

Note: System Python may show urllib3 warnings on macOS due to LibreSSL compatibility. Use Homebrew Python for a cleaner experience.

Configuration

Quick Setup with CLI

alpaca auth

This will interactively prompt you for:

• API Key
• Secret Key (hidden input)
• Trading mode (Paper or Live)

The command automatically saves your credentials to your shell config file (~/.zshrc, ~/.bashrc, or ~/.profile).

Manual Setup

Alternatively, set these in your shell profile manually:

export ALPACA_API_KEY="your_api_key"
export ALPACA_SECRET_KEY="your_secret_key"
export ALPACA_PAPER="true"  # Use "false" for live trading

Get your API keys from https://alpaca.markets (Dashboard → API Keys)

Paper Trading (recommended for testing):

• Use paper trading API keys
• Virtual $100,000 starting balance
• No real money at risk

Live Trading (real money):

• Use live trading API keys
• Real money, real risk
• Test thoroughly with paper trading first

CLI Commands

Setup & Configuration

Configure Credentials

alpaca auth

Interactive setup wizard that guides you through:

1. Enter API Key
2. Enter Secret Key (hidden)
3. Choose trading mode (Paper/Live)
4. Automatically saves to shell config

Account & Market Info

Check Account

alpaca account

Shows:

• Account number and status
• Portfolio value, cash, buying power
• P&L (equity, last equity)
• Trading restrictions (pattern day trader, blocks)

Check Market Status

alpaca clock

Shows:

• Market status (🟢 OPEN or 🔴 CLOSED)
• Current time
• Next open/close times

View Market Calendar

# Show next 30 trading days (default)
alpaca calendar

# Show next 7 trading days
alpaca calendar --days 7

Shows trading days with open/close times (Eastern Time).

View Portfolio History

# Default: 1 month, daily bars
alpaca history

# Last week
alpaca history --period 1W

# Last 3 months with hourly bars
alpaca history --period 3M --timeframe 1H

Periods: 1D, 1W, 1M, 3M, 1Y, all
Timeframes: 1Min, 5Min, 15Min, 1H, 1D

Shows:

• Start and end equity
• Total change ($ and %)
• Recent history (last 10 data points)

Portfolio Management

View Positions

alpaca positions

Shows all current holdings with:

• Symbol, quantity, current price
• Entry price and market value
• Unrealized P&L ($ and %)
• Total portfolio value and P&L

Get Stock Quotes

# Single symbol
alpaca quote AAPL

# Multiple symbols
alpaca quote AAPL,TSLA,MSFT

Shows:

• Bid and ask prices
• Mid price and spread
• Quote timestamp

Note: Quotes may show incomplete data when market is closed. Best used during market hours (9:30 AM - 4:00 PM ET).

Order Management

View Orders

# Show open orders (default)
alpaca orders

# Show all recent orders
alpaca orders --status all

# Show last 20 closed orders
alpaca orders --status closed --limit 20

Shows:

• Order status with emoji indicators (⏳ pending, ✓ filled, ✗ canceled)
• Symbol, side (BUY/SELL), quantity
• Order ID and creation time
• Fill price (if filled)

Place Orders

# Buy shares
alpaca buy AAPL 10

# Sell shares
alpaca sell AAPL 5

Places a market order that executes at market price when market is open.

Cancel Orders

# Cancel specific order
alpaca cancel <order_id>

# Cancel all open orders
alpaca cancel-all

Position Management

Close Positions

# Close specific position
alpaca close AAPL

# Close all positions (requires confirmation)
alpaca close-all

Note: close-all will prompt for confirmation before closing all positions.

Example Workflows

First Time Setup

# Configure credentials
alpaca auth

# Check account
alpaca account

# Check if market is open
alpaca clock

Trading Workflow

# Check current price
alpaca quote TSLA

# Check account balance
alpaca account

# Buy some shares
alpaca buy TSLA 5

# Check pending orders
alpaca orders

# View positions (after order fills)
alpaca positions

# Get updated quote
alpaca quote TSLA

# Sell some shares
alpaca sell TSLA 2

# Check order history
alpaca orders --status all

Portfolio Analysis

# View current positions
alpaca positions

# View portfolio history
alpaca history --period 1M

# Check market calendar
alpaca calendar --days 7

Risk Management

# Check all open orders
alpaca orders

# Cancel specific order
alpaca cancel <order_id>

# Cancel all orders
alpaca cancel-all

# Close specific position
alpaca close AAPL

# Close all positions
alpaca close-all

Automated Setup for Agents

When a user wants to start trading but hasn't configured Alpaca yet, agents can automate the entire setup process using browser automation.

Setup Workflow

1. Run alpaca init - Displays clear registration steps
2. Use browser automation to complete steps 1-3:
   • Navigate to https://alpaca.markets
   • Click "Sign Up" and fill registration form
   • Verify email (can use email skill to automate)
   • Log in and navigate to Dashboard → API Keys → Paper Trading
   • Generate new API key pair
   • Extract both keys (API Key and Secret Key)
3. Run alpaca auth - Save the extracted keys to shell config

Example Agent Flow

User: "I want to start trading stocks"

Agent: 
1. Runs: alpaca init (gets registration steps)
2. Uses browser skill to:
   - Open https://alpaca.markets
   - Fill registration form with user info
   - Verify email automatically
   - Navigate to API Keys page
   - Generate and extract keys
3. Runs: alpaca auth (with extracted keys)
4. Confirms: "✓ Setup complete! You have $100k in paper money."

Key Points

• alpaca init is non-interactive - just displays steps
• Agents should use browser automation to follow the steps
• alpaca auth requires user consent (modifies shell config)
• After setup, verify with alpaca clock or alpaca account

Agent Usage

When the user asks about their portfolio or wants to trade:

1. Configure credentials: Run alpaca auth for first-time setup
2. Check market status: Run alpaca clock to see if market is open
3. Check account: Run alpaca account to see current balance and buying power
4. Get positions: Run alpaca positions to list current holdings
5. View orders: Run alpaca orders to see pending/recent orders
6. Get quotes: Run alpaca quote <symbols> to check current prices
7. Place orders: Run alpaca buy/sell to execute trades
8. Manage risk: Run alpaca cancel/close commands as needed

Safety Tips

• Always test with paper trading first (ALPACA_PAPER=true)
• Use alpaca auth to safely configure credentials (secret key is hidden)
• Check alpaca clock before trading to see if market is open
• Check quotes before placing orders to understand current prices
• Check account.buying_power before placing orders
• Use TimeInForce.DAY to auto-cancel unfilled orders at market close
• Monitor positions regularly with alpaca positions
• Check order status with alpaca orders
• Review portfolio performance with alpaca history
• Use alpaca cancel-all to quickly cancel all pending orders
• Use alpaca close-all with caution (requires confirmation)
• Set stop-loss orders for risk management
• Never share your API keys publicly

Market Hours

US stock market hours (Eastern Time):

• Regular hours: 9:30 AM - 4:00 PM ET
• Pre-market: 4:00 AM - 9:30 AM ET
• After-hours: 4:00 PM - 8:00 PM ET

Orders placed outside market hours will be queued and executed when market opens.

Quotes may show incomplete or stale data when market is closed.

Use alpaca clock to check current market status.

Troubleshooting

urllib3 Warning (LibreSSL)

If you see:

NotOpenSSLWarning: urllib3 v2 only supports OpenSSL 1.1.1+, currently using LibreSSL

Solution: Install and use Homebrew Python 3.11+ which uses OpenSSL:

brew install python@3.11
/opt/homebrew/bin/pip3.11 install alpaca-py pytz

Then update the script shebang to use Homebrew Python:

sed -i '' '1s|#!/usr/bin/env python3|#!/opt/homebrew/bin/python3.11|' ~/.openclaw/workspace/skills/alpaca-py-cli/scripts/alpaca

Missing pytz

If you see:

ModuleNotFoundError: No module named 'pytz'

Solution:

pip3 install pytz
# or
/opt/homebrew/bin/pip3.11 install pytz

Command Not Found

If alpaca command is not found, use the full path:

~/.openclaw/workspace/skills/alpaca-py-cli/scripts/alpaca

Or add to PATH in your shell config:

export PATH="$HOME/.openclaw/workspace/skills/alpaca-py-cli/scripts:$PATH"

Files

• CLI Tool: ~/.openclaw/workspace/skills/alpaca-py-cli/scripts/alpaca
• Config: Environment variables in ~/.zshrc (or ~/.bashrc, ~/.profile)

Official Documentation

• Python SDK: https://alpaca.markets/docs/python-sdk/
• API Reference: https://docs.alpaca.markets/reference/
• Trading API: https://docs.alpaca.markets/docs/trading-api
• Market Data API: https://docs.alpaca.markets/docs/market-data

Initialization (For Agents)

See the "Automated Setup for Agents" section above for the complete workflow.

Quick summary:

1. Run alpaca init to see registration steps
2. Use browser automation to complete registration and extract API keys
3. Run alpaca auth to save keys (with user consent)
4. Verify with alpaca clock or alpaca account

The new alpaca init command is non-interactive and agent-friendly - it simply displays clear steps that an agent can follow using browser automation.