Habilidad de Trading con Alpaca
Opera y gestiona portafolios a través de la API REST de Alpaca usando scripts/alpaca.sh.
Configuración
Variables de entorno requeridas
| Variable | Propósito |
|---|---|
APCA_API_KEY_ID | Clave API de Alpaca |
APCA_API_SECRET_KEY | Secreto API de Alpaca |
Variables de entorno opcionales
| Variable | Valor por defecto | Propósito |
|---|---|---|
APCA_API_BASE_URL | https://paper-api.alpaca.markets | Endpoint de trading. Establecer a https://api.alpaca.markets para operar en vivo |
APCA_DATA_API_BASE_URL | https://data.alpaca.markets | Endpoint de datos de mercado |
El paper trading está activado por defecto. Confirma siempre con el usuario antes de cambiar al entorno real.
Script auxiliar
Cargue scripts/alpaca.sh desde el directorio de esta habilidad. Uso:
alpaca METHOD PATH [JSON_BODY]
# Datos de mercado:
ALPACA_DATA=1 alpaca METHOD PATH
Referencia rápida
Cuenta y portafolio
alpaca GET /v2/account # saldo, capital, poder de compra
alpaca GET /v2/account/configurations # configuración de trading
alpaca GET '/v2/account/portfolio/history?period=1M&timeframe=1D' # gráfico del portafolio
alpaca GET '/v2/account/activities?activity_types=FILL,DIV' # historial de operaciones/dividendos
alpaca GET /v2/clock # mercado abierto/cerrado
alpaca GET '/v2/calendar?start=2026-03-01&end=2026-03-31' # días de negociación
Órdenes — Acciones y Criptomonedas
# Compra a mercado (por cantidad o monto en dólares)
alpaca POST /v2/orders '{"symbol":"AAPL","qty":"10","side":"buy","type":"market","time_in_force":"day"}'
alpaca POST /v2/orders '{"symbol":"AAPL","notional":"1000","side":"buy","type":"market","time_in_force":"day"}'
# Criptomonedas (24/7)
alpaca POST /v2/orders '{"symbol":"BTC/USD","qty":"0.001","side":"buy","type":"market","time_in_force":"gtc"}'
# Límite / stop / stop-límite / trailing stop / bracket / OTO / OCO — consulte references/api.md
# Listar / obtener / reemplazar / cancelar
alpaca GET /v2/orders
alpaca GET /v2/orders/ORDER_ID
alpaca PATCH /v2/orders/ORDER_ID '{"qty":"20","limit_price":"190.00"}'
alpaca DELETE /v2/orders/ORDER_ID
alpaca DELETE /v2/orders # cancelar TODAS
Órdenes — Opciones
# Comprar call (Nivel 2+)
alpaca POST /v2/orders '{"symbol":"AAPL260418C00260000","qty":"1","side":"buy","type":"market","time_in_force":"day"}'
# Vender covered call (Nivel 1+, debe poseer 100 acciones por contrato)
alpaca POST /v2/orders '{"symbol":"AAPL260418C00270000","qty":"1","side":"sell","type":"limit","limit_price":"2.00","time_in_force":"day"}'
# Comprar/vender puts, cash-secured puts, spreads (Nivel 3) — consulte references/api.md
# Ejercer opción
alpaca POST /v2/positions/AAPL260418C00260000/exercise
# Buscar contratos
alpaca GET '/v2/options/contracts?underlying_symbols=AAPL&expiration_date_gte=2026-04-01&type=call&limit=10'
alpaca GET /v2/options/contracts/AAPL260418C00260000
Posiciones
alpaca GET /v2/positions # todas abiertas
alpaca GET '/v2/positions?asset_class=us_option' # solo opciones
alpaca GET /v2/positions/AAPL # acción individual
alpaca GET /v2/positions/NVDA260417C00220000 # opción individual
alpaca DELETE /v2/positions/AAPL # cerrar
alpaca DELETE '/v2/positions/AAPL?qty=5' # cerrar parcial
alpaca DELETE '/v2/positions?cancel_orders=true' # cerrar TODAS
Datos de mercado — Acciones
ALPACA_DATA=1 alpaca GET /v2/stocks/AAPL/snapshot # cotización + operación + vela
ALPACA_DATA=1 alpaca GET '/v2/stocks/snapshots?symbols=AAPL,MSFT,GOOGL' # múltiples instantáneas
ALPACA_DATA=1 alpaca GET '/v2/stocks/AAPL/bars?timeframe=1Day&start=2026-03-01&limit=30'
ALPACA_DATA=1 alpaca GET /v1beta1/screener/stocks/most-actives
ALPACA_DATA=1 alpaca GET '/v1beta1/screener/stocks/movers?top=10'
ALPACA_DATA=1 alpaca GET '/v1beta1/news?symbols=AAPL&limit=5'
Datos de mercado — Opciones
ALPACA_DATA=1 alpaca GET '/v1beta1/options/snapshots/AAPL?feed=indicative&limit=10' # cadena de opciones
ALPACA_DATA=1 alpaca GET '/v1beta1/options/bars?symbols=NVDA260417C00220000&timeframe=1Day&limit=10'
ALPACA_DATA=1 alpaca GET '/v1beta1/options/quotes/latest?symbols=NVDA260417C00220000'
ALPACA_DATA=1 alpaca GET '/v1beta1/options/trades/latest?symbols=NVDA260417C00220000'
# feed: indicative (gratuito/con retraso) o opra (requiere suscripción)
Datos de mercado — Criptomonedas
ALPACA_DATA=1 alpaca GET '/v1beta3/crypto/us/latest/quotes?symbols=BTC/USD'
ALPACA_DATA=1 alpaca GET '/v1beta3/crypto/us/bars?symbols=BTC/USD&timeframe=1Day&limit=30'
ALPACA_DATA=1 alpaca GET '/v1beta3/crypto/us/snapshots?symbols=BTC/USD,ETH/USD'
Acciones corporativas
ALPACA_DATA=1 alpaca GET '/v1/corporate-actions?symbols=AAPL&types=cash_dividend'
# Tipos: forward_split, reverse_split, cash_dividend, stock_dividend, spin_off, etc.
Activos y listas de seguimiento
alpaca GET /v2/assets/AAPL # información del activo
alpaca GET '/v2/assets?status=active&attributes=has_options' # acciones con opciones
alpaca GET /v2/watchlists # listar listas de seguimiento
alpaca POST /v2/watchlists '{"name":"Tech","symbols":["AAPL","MSFT","GOOGL"]}'
Referencia completa de la API
Lea references/api.md para la documentación completa de los endpoints, incluyendo:
- Todos los tipos de órdenes (límite, stop, stop-límite, trailing stop, bracket, OCO, OTO)
- Referencia de campos de órdenes (side, type, time_in_force, order_class)
- CRUD de listas de seguimiento
- Contratos de opciones
- Velas, operaciones y cotizaciones históricas con todos los parámetros de consulta
- Endpoints de criptomonedas
- Calendario de mercado
Reglas de seguridad
- Usar paper trading por defecto. Nunca establecer
APCA_API_BASE_URLal entorno real sin confirmación explícita del usuario. - Mostrar el JSON de la orden antes de enviarla. Permitir que el usuario confirme símbolo, cantidad, lado y tipo.
- Verificar el reloj del mercado antes de colocar órdenes — las acciones solo se negocian en horario de mercado (9:30-16:00 ET) a menos que se incluya
"extended_hours": trueen órdenes límite. - Verificar el poder de compra mediante
GET /v2/accountantes de órdenes grandes. - Nunca proporcionar asesoramiento financiero. Presentar datos; dejar que el usuario decida.
- Advertir sobre acciones irreversibles — cerrar todas las posiciones, cancelar todas las órdenes.
Solución de problemas
| Síntoma | Solución |
|---|---|
HTTP 401 | Verificar que APCA_API_KEY_ID / APCA_API_SECRET_KEY estén configuradas y sean válidas |
HTTP 403 | Claves de prueba en URL real o viceversa; verificar APCA_API_BASE_URL |
HTTP 422 (cantidad insuficiente) | Verificar poder de compra, soporte fraccional o validez del símbolo |
HTTP 429 | Límite de tasa alcanzado — esperar y reintentar; Alpaca permite 200 solicitudes/min |
| Orden rechazada fuera del horario | Agregar "extended_hours":true (solo órdenes límite) o esperar a la apertura del mercado |
jq: command not found | El script usa python3 -m json.tool como alternativa; instalar jq para mejor salida |