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
• INLINECODE1 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. 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)
• INLINECODE3 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)

CODEBLOCK0

Alternative: System Python

CODEBLOCK1

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

CODEBLOCK2

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:

CODEBLOCK3

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

CODEBLOCK4

Interactive setup wizard that guides you through:

1. 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

CODEBLOCK5

Shows:

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

Check Market Status

CODEBLOCK6

Shows:

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

View Market Calendar

CODEBLOCK7

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

View Portfolio History

CODEBLOCK8

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

CODEBLOCK9

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

CODEBLOCK10

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

CODEBLOCK11

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

CODEBLOCK12

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

Cancel Orders

CODEBLOCK13

Position Management

Close Positions

CODEBLOCK14

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

Example Workflows

First Time Setup

CODEBLOCK15

Trading Workflow

CODEBLOCK16

Portfolio Analysis

CODEBLOCK17

Risk Management

CODEBLOCK18

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. 1. Run alpaca init - Displays clear registration steps
2. Use browser automation to complete steps 1-3:

1. 3. Run alpaca auth - Save the extracted keys to shell config

Example Agent Flow

CODEBLOCK19

Key Points

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

Agent Usage

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

1. 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 INLINECODE29
• Check order status with INLINECODE30
• Review portfolio performance with INLINECODE31
• 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:
CODEBLOCK20

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

Then update the script shebang to use Homebrew Python:
CODEBLOCK22

Missing pytz

If you see:
CODEBLOCK23

Solution:
CODEBLOCK24

Command Not Found

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

Or add to PATH in your shell config:
CODEBLOCK26

Files

• - CLI Tool: INLINECODE36
• 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. 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 INLINECODE43

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