Communitygithub.com

Habilidade de Negociação Alpaca

Execute negociações, analise mercados e gerencie portfólios usando a ferramenta de linha de comando apcacli para a API de Negociação da Alpaca.

O que é Habilidade de Negociação Alpaca?

A Habilidade de Negociação Alpaca integra o agente de IA com a plataforma de negociação da Alpaca por meio da ferramenta de linha de comando `apcacli`, permitindo que os usuários executem negociações, gerenciem portfólios e acessem dados de mercado para ações, ETFs, opções e criptomoedas. Ela se destaca em automação segura, começando com paper trading e enfatizando a verificação de comandos, condições de mercado e gerenciamento de risco. A habilidade suporta uma ampla gama de operações, como envio de ordens de mercado, limite, stop e trailing stop, visualização de posições e P/L, verificação de saldos de conta e monitoramento de eventos em tempo real. É particularmente útil para traders que desejam automatizar fluxos de trabalho de negociação diretamente de um ambiente de linha de comando, proporcionando execução eficiente e potencialmente alavancando scripts e ferramentas de IA para tomada de decisão. Além das funcionalidades principais, a habilidade oferece práticas recomendadas para gestão de risco, como o uso de ordens limite e stop loss, e inclui guias de solução de problemas para erros comuns, como variáveis de ambiente não configuradas ou ordens rejeitadas. Ela também fornece comandos para verificar o status do mercado, visualizar atividades da conta e fechar posições de forma parcial ou total. A documentação abrange desde a instalação (`cargo install apcacli`) até recursos avançados como conclusão de shell e streaming em tempo real, tornando-a uma ferramenta abrangente para traders que buscam integrar negociação algorítmica com seus sistemas baseados em IA.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add lacymorrow/openclaw-alpaca-trading-skill

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Habilidade de Negociação Alpaca faz?

Execute negociações e gerencie portfólios através da ferramenta de linha de comando apcacli para a API de Negociação da Alpaca.

Instalação

apcacli é um CLI em Rust. Instale-o multiplataforma:

macOS (Homebrew)

brew install rustup
rustup-init -y
source "$HOME/.cargo/env"
cargo install apcacli

Linux

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"
cargo install apcacli

Windows

  1. Baixe e execute rustup-init.exe
  2. Abra um novo terminal, então: cargo install apcacli

Variáveis de Ambiente

export APCA_API_KEY_ID='seu-id-da-chave'
export APCA_API_SECRET_KEY='sua-chave-secreta'
# Para negociação ao vivo (o padrão é paper):
# export APCA_API_BASE_URL='https://api.alpaca.markets'

Visão Geral

Você é um especialista no uso do apcacli para negociação de ações em linha de comando. Seu objetivo é ajudar os usuários a negociar ações, ETFs, opções e criptomoedas de forma eficiente através da API da Alpaca, enfatizando segurança e melhores práticas.

Como Usar Esta Habilidade

Ao ajudar usuários com tarefas de negociação:

  1. Segurança Primeiro: Sempre recomende paper trading para novos usuários ou ao testar
  2. Verifique Comandos: Mostre o comando exato antes de executar negociações
  3. Verifique Pré-requisitos: Confirme horários de mercado, saldo da conta e símbolos válidos
  4. Explique Tipos de Ordem: Ajude os usuários a escolher o tipo de ordem certo para suas necessidades
  5. Gerenciamento de Risco: Sugira stop losses e dimensionamento de posição

O Que Esta Habilidade Faz

apcacli é um CLI baseado em Rust para interagir com a plataforma de negociação da Alpaca. Ele fornece:

  • Negociação: Enviar, modificar e cancelar ordens para ações, ETFs, opções e criptomoedas
  • Gerenciamento de Portfólio: Visualizar posições, P/L e informações da conta
  • Dados de Mercado: Acessar informações de ativos e status do relógio do mercado
  • Atividade da Conta: Acompanhar histórico de negociações e alterações na conta
  • Streaming em Tempo Real: Monitorar eventos da conta e de negociações

Quando Usar Esta Habilidade

Use esta habilidade quando o usuário quiser:

  • Executar negociações (comprar/vender ações, ETFs, opções, criptomoedas)
  • Verificar posições e desempenho do portfólio
  • Visualizar ou gerenciar ordens (abertas, preenchidas, canceladas)
  • Obter saldo da conta e poder de compra
  • Acessar dados de mercado e informações de ativos
  • Monitorar atividade da conta e eventos
  • Verificar se o mercado está aberto
  • Configurar stop losses ou trailing stops
  • Automatizar fluxos de trabalho de negociação com scripts

Frases de gatilho comuns:

  • "Compre 10 ações da AAPL"
  • "Mostre minhas posições abertas"
  • "Qual é o meu saldo da conta?"
  • "Liste todas as minhas ordens"
  • "Cancele a ordem [ID]"
  • "O mercado está aberto?"
  • "Mostre o desempenho do meu portfólio"
  • "Configure um stop loss na minha posição"
  • "Feche todas as minhas posições"

Quando NÃO usar esta habilidade:

  • O usuário quer negociação com interface gráfica (direcione-o para a interface web)
  • O usuário pede conselhos financeiros (você fornece ferramentas, não recomendações)
  • O usuário quer negociar instrumentos não suportados pela Alpaca
  • O usuário não tem o apcacli instalado (ajude-o a instalar primeiro)

Instalação e Configuração

Instalar apcacli

# Usando Cargo (gerenciador de pacotes Rust)
cargo install apcacli

# Verificar instalação
apcacli --help

Requisitos:

  • Rust 1.71 ou mais recente
  • Conta Alpaca (paper ou negociação ao vivo)
  • Credenciais da API Alpaca

Configurar Variáveis de Ambiente

Para Paper Trading (Recomendado para testes):

export APCA_API_KEY_ID='id_da_chave_paper'
export APCA_API_SECRET_KEY='chave_secreta_paper'
# Paper trading é o padrão, não é necessário definir APCA_API_BASE_URL

Para Negociação ao Vivo:

export APCA_API_BASE_URL='https://api.alpaca.markets'
export APCA_API_KEY_ID='id_da_chave_ao_vivo'
export APCA_API_SECRET_KEY='chave_secreta_ao_vivo'

Obter Credenciais da API:

  1. Cadastre-se em https://alpaca.markets/
  2. Navegue até seu painel
  3. Gere chaves de API (paper ou ao vivo)
  4. Exporte as variáveis de ambiente

Comandos Principais

Informações da Conta

Visualizar detalhes da conta:

apcacli account get

Mostra status da conta, saldo em dinheiro, poder de compra, patrimônio líquido e informações de margem.

Visualizar atividade da conta:

apcacli account activity

Exibe atividade recente da conta, incluindo negociações, dividendos e transferências.

Atualizar configuração da conta:

apcacli account config <opções>

Modifica configurações da conta (use --help para opções disponíveis).

Gerenciamento de Ordens

Enviar uma ordem de mercado:

# Comprar com valor em dólares
apcacli order submit buy AAPL --value 1000

# Comprar quantidade específica
apcacli order submit buy AAPL --quantity 10

# Vender ações
apcacli order submit sell TSLA --quantity 5

Enviar uma ordem limite:

# Comprar a preço específico
apcacli order submit buy MSFT --quantity 10 --limit-price 420

# Vender a preço específico
apcacli order submit sell NVDA --quantity 20 --limit-price 850

Enviar ordens avançadas:

# Ordem stop
apcacli order submit sell AAPL --quantity 10 --stop-price 180

# Ordem stop-limit
apcacli order submit sell TSLA --quantity 5 --stop-price 800 --limit-price 795

# Ordem trailing stop (porcentagem)
apcacli order submit sell NVDA --quantity 10 --trail-percent 5

Listar todas as ordens:

apcacli order list

Mostra todas as ordens com seu status (abertas, preenchidas, canceladas, etc.).

Obter detalhes de uma ordem específica:

apcacli order get <ID_DA_ORDEM>

Exibe informações completas da ordem, incluindo timestamps, preços e status.

Cancelar uma ordem:

apcacli order cancel <ID_DA_ORDEM>

Cancela uma ordem pendente pelo seu ID.

Cancelar todas as ordens:

apcacli order cancel-all

Cancela todas as ordens abertas.

Gerenciamento de Posições

Listar todas as posições abertas:

apcacli position list

Mostra todas as posições abertas com:

  • Quantidade e preço de entrada
  • Valor de mercado atual
  • P/L diário (com porcentagem)
  • P/L total (com porcentagem)
  • Lucro/prejuízo codificado por cores

Obter posição específica:

apcacli position get <SÍMBOLO>

Exibe informações detalhadas para uma posição específica.

Fechar uma posição:

# Fechar posição inteira
apcacli position close <SÍMBOLO>

# Fechar posição parcial
apcacli position close <SÍMBOLO> --quantity 5

Fechar todas as posições:

apcacli position close-all

Fecha todas as posições abertas.

Informações de Ativos

Listar ativos disponíveis:

apcacli asset list

Mostra todos os ativos negociáveis.

Obter detalhes do ativo:

apcacli asset get <SÍMBOLO>

Exibe informações do ativo, incluindo bolsa, classe e status de negociabilidade.

Pesquisar ativos:

apcacli asset search <CONSULTA>

Pesquisa ativos que correspondem à consulta.

Dados de Mercado

Verificar relógio do mercado:

apcacli market clock

Mostra status atual do mercado (aberto/fechado), próximo horário de abertura e próximo horário de fechamento.

Streaming (Eventos em Tempo Real)

Transmitir atualizações da conta:

apcacli stream account

Monitora eventos da conta em tempo real, incluindo atualizações de ordens e preenchimentos.

Transmitir atualizações de negociações:

apcacli stream trades

Monitora eventos de negociação em tempo real para suas posições.

Melhores Práticas

Segurança e Gerenciamento de Risco

  1. Comece com Paper Trading - Sempre teste estratégias primeiro com paper trading
  2. Use Ordens Limite - Evite ordens de mercado em condições voláteis para melhor controle de preço
  3. Verifique Símbolos - Verifique duas vezes os tickers antes de executar negociações
  4. Revise Antes de Executar - Use apcacli order get para verificar detalhes da ordem
  5. Defina Stop Losses - Proteja posições com ordens stop
  6. Verifique Saldo da Conta - Garanta poder de compra suficiente antes de negociar
  7. Monitore Posições - Revise regularmente o P/L com apcacli position list

Uso Eficaz

  1. Verifique a ajuda de qualquer comando - Use apcacli <comando> --help para opções detalhadas
  2. Salve IDs de ordens - Armazene IDs de ordens retornadas para rastrear e gerenciar ordens posteriormente
  3. Use variáveis de ambiente - Mantenha credenciais seguras em variáveis de ambiente, nunca codifique
  4. Verifique horários de mercado - Verifique apcacli market clock antes de colocar ordens
  5. Revise a atividade regularmente - Monitore a atividade da conta para alterações inesperadas

Fluxos de Trabalho Comuns

Compra simples de ações:

# 1. Verificar saldo da conta
apcacli account get

# 2. Verificar se o ativo é negociável
apcacli asset get AAPL

# 3. Verificar se o mercado está aberto
apcacli market clock

# 4. Enviar ordem de mercado
apcacli order submit buy AAPL --value 1000

# 5. Verificar posição
apcacli position list

Ordem limite com monitoramento:

# 1. Enviar ordem limite
apcacli order submit buy MSFT --quantity 10 --limit-price 420

# 2. Salvar o ID_DA_ORDEM retornado
# 3. Verificar status da ordem
apcacli order get <ID_DA_ORDEM>

# 4. Se necessário, cancelar
apcacli order cancel <ID_DA_ORDEM>

Revisão de portfólio:

# 1. Visualizar todas as posições
apcacli position list

# 2. Verificar resumo da conta
apcacli account get

# 3. Revisar atividade recente
apcacli account activity

Fechar posição com stop loss:

# 1. Verificar posição atual
apcacli position get AAPL

# 2. Definir trailing stop para proteger lucros
apcacli order submit sell AAPL --quantity 10 --trail-percent 5

# 3. Monitorar a ordem
apcacli order list

Guia de Referência Rápida de Comandos

TarefaComando
Visualizar contaapcacli account get
Atividade da contaapcacli account activity
Comprar ação (mercado)apcacli order submit buy SÍMBOLO --value VALOR
Comprar ação (limite)apcacli order submit buy SÍMBOLO --quantity N --limit-price PREÇO
Vender açãoapcacli order submit sell SÍMBOLO --quantity N
Listar todas as ordensapcacli order list
Obter detalhes da ordemapcacli order get ID_DA_ORDEM
Cancelar ordemapcacli order cancel ID_DA_ORDEM
Cancelar todas as ordensapcacli order cancel-all
Listar posiçõesapcacli position list
Obter posiçãoapcacli position get SÍMBOLO
Fechar posiçãoapcacli position close SÍMBOLO
Fechar todas as posiçõesapcacli position close-all
Listar ativosapcacli asset list
Obter info do ativoapcacli asset get SÍMBOLO
Verificar status do mercadoapcacli market clock
Transmitir eventos da contaapcacli stream account
Transmitir negociaçõesapcacli stream trades

Tipos de Ordem e Parâmetros

Parâmetros Básicos de Ordem

  • --quantity N - Número de ações para negociar
  • --value VALOR - Valor em dólares para investir (para ordens de mercado)
  • --limit-price PREÇO - Preço limite para ordens limite
  • --stop-price PREÇO - Preço stop para ordens stop
  • --trail-percent N - Porcentagem de trailing stop
  • --trail-amount VALOR - Valor em dólares do trailing stop

Tipos de Ordem

Ordem de Mercado - Executa imediatamente ao preço atual de mercado

apcacli order submit buy AAPL --quantity 10

Ordem Limite - Executa apenas ao preço especificado ou melhor

apcacli order submit buy AAPL --quantity 10 --limit-price 185

Ordem Stop - Converte em ordem de mercado quando o preço stop é atingido

apcacli order submit sell AAPL --quantity 10 --stop-price 180

Ordem Stop-Limit - Converte em ordem limite quando o preço stop é atingido

apcacli order submit sell AAPL --quantity 10 --stop-price 180 --limit-price 179

Trailing Stop - O preço stop segue o mercado por porcentagem ou valor especificado

# Baseado em porcentagem
apcacli order submit sell AAPL --quantity 10 --trail-percent 5

# Baseado em valor
apcacli order submit sell AAPL --quantity 10 --trail-amount 10

Notas Importantes

Requisitos

  • O binário apcacli deve estar instalado - Instale via cargo install apcacli
  • Variáveis de ambiente devem estar definidas - APCA_API_KEY_ID e APCA_API_SECRET_KEY são necessárias
  • Conta Alpaca - Conta de negociação paper ou ao vivo ativa
  • Rust 1.71+ - Necessário para instalação a partir do código fonte

Limitações de Negociação

  • Paper vs Ao Vivo: O padrão é paper trading; defina APCA_API_BASE_URL para negociação ao vivo
  • Horários de mercado: A maioria das negociações só executa durante o horário de mercado (9h30 - 16h00 ET)
  • Pattern Day Trading (PDT): Contas abaixo de $25k têm restrições PDT
  • Poder de compra: Limitado pelo patrimônio da conta e requisitos de margem
  • Restrições de ordem: Alguns tipos de ordem podem não estar disponíveis para todos os títulos
  • Negociação de criptomoedas: Pode ter regras e horários de negociação diferentes

Dados e Desempenho

  • Limites de taxa da API: A Alpaca tem limites de requisição para evitar abuso
  • Dados em tempo real: Pode exigir assinatura de dados ativa
  • Saída de comandos: Resultados formatados com codificação de cores para fácil leitura
  • IDs de ordens: Salve IDs de ordens retornados para rastreamento e gerenciamento
  • Dependência de rede: Requer conexão com a internet para a API da Alpaca

Solução de Problemas

Variáveis de Ambiente Não Definidas

# Erro: "Missing APCA_API_KEY_ID"
# Solução: Exporte as variáveis de ambiente necessárias
export APCA_API_KEY_ID='sua_chave'
export APCA_API_SECRET_KEY='seu_segredo'

Comando Não Encontrado

# Erro: "apcacli: command not found"
# Solução: Instale o apcacli
cargo install apcacli

# Verificar instalação
which apcacli

Autenticação da API Falhou

  • Verifique se as credenciais da API estão corretas
  • Verifique se está usando o endpoint correto (paper vs ao vivo)
  • Certifique-se de que as chaves da API não foram revogadas
  • Confirme que o status da conta está ativo

Ordem Rejeitada

  • Verifique se o mercado está aberto (para ações)
  • Verifique poder de compra suficiente
  • Confirme se o símbolo é válido e negociável
  • Revise os parâmetros da ordem (preço, quantidade)
  • Verifique se há restrições na conta

Posição Não Encontrada

  • Verifique se o símbolo está correto
  • Certifique-se de que a posição está realmente aberta
  • Verifique se a posição foi fechada anteriormente
  • Confirme se está usando a conta certa (paper vs ao vivo)

Recursos Avançados

Conclusão de Shell

Gere conclusão de shell para entrada de comandos mais rápida:

# Instalar script de conclusão
cargo run --bin=shell-complete > apcacli.bash
source apcacli.bash

# Agora você pode usar a conclusão com TAB
apcacli order <TAB>

Streaming para Monitoramento

Use comandos de streaming para monitorar a atividade da conta em tempo real:

# Terminal 1: Monitorar eventos da conta
apcacli stream account

# Terminal 2: Executar negociações
apcacli order submit buy AAPL

Habilidades Relacionadas