home / skills / openclaw / skills / alpaca

alpaca skill

safe

This skill helps you manage trades and monitor markets using Alpaca API, including quotes, orders, and portfolio data for paper or live trading.

npx playbooks add skill openclaw/skills --skill alpaca

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

4.5 KB

---
name: alpaca
description: Trade stocks and crypto via Alpaca API. Use for market data (quotes, bars, news), placing orders (market, limit, stop), checking positions, portfolio management, and account info. Supports both paper and live trading. Use when user asks about stock prices, wants to buy/sell securities, check portfolio, or manage trades.
---

# Alpaca Trading Skill

Trade stocks and crypto programmatically via Alpaca's API.

## Setup

Requires API credentials stored in environment or config:

```bash
# Set environment variables
export ALPACA_API_KEY="your-api-key"
export ALPACA_SECRET_KEY="your-secret-key"
export ALPACA_PAPER="true"  # "true" for paper, "false" for live
```

Or store in `~/.openclaw/credentials/alpaca.json`:

```json
{
  "apiKey": "your-api-key",
  "secretKey": "your-secret-key",
  "paper": true
}
```

## Quick Reference

### Get Quote
```bash
python3 scripts/alpaca_cli.py quote AAPL
python3 scripts/alpaca_cli.py quote AAPL,TSLA,NVDA
```

### Get Bars (Historical Data)
```bash
python3 scripts/alpaca_cli.py bars AAPL --timeframe 1Day --limit 10
python3 scripts/alpaca_cli.py bars AAPL --timeframe 1Hour --start 2026-02-01
```

### Check Account
```bash
python3 scripts/alpaca_cli.py account
```

### List Positions
```bash
python3 scripts/alpaca_cli.py positions
```

### Place Orders
```bash
# Market order
python3 scripts/alpaca_cli.py order buy AAPL 10

# Limit order
python3 scripts/alpaca_cli.py order buy AAPL 10 --limit 150.00

# Stop order
python3 scripts/alpaca_cli.py order sell TSLA 5 --stop 200.00

# Stop-limit order
python3 scripts/alpaca_cli.py order sell TSLA 5 --stop 200.00 --limit 195.00

# Skip price validation (use with caution)
python3 scripts/alpaca_cli.py order buy AAPL 10 --limit 999.00 --force
```

**Order Guardrails:**

1. **Symbol validation** — Rejects invalid/unknown tickers
2. **Buying power check** — Blocks orders exceeding available funds, shows max shares
3. **Duplicate detection** — Warns if you have open orders for same symbol/side
4. **Price validation** — Warns if limit price is worse than market
5. **Market hours check** — Detects pre-market, after-hours, and closed sessions
   - Pre-market (4:00 AM - 9:30 AM ET): Option to place pre-market order
   - After-hours (4:00 PM - 8:00 PM ET): Option to place after-hours order
   - Closed: Warns order will queue until market open
6. **Cost confirmation** — Shows total cost and requires confirmation

Use `--force` to skip all confirmation prompts (use with caution).

### List Orders
```bash
python3 scripts/alpaca_cli.py orders
python3 scripts/alpaca_cli.py orders --status open
python3 scripts/alpaca_cli.py orders --status closed --limit 20
```

### Cancel Order
```bash
python3 scripts/alpaca_cli.py cancel ORDER_ID
python3 scripts/alpaca_cli.py cancel all  # Cancel all open orders
```

### Get News
```bash
python3 scripts/alpaca_cli.py news AAPL
python3 scripts/alpaca_cli.py news AAPL,TSLA --limit 5
```

### Watchlist
```bash
python3 scripts/alpaca_cli.py watchlist list
python3 scripts/alpaca_cli.py watchlist create "Tech Stocks" AAPL,MSFT,GOOGL
python3 scripts/alpaca_cli.py watchlist add WATCHLIST_ID NVDA
python3 scripts/alpaca_cli.py watchlist delete WATCHLIST_ID
```

### Stream Live Data (Websocket)
```bash
# Stream trades (default)
python3 scripts/alpaca_cli.py stream AAPL

# Stream quotes
python3 scripts/alpaca_cli.py stream AAPL,TSLA --type quotes

# Stream bars (1-min)
python3 scripts/alpaca_cli.py stream NVDA --type bars

# Stream all data types
python3 scripts/alpaca_cli.py stream AAPL --type all
```

Press Ctrl+C to stop streaming.

### Price Alerts
```bash
# Add alert - notify when INTU drops below $399
python3 scripts/alpaca_cli.py alert add --symbol INTU --price 399 --condition below

# Add alert - notify when AAPL goes above $300
python3 scripts/alpaca_cli.py alert add --symbol AAPL --price 300 --condition above

# List active alerts
python3 scripts/alpaca_cli.py alert list

# Check alerts (used by cron)
python3 scripts/alpaca_cli.py alert check

# Remove an alert
python3 scripts/alpaca_cli.py alert remove --alert_id ABC123

# Clear all alerts
python3 scripts/alpaca_cli.py alert clear
```

Alerts are stored in `~/.openclaw/data/alpaca-alerts.json`.

## Script Location

All commands use: `scripts/alpaca_cli.py` (relative to this skill directory)

## API Reference

See `references/api.md` for detailed API documentation and response formats.

## Safety Notes

- Always confirm with user before placing real trades
- Paper trading (`ALPACA_PAPER=true`) recommended for testing
- Check buying power before large orders
- Verify order details before submission

Overview

This skill lets you trade stocks and crypto programmatically via the Alpaca API. It supports market data (quotes, bars, news), order placement (market, limit, stop, stop-limit), portfolio and position checks, and both paper and live trading. The skill includes safety guardrails and a CLI for common workflows.

How this skill works

The skill reads Alpaca API credentials from environment variables or a local credentials file and uses the Alpaca REST and streaming APIs to fetch market data, place and manage orders, and stream live updates. A command-line interface exposes quote, bars, account, positions, orders, watchlist, alerts, and streaming capabilities. Built-in validations inspect symbols, buying power, duplicate orders, price sanity, and market session state before submitting trades.

When to use it

Check real-time quotes, historical bars, or company news for research.
Place market, limit, stop, or stop-limit orders for stocks and crypto.
Manage and review open positions, total portfolio, and account details.
Stream live trades, quotes, or bars for automated strategies or monitoring.
Run price alerts via cron jobs to get notified when thresholds are crossed.

Best practices

Use paper trading mode for development and testing (ALPACA_PAPER=true).
Always confirm trade details with the user before submitting live orders.
Rely on the built-in guardrails: validate symbol, check buying power, and review duplicate orders.
Avoid skipping validation flags like --force unless you understand the risks.
Monitor market session (pre-market, regular, after-hours) before placing time-sensitive orders.

Example use cases

Quickly get the latest quote for AAPL or multiple tickers to inform a decision.
Place a limit buy for 10 shares of AAPL with price validation and cost confirmation.
Stream 1-minute bars for NVDA to feed a short-term trading strategy.
List open orders, cancel a specific order, or bulk-cancel all open orders.
Create and manage a watchlist and schedule cron-based price alerts.

FAQ

How do I provide API credentials?

Set ALPACA_API_KEY and ALPACA_SECRET_KEY as environment variables or place credentials in ~/.openclaw/credentials/alpaca.json.

Can I test without risking real money?

Yes. Enable paper trading by setting ALPACA_PAPER=true in your environment or credentials to use Alpaca's paper environment.