alpaca-trading

What this skill does

# 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)
```bash
brew install rustup
rustup-init -y
source "$HOME/.cargo/env"
cargo install apcacli
```

### Linux
```bash
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](https://rustup.rs)
2. Open a new terminal, then: `cargo install apcacli`

### Environment Variables
```bash
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

```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 <options>
```
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 <ORDER_ID>
```
Displays comprehensive order information including timestamps, pricing, and status.

**Cancel an order:**
```bash
apcacli order cancel <ORDER_ID>
```
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 <SYMBOL>
```
Displays detailed information for a specific position.

**Close a position:**
```bash
# Close entire position
apcacli position close <SYMBOL>

# Close partial position
apcacli position close <SYMBOL> --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 <SYMBOL>
```
Displays asset information including exchange, class, and tradability status.

**Search for assets:**
```bash
apcacli asset search <QUERY>
```
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 <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** - Monito