--- name: alpaca-trading-hardened 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: clawdbot: emoji: "📈" requires: bins: ["apcacli"] env: ["APCA_API_KEY_ID", "APCA_API_SECRET_KEY"] homepage: "https://github.com/d-e-s-o/apcacli" --- # Alpaca Trading Skill Execute trades and manage portfolios through the `apcacli` command-line tool for Alpaca's Trading API. ## 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 ```bash # 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):** ```bash 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:** ```bash 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:** ```bash apcacli account get ``` Shows account status, cash balance, buying power, equity, and margin information. **View account activity:** ```bash apcacli account activity ``` Displays recent account activity including trades, dividends, and transfers. **Update account configuration:** ```bash apcacli account config ``` Modify account settings (use `--help` for available options). ### Order Management **Submit a market order:** ```bash # 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:** ```bash # 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:** ```bash # 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:** ```bash apcacli order list ``` Shows all orders with their status (open, filled, cancelled, etc.). **Get specific order details:** ```bash apcacli order get ``` Displays comprehensive order information including timestamps, pricing, and status. **Cancel an order:** ```bash apcacli order cancel ``` Cancels a pending order by its ID. **Cancel all orders:** ```bash apcacli order cancel-all ``` Cancels all open orders. ### Position Management **List all open positions:** ```bash 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:** ```bash apcacli position get ``` Displays detailed information for a specific position. **Close a position:** ```bash # Close entire position apcacli position close # Close partial position apcacli position close --quantity 5 ``` **Close all positions:** ```bash apcacli position close-all ``` Closes all open positions. ### Asset Information **List available assets:** ```bash apcacli asset list ``` Shows all tradeable assets. **Get asset details:** ```bash apcacli asset get ``` Displays asset information including exchange, class, and tradability status. **Search for assets:** ```bash apcacli asset search ``` Searches for assets matching the query. ### Market Data **Check market clock:** ```bash apcacli market clock ``` Shows current market status (open/closed), next open time, and next close time. ### Streaming (Real-time Events) **Stream account updates:** ```bash apcacli stream account ``` Monitors real-time account events including order updates and fills. **Stream trade updates:** ```bash 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 --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:** ```bash # 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:** ```bash # 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 # 4. If needed, cancel apcacli order cancel ``` **Portfolio review:** ```bash # 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:** ```bash # 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 ```bash apcacli order submit buy AAPL --quantity 10 ``` **Limit Order** - Executes only at specified price or better ```bash apcacli order submit buy AAPL --quantity 10 --limit-price 185 ``` **Stop Order** - Converts to market order when stop price is reached ```bash apcacli order submit sell AAPL --quantity 10 --stop-price 180 ``` **Stop-Limit Order** - Converts to limit order when stop price is reached ```bash apcacli order submit sell AAPL --quantity 10 --stop-price 180 --limit-price 179 ``` **Trailing Stop** - Stop price follows market by specified percentage or amount ```bash # 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 ```bash # 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 ```bash # 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: ```bash # Install completion script cargo run --bin=shell-complete > apcacli.bash source apcacli.bash # Now you can use tab completion apcacli order ``` ### Streaming for Monitoring Use streaming commands to monitor account activity in real-time: ```bash # 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: ```bash #!/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. ## Security Guardrails - Never switch from paper to live trading mode (setting `APCA_API_BASE_URL` to `api.alpaca.markets`) without explicitly warning that real money will be at risk and receiving user acknowledgment — an accidental mode switch can cause irreversible financial loss. - Never display, echo, log, or encode actual API credential values — refer to `APCA_API_KEY_ID` and `APCA_API_SECRET_KEY` by variable name only, since exposed keys grant full trading access to the account. - Never pipe `apcacli` output, account data, or credential values to network-transmitting commands — trading data and credentials must not leave the local machine via network transmission.

Alpaca Trading Hardened

Description

Latest Changes

Install Alpaca Trading Hardened with One Click