trader-broker

O que trader-broker faz?

O Executor de Ordens é o único skill neste pacote que pode levar a uma ordem real, por isso é o mais rigoroso. Uma ordem chega ao mercado apenas após três barreiras separadas, sempre, para cada ordem:

1. trader-risk aprovou esta ordem exata hoje (verificada por impressão digital).
2. O usuário digitou um sim explícito para esta ordem no chat.
3. O usuário clicou em Permitir uma vez no cartão de permissão do próprio Claude, que aparece porque a ferramenta de ordem está configurada como "Needs approval".

Dois sins do usuário, um PASS das regras. Sem sim, sem ordem.

${CLAUDE_SKILL_DIR} abaixo é a pasta deste skill (onde este SKILL.md reside).

python3 "${CLAUDE_SKILL_DIR}/ticket.py" show                     # todos os tickets, READY ou não
python3 "${CLAUDE_SKILL_DIR}/ticket.py" approve --index 1 --reply "sim"
python3 "${CLAUDE_SKILL_DIR}/ticket.py" result --index 1 --status placed --broker-id ID --filled-qty 8 --filled-price 364.20
python3 "${CLAUDE_SKILL_DIR}/ticket.py" fill --symbol TSLA --side sell --qty 8 --price 370.04
python3 "${CLAUDE_SKILL_DIR}/ticket.py" flatten --symbol TSLA --qty 8
python3 "${CLAUDE_SKILL_DIR}/ticket.py" log

ticket.py nunca fala com uma corretora. Ele renderiza tickets, verifica se uma resposta é um sim real para aquela ordem, constrói o ticket de fechamento e mantém o log em trader/state/broker.json. --now "2026-10-19 10:15" define o relógio (horário de Nova York).

O que ele lê e escreve

arquivo	o quê
trader/orders.json	as ordens propostas (trader-budget escreve; flatten substitui)
trader/state/risk.json	os vereditos do trader-risk; apenas um PASS de hoje é READY
trader/state/broker.json	cada sim, não, placed, failed e filled, com a perda máxima de cada entrada
trader/portfolio.json	dinheiro e ações, atualizado por fill e por result --filled-qty
trader/plan.json	o horário limite para flatten

Configuração A: Alpaca (servidor MCP oficial, Claude Desktop)

O próprio servidor da Alpaca é github.com/alpacahq/alpaca-mcp-server (MIT). Ele roda no computador do usuário dentro do Claude Desktop. Não está no diretório de conectores do Claude. Ele opera em uma conta simulada (paper) a menos que seja instruído de outra forma. Verificado contra seu código-fonte em 2026-10-20 (versão 2.4.0).

1. O usuário cria uma conta Alpaca e gera chaves de API de simulação no painel da Alpaca. As chaves de simulação são separadas das chaves reais.
2. O usuário instala o uv (que fornece uvx), a partir de docs.astral.sh/uv.
3. No Claude Desktop: Configurações > Desenvolvedor > Editar Config. Isso abre claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\). O usuário adiciona este bloco (também em claude_desktop_config.example.json aqui) e digita suas próprias chaves no arquivo:

{
  "mcpServers": {
    "alpaca": {
      "command": "uvx",
      "args": ["alpaca-mcp-server"],
      "env": {
        "ALPACA_API_KEY": "cole aqui sua chave de simulação, apenas neste arquivo",
        "ALPACA_SECRET_KEY": "cole aqui seu segredo de simulação, apenas neste arquivo",
        "ALPACA_PAPER_TRADE": "true",
        "ALPACA_TOOLSETS": "account,trading,stock-data"
      }
    }
  }
}

O bloco env entrega as chaves ao servidor como variáveis de ambiente. As chaves nunca vão para o chat. Nunca peça por elas, nunca leia este arquivo de volta para a conversa e, se o usuário colar uma chave de qualquer forma, diga a ele para deletar essa mensagem e criar novas chaves no painel da Alpaca. ALPACA_PAPER_TRADE já é verdadeiro por padrão; escrevê-lo o torna visível. ALPACA_TOOLSETS é opcional e esconde as ferramentas que ele não precisa. 4. Reinicie o Claude Desktop. 5. Defina as permissões das ferramentas. Personalizar > Conectores (Configurações > Conectores em versões mais antigas), abra alpaca e, para cada ferramenta, escolha Always allow, Needs approval ou Blocked:

• place_stock_order: Needs approval. Nunca Always allow.
• toda outra ferramenta que coloca, altera, cancela ou fecha algo (cancel_order_by_id, replace_order_by_id, close_position, update_account_config): Needs approval.
• place_option_order, place_crypto_order, close_all_positions, cancel_all_orders, exercise_options_position, do_not_exercise_options_position: Blocked a menos que o usuário tenha um motivo e o diga.
• ferramentas somente leitura (get_account_info, get_all_positions, get_open_position, get_orders, get_clock, get_stock_snapshot, get_stock_latest_quote): Always allow está ok.

6. Verifique: peça ao Claude as informações da conta Alpaca (somente leitura) e confirme no painel da Alpaca que é a conta de simulação.

No Claude Code em vez do Claude Desktop, mantenha a ferramenta de ordem em ask em .claude/settings.json: "permissions": {"ask": ["mcp__alpaca__place_stock_order"]}, e nunca coloque uma ferramenta de ordem em allow.

Ordens bracket na Alpaca. place_stock_order aceita take_profit_limit_price e stop_loss_stop_price (e um opcional stop_loss_limit_price). Quando qualquer um está presente, o servidor define order_class como "bracket" por conta própria; o trader-budget escreve de qualquer forma para que o ticket o exiba. Um bracket é apenas em ações inteiras, com time_in_force day ou gtc. Após o preenchimento da entrada, o stop-loss e o take-profit aguardam na corretora como duas ordens que se cancelam mutuamente. Elas também são ordens day, então terminam no fechamento: mais uma razão para estar flat até lá.

Configuração B: Interactive Brokers (conector no diretório do Claude)

O Interactive Brokers publica um conector verificado: claude.ai/directory/interactive-brokers (URL do conector https://api.ibkr.com/v1/api/mcp). Adicione-o em Personalizar > Conectores > Procurar conectores e faça login no IBKR lá, não no chat. A descrição diz que o Claude pode redigir instruções de negociação que são enviadas para a conta IBKR do usuário para sua revisão e aprovação, e que o Claude nunca envia ordens diretamente ao mercado. Então, com o IBKR, o sim final acontece no IBKR também. Defina "broker": "ibkr" em trader/config.json. Defina suas ferramentas que redigem ordens como Needs approval também.

Passos: a entrada

1. ticket.py show. Apenas tickets READY vão para o usuário. Um ticket que NÃO está READY ou BLOCKED retorna para /trader-risk.
2. Mostre UM ticket e pergunte: "Colocar esta ordem? Responda sim ou não." Uma ordem por pergunta. Nunca ofereça "sim para todas".
3. Execute ticket.py approve --index N --reply "<a resposta do usuário, palavra por palavra>". Se imprimir "Não registrado", a resposta não foi um sim explícito para esta ordem (por exemplo, "claro", "sim para todas" ou um sim que menciona uma ação ou quantidade diferente). Pergunte novamente. Nunca transforme uma resposta em um sim você mesmo.
4. Apenas após "Seu sim foi registrado", chame place_stock_order com exatamente o JSON que o ticket imprimiu. O cartão do Claude aparece: Permitir uma vez ou Negar.
5. Registre o que aconteceu: ticket.py result --index N --status placed --broker-id <id> --filled-qty Q --filled-price P (o preenchimento da resposta ou de get_open_position), ou --status denied, ou --status failed com --note. Uma ordem falha não é reenviada sem uma nova verificação e um novo sim. O log mantém a perda máxima da entrada para o limite diário do trader-risk.

Passos: enquanto está aberta, e sair até o fechamento

• trader-alerts monitora o stop, o alvo e o horário limite (alerts.py add --from-plan). As próprias ordens do bracket executam o stop.
• Quando o stop-loss ou o take-profit preenche, registre: ticket.py fill --symbol TSLA --side sell --qty 8 --price 358.32.
• Até flat_by (15:55 Nova York), qualquer coisa ainda aberta é fechada:
  1. Pergunte à Alpaca quantas ações estão sendo mantidas: get_open_position (somente leitura).
  2. ticket.py flatten --symbol TSLA --qty 8 escreve uma venda a mercado para essas ações em trader/orders.json.
  3. /trader-risk. Uma venda que apenas fecha o que o usuário possui nunca é bloqueada pelos limites diários ou pela janela de entrada.
  4. ticket.py show, então o sim do usuário para aquela ordem, como acima.
  5. O stop-loss e o take-profit do bracket ainda seguram essas ações, então a Alpaca rejeita uma nova venda até que sejam cancelados: get_orders (status open, nested true) os mostra; cancel_order_by_id cada um (Needs approval). Então place_stock_order com o ticket, depois result.

Exemplo: o modelo

ORDEM 1 de 1, conta SIMULADA, Alpaca
  COMPRAR 8 TSLA, mercado, válido para hoje
  stop-loss 358.32
  take-profit 370.04
  perda máxima cerca de $46,88 se o stop preencher a 358,32 (pode preencher pior em mercado rápido)
  motivo: rompimento de range de abertura na TSLA: 8 ações, limitado pela sua perda máxima de $50 por negociação (8 x 5,86 = $46,88 no stop)
  READY: trader-risk PASS, aguardando seu sim
  Claude chamará place_stock_order com exatamente:
    {"symbol": "TSLA", "side": "buy", "qty": "8", "type": "market", "time_in_force": "day",
     "order_class": "bracket", "take_profit_limit_price": "370.04", "stop_loss_stop_price": "358.32"}

O usuário responde "sim". Claude registra, chama place_stock_order, e o cartão mostra "Claude quer usar Place stock order" com aquele JSON e dois botões: Permitir uma vez, Negar. Permitir uma vez envia para a conta simulada. O why e o plano permanecem no arquivo; eles nunca são enviados.

O que ele nunca faz

• Nunca coloca uma ordem sem as três barreiras, e nunca duas ordens em um sim.
• Nunca coloca ordens a partir de uma tarefa agendada ou em segundo plano: não há ninguém para dizer sim.
• Nunca pede, lê, armazena ou repete chaves de API ou senhas.
• Nunca altera ALPACA_PAPER_TRADE ou "paper" para real. O usuário faz isso por conta própria.
• Nunca chama close_all_positions, cancel_all_orders ou ferramentas de opções ou cripto por conta própria.
• Nunca promete um preço de preenchimento: uma ordem a mercado e um stop preenchem pelo que o mercado oferece.

Segurança

• Educação e ferramentas, não aconselhamento financeiro. Um PASS é uma verificação de regras, não uma recomendação.
• Negociação simulada por padrão ("paper": true). Ir para o real é decisão do próprio usuário, em sua própria configuração.
• Nada neste pacote coloca uma ordem exceto trader-broker, e apenas quando os três se mantêm: trader-risk aprovou essa ordem exata hoje, o usuário digitou um sim explícito para aquela ordem no chat, e o usuário clicou em Permitir uma vez no cartão do próprio Claude porque a ferramenta de ordem está configurada como "Needs approval" (Personalizar > Conectores > permissões de ferramentas). Nunca defina uma ferramenta de ordem como "Always allow".
• Sem opções, margem, venda a descoberto ou alavancagem, a menos que a configuração permita e o usuário confirme.
• As chaves da corretora vivem em variáveis de ambiente ou no arquivo de configuração do Claude Desktop, nunca no chat.