Skill de Negociação Alpaca
Negocie e gerencie portfólios via API REST da Alpaca usando scripts/alpaca.sh.
Configuração
Variáveis de ambiente obrigatórias
| Variável | Finalidade |
|---|---|
APCA_API_KEY_ID | Chave da API Alpaca |
APCA_API_SECRET_KEY | Segredo da API Alpaca |
Variáveis de ambiente opcionais
| Variável | Padrão | Finalidade |
|---|---|---|
APCA_API_BASE_URL | https://paper-api.alpaca.markets | Endpoint de negociação. Defina como https://api.alpaca.markets para ambiente real |
APCA_DATA_API_BASE_URL | https://data.alpaca.markets | Endpoint de dados de mercado |
Paper trading é o padrão. Sempre confirme com o usuário antes de alternar para o ambiente real.
Script auxiliar
Carregue scripts/alpaca.sh deste diretório da skill. Uso:
alpaca METHOD PATH [JSON_BODY]
# Dados de mercado:
ALPACA_DATA=1 alpaca METHOD PATH
Referência Rápida
Conta e portfólio
alpaca GET /v2/account # saldo, patrimônio líquido, poder de compra
alpaca GET /v2/account/configurations # configurações de negociação
alpaca GET '/v2/account/portfolio/history?period=1M&timeframe=1D' # gráfico do portfólio
alpaca GET '/v2/account/activities?activity_types=FILL,DIV' # histórico de negociações/dividendos
alpaca GET /v2/clock # mercado aberto/fechado
alpaca GET '/v2/calendar?start=2026-03-01&end=2026-03-31' # dias de negociação
Ordens — Ações e Criptomoedas
# Compra a mercado (por quantidade ou valor)
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"}'
# Cripto (24/7)
alpaca POST /v2/orders '{"symbol":"BTC/USD","qty":"0.001","side":"buy","type":"market","time_in_force":"gtc"}'
# Limite / stop / stop-limit / trailing stop / bracket / OTO / OCO — consulte references/api.md
# Listar / obter / substituir / 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
Ordens — Opções
# Comprar call (Nível 2+)
alpaca POST /v2/orders '{"symbol":"AAPL260418C00260000","qty":"1","side":"buy","type":"market","time_in_force":"day"}'
# Vender covered call (Nível 1+, é necessário possuir 100 ações 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 (Nível 3) — consulte references/api.md
# Exercer opção
alpaca POST /v2/positions/AAPL260418C00260000/exercise
# Consultar 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
Posições
alpaca GET /v2/positions # todas abertas
alpaca GET '/v2/positions?asset_class=us_option' # apenas opções
alpaca GET /v2/positions/AAPL # ação individual
alpaca GET /v2/positions/NVDA260417C00220000 # opção individual
alpaca DELETE /v2/positions/AAPL # fechar
alpaca DELETE '/v2/positions/AAPL?qty=5' # fechar parcial
alpaca DELETE '/v2/positions?cancel_orders=true' # fechar TODAS
Dados de mercado — Ações
ALPACA_DATA=1 alpaca GET /v2/stocks/AAPL/snapshot # cotação + negociação + barra
ALPACA_DATA=1 alpaca GET '/v2/stocks/snapshots?symbols=AAPL,MSFT,GOOGL' # múltiplos snapshots
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'
Dados de mercado — Opções
ALPACA_DATA=1 alpaca GET '/v1beta1/options/snapshots/AAPL?feed=indicative&limit=10' # cadeia de opções
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 (grátis/atrasado) ou opra (assinatura necessária)
Dados de mercado — Criptomoedas
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'
Ações 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.
Ativos e Listas de Observação
alpaca GET /v2/assets/AAPL # informações do ativo
alpaca GET '/v2/assets?status=active&attributes=has_options' # ações com opções habilitadas
alpaca GET /v2/watchlists # listar watchlists
alpaca POST /v2/watchlists '{"name":"Tecnologia","symbols":["AAPL","MSFT","GOOGL"]}'
Referência completa da API
Leia references/api.md para documentação completa dos endpoints, incluindo:
- Todos os tipos de ordem (limite, stop, stop-limit, trailing stop, bracket, OCO, OTO)
- Referência dos campos da ordem (side, type, time_in_force, order_class)
- CRUD de watchlists
- Contratos de opções
- Barras/negociações/cotações históricas com todos os parâmetros de consulta
- Endpoints de criptomoedas
- Calendário do mercado
Regras de Segurança
- Padrão para paper trading. Nunca defina
APCA_API_BASE_URLpara ambiente real sem confirmação explícita do usuário. - Mostre o JSON da ordem antes de enviar. Deixe o usuário confirmar símbolo, quantidade, lado e tipo.
- Verifique o relógio do mercado antes de colocar ordens — ações só negociam durante o horário de mercado (9:30-16:00 ET), a menos que
extended_hours: trueem ordens limite. - Verifique o poder de compra via
GET /v2/accountantes de ordens grandes. - Nunca forneça aconselhamento financeiro. Apresente os dados; deixe o usuário decidir.
- Alerta sobre ações irreversíveis — fechar todas as posições, cancelar todas as ordens.
Solução de Problemas
| Sintoma | Solução |
|---|---|
HTTP 401 | Verifique se APCA_API_KEY_ID / APCA_API_SECRET_KEY estão definidas e são válidas |
HTTP 403 | Chaves do paper na URL real ou vice-versa; verifique APCA_API_BASE_URL |
HTTP 422 (quantidade insuficiente) | Verifique poder de compra, suporte a frações ou validade do símbolo |
HTTP 429 | Limite de taxa excedido — aguarde e tente novamente; Alpaca permite 200 req/min |
| Ordem rejeitada fora do horário | Adicione "extended_hours":true (apenas ordens limite) ou aguarde a abertura do mercado |
jq: command not found | O script usa python3 -m json.tool como fallback; instale jq para melhor saída |