alpaca-trading

name	alpaca-trading
description	Execute trades, analyze markets, and manage portfolios using apcacli command-line tool for Alpaca's Trading API. Use when the user wants to trade stocks, ETFs, options, crypto, check market data, view positions, manage orders, or analyze their portfolio. Also use when they mention "buy," "sell," "trade," "market data," "stock price," "portfolio," "account balance," or "alpaca trading."
metadata	{"openclaw":{"emoji":"📈","requires":{"bins":["apcacli"],"env":["APCA_API_KEY_ID","APCA_API_SECRET_KEY"]},"homepage":"https://github.com/d-e-s-o/apcacli","repository":"https://github.com/lacymorrow/openclaw-alpaca-trading-skill","install":[{"id":"brew-rustup","kind":"brew","formula":"rustup","bins":["rustup"],"label":"Install Rust toolchain (Homebrew)"}]}}

Alpaca Trading Skill

Execute trades and manage portfolios through the apcacli command-line tool for Alpaca's Trading API.

Installation

apcacli is a Rust CLI. Install it cross-platform:

macOS (Homebrew)

brew install rustup
rustup-init -y
source "$HOME/.cargo/env"
cargo install apcacli

Linux

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"
cargo install apcacli

Windows

1. Download and run rustup-init.exe
2. Open a new terminal, then: cargo install apcacli

Environment Variables

export APCA_API_KEY_ID='your-key-id'
export APCA_API_SECRET_KEY='your-secret-key'
# For live trading (default is paper):
# export APCA_API_BASE_URL='https://api.alpaca.markets'

Overview

You are an expert in using apcacli for command-line stock trading. Your goal is to help users trade stocks, ETFs, options, and crypto efficiently through Alpaca's API while emphasizing safety and best practices.

How to Use This Skill

When helping users with trading tasks:

1. Safety First: Always recommend paper trading for new users or when testing
2. Verify Commands: Show the exact command before executing trades
3. Check Prerequisites: Confirm market hours, account balance, and valid symbols
4. Explain Order Types: Help users choose the right order type for their needs
5. Risk Management: Suggest stop losses and position sizing

---

What This Skill Does

apcacli is a Rust-based CLI for interacting with Alpaca's trading platform. It provides:

• Trading: Submit, modify, and cancel orders for stocks, ETFs, options, and crypto
• Portfolio Management: View positions, P/L, and account information
• Market Data: Access asset information and market clock status
• Account Activity: Track trading history and account changes
• Real-time Streaming: Monitor account and trade events

When to Use This Skill

Use this skill when the user wants to:

• Execute trades (buy/sell stocks, ETFs, options, crypto)
• Check portfolio positions and performance
• View or manage orders (open, filled, cancelled)
• Get account balance and buying power
• Access market data and asset information
• Monitor account activity and events
• Check if the market is open
• Set up stop losses or trailing stops
• Automate trading workflows with scripts

Common trigger phrases:

• "Buy 10 shares of AAPL"
• "Show my open positions"
• "What's my account balance?"
• "List all my orders"
• "Cancel order [ID]"
• "Is the market open?"
• "Show my portfolio performance"
• "Set a stop loss on my position"
• "Close all my positions"

When NOT to use this skill:

• User wants GUI-based trading (direct them to web interface)
• User asks for financial advice (you provide tools, not recommendations)
• User wants to trade instruments not supported by Alpaca
• User doesn't have apcacli installed (help them install it first)

Installation & Setup

Install apcacli

# Using Cargo (Rust package manager)
cargo install apcacli

# Verify installation
apcacli --help

Requirements:

• Rust 1.71 or newer
• Alpaca account (paper or live trading)
• Alpaca API credentials

Configure Environment Variables

For Paper Trading (Recommended for testing):

export APCA_API_KEY_ID='your_paper_key_id'
export APCA_API_SECRET_KEY='your_paper_secret_key'
# Paper trading is the default, no need to set APCA_API_BASE_URL

For Live Trading:

export APCA_API_BASE_URL='https://api.alpaca.markets'
export APCA_API_KEY_ID='your_live_key_id'
export APCA_API_SECRET_KEY='your_live_secret_key'

Get API Credentials:

1. Sign up at https://alpaca.markets/
2. Navigate to your dashboard
3. Generate API keys (paper or live)
4. Export the environment variables

Core Commands

Account Information

View account details:

apcacli account get

Shows account status, cash balance, buying power, equity, and margin information.

View account activity:

apcacli account activity

Displays recent account activity including trades, dividends, and transfers.

Update account configuration:

apcacli account config <options>

Modify account settings (use --help for available options).

Order Management

Submit a market order:

# Buy with dollar amount
apcacli order submit buy AAPL --value 1000

# Buy specific quantity
apcacli order submit buy AAPL --quantity 10

# Sell shares
apcacli order submit sell TSLA --quantity 5

Submit a limit order:

# Buy at specific price
apcacli order submit buy MSFT --quantity 10 --limit-price 420

# Sell at specific price
apcacli order submit sell NVDA --quantity 20 --limit-price 850

Submit advanced orders:

# Stop order
apcacli order submit sell AAPL --quantity 10 --stop-price 180

# Stop-limit order
apcacli order submit sell TSLA --quantity 5 --stop-price 800 --limit-price 795

# Trailing stop order (percentage)
apcacli order submit sell NVDA --quantity 10 --trail-percent 5

List all orders:

apcacli order list

Shows all orders with their status (open, filled, cancelled, etc.).

Get specific order details:

apcacli order get <ORDER_ID>

Displays comprehensive order information including timestamps, pricing, and status.

Cancel an order:

apcacli order cancel <ORDER_ID>

Cancels a pending order by its ID.

Cancel all orders:

apcacli order cancel-all

Cancels all open orders.

Position Management

List all open positions:

apcacli position list

Shows all open positions with:

• Quantity and entry price
• Current market value
• Daily P/L (with percentage)
• Total P/L (with percentage)
• Color-coded profit/loss

Get specific position:

apcacli position get <SYMBOL>

Displays detailed information for a specific position.

Close a position:

# Close entire position
apcacli position close <SYMBOL>

# Close partial position
apcacli position close <SYMBOL> --quantity 5

Close all positions:

apcacli position close-all

Closes all open positions.

Asset Information

List available assets:

apcacli asset list

Shows all tradeable assets.

Get asset details:

apcacli asset get <SYMBOL>

Displays asset information including exchange, class, and tradability status.

Search for assets:

apcacli asset search <QUERY>

Searches for assets matching the query.

Market Data

Check market clock:

apcacli market clock

Shows current market status (open/closed), next open time, and next close time.

Streaming (Real-time Events)

Stream account updates:

apcacli stream account

Monitors real-time account events including order updates and fills.

Stream trade updates:

apcacli stream trades

Monitors real-time trade events for your positions.

Best Practices

Safety & Risk Management

1. Start with Paper Trading - Always test strategies with paper trading first
2. Use Limit Orders - Avoid market orders in volatile conditions for better price control
3. Verify Symbols - Double-check ticker symbols before executing trades
4. Review Before Executing - Use apcacli order get to verify order details
5. Set Stop Losses - Protect positions with stop orders
6. Check Account Balance - Ensure sufficient buying power before trading
7. Monitor Positions - Regularly review P/L with apcacli position list

Effective Usage

1. Check help for any command - Use apcacli <command> --help for detailed options
2. Save order IDs - Store returned order IDs to track and manage orders later
3. Use environment variables - Keep credentials secure in environment variables, never hardcode
4. Verify market hours - Check apcacli market clock before placing orders
5. Review activity regularly - Monitor account activity for unexpected changes

Common Workflows

Simple stock purchase:

# 1. Check account balance
apcacli account get

# 2. Verify asset is tradeable
apcacli asset get AAPL

# 3. Check market is open
apcacli market clock

# 4. Submit market order
apcacli order submit buy AAPL --value 1000

# 5. Verify position
apcacli position list

Limit order with monitoring:

# 1. Submit limit order
apcacli order submit buy MSFT --quantity 10 --limit-price 420

# 2. Save the returned ORDER_ID
# 3. Check order status
apcacli order get <ORDER_ID>

# 4. If needed, cancel
apcacli order cancel <ORDER_ID>

Portfolio review:

# 1. View all positions
apcacli position list

# 2. Check account summary
apcacli account get

# 3. Review recent activity
apcacli account activity

Close position with stop loss:

# 1. Check current position
apcacli position get AAPL

# 2. Set trailing stop to protect profits
apcacli order submit sell AAPL --quantity 10 --trail-percent 5

# 3. Monitor the order
apcacli order list

Command Reference Quick Guide

Task	Command
View account	apcacli account get
Account activity	apcacli account activity
Buy stock (market)	apcacli order submit buy SYMBOL --value AMOUNT
Buy stock (limit)	apcacli order submit buy SYMBOL --quantity N --limit-price PRICE
Sell stock	apcacli order submit sell SYMBOL --quantity N
List all orders	apcacli order list
Get order details	apcacli order get ORDER_ID
Cancel order	apcacli order cancel ORDER_ID
Cancel all orders	apcacli order cancel-all
List positions	apcacli position list
Get position	apcacli position get SYMBOL
Close position	apcacli position close SYMBOL
Close all positions	apcacli position close-all
List assets	apcacli asset list
Get asset info	apcacli asset get SYMBOL
Check market status	apcacli market clock
Stream account events	apcacli stream account
Stream trades	apcacli stream trades

Order Types & Parameters

Basic Order Parameters

• --quantity N - Number of shares to trade
• --value AMOUNT - Dollar amount to invest (for market orders)
• --limit-price PRICE - Limit price for limit orders
• --stop-price PRICE - Stop price for stop orders
• --trail-percent N - Trailing stop percentage
• --trail-amount AMOUNT - Trailing stop dollar amount

Order Types

Market Order - Executes immediately at current market price

apcacli order submit buy AAPL --quantity 10

Limit Order - Executes only at specified price or better

apcacli order submit buy AAPL --quantity 10 --limit-price 185

Stop Order - Converts to market order when stop price is reached

apcacli order submit sell AAPL --quantity 10 --stop-price 180

Stop-Limit Order - Converts to limit order when stop price is reached

apcacli order submit sell AAPL --quantity 10 --stop-price 180 --limit-price 179

Trailing Stop - Stop price follows market by specified percentage or amount

# Percentage-based
apcacli order submit sell AAPL --quantity 10 --trail-percent 5

# Dollar-based
apcacli order submit sell AAPL --quantity 10 --trail-amount 10

Important Notes

Requirements

• apcacli binary must be installed - Install via cargo install apcacli
• Environment variables must be set - APCA_API_KEY_ID and APCA_API_SECRET_KEY are required
• Alpaca account - Active paper or live trading account
• Rust 1.71+ - Required for installation from source

Trading Limitations

• Paper vs Live: Default is paper trading; set APCA_API_BASE_URL for live trading
• Market hours: Most trades only execute during market hours (9:30 AM - 4:00 PM ET)
• Pattern Day Trading (PDT): Accounts under $25k have PDT restrictions
• Buying power: Limited by account equity and margin requirements
• Order restrictions: Some order types may not be available for all securities
• Crypto trading: May have different rules and trading hours

Data & Performance

• API rate limits: Alpaca has request limits to prevent abuse
• Real-time data: May require active data subscription
• Command output: Results formatted with color coding for easy reading
• Order IDs: Save returned order IDs for tracking and management
• Network dependency: Requires internet connection to Alpaca's API

Troubleshooting

Environment Variables Not Set

# Error: "Missing APCA_API_KEY_ID"
# Solution: Export required environment variables
export APCA_API_KEY_ID='your_key'
export APCA_API_SECRET_KEY='your_secret'

Command Not Found

# Error: "apcacli: command not found"
# Solution: Install apcacli
cargo install apcacli

# Verify installation
which apcacli

API Authentication Failed

• Verify API credentials are correct
• Check if using correct endpoint (paper vs live)
• Ensure API keys haven't been revoked
• Confirm account status is active

Order Rejected

• Verify market is open (for stocks)
• Check sufficient buying power
• Confirm symbol is valid and tradeable
• Review order parameters (price, quantity)
• Check for any account restrictions

Position Not Found

• Verify symbol is correct
• Ensure position is actually open
• Check if position was closed previously
• Confirm you're using the right account (paper vs live)

Advanced Features

Shell Completion

Generate shell completion for faster command entry:

# Install completion script
cargo run --bin=shell-complete > apcacli.bash
source apcacli.bash

# Now you can use tab completion
apcacli order <TAB>

Streaming for Monitoring

Use streaming commands to monitor account activity in real-time:

# Terminal 1: Monitor account events
apcacli stream account

# Terminal 2: Execute trades
apcacli order submit buy AAPL --value 1000
# Watch the fill notification appear in Terminal 1

Scripting & Automation

Combine apcacli with shell scripts for automated strategies:

#!/bin/bash
# Example: Daily portfolio check script

echo "=== Daily Portfolio Report ==="
echo ""
echo "Account Status:"
apcacli account get
echo ""
echo "Open Positions:"
apcacli position list
echo ""
echo "Recent Activity:"
apcacli account activity

Additional Resources

• apcacli Repository: https://github.com/d-e-s-o/apcacli
• Alpaca Documentation: https://docs.alpaca.markets/
• Alpaca API Reference: https://docs.alpaca.markets/reference/
• Paper Trading Dashboard: https://app.alpaca.markets/paper/dashboard/overview
• apca Crate (Underlying Library): https://github.com/d-e-s-o/apca

Safety Reminders

⚠️ IMPORTANT:

• Always start with PAPER TRADING to test without risk
• Review all order details before execution
• Never share your API credentials
• Use limit orders for better price control
• Set stop losses to manage risk
• Verify environment variables are set correctly (paper vs live)
• Double-check symbols and quantities
• Monitor positions regularly

Credits

apcacli created by d-e-s-o

Built on the apca Rust crate for Alpaca API interactions.