trader-broker

Que fait trader-broker ?

L'Exécuteur d'Ordres est le seul skill de ce pack qui peut conduire à un ordre réel, il est donc le plus strict. Un ordre n'atteint le marché qu'après trois barrières distinctes, à chaque fois, pour chaque ordre :

1. trader-risk a validé cet ordre précis aujourd'hui (correspondance par empreinte).
2. L'utilisateur a tapé un oui explicite pour cet ordre dans le chat.
3. L'utilisateur a cliqué sur Autoriser une fois sur la carte de permission de Claude, qui apparaît parce que l'outil d'ordre est réglé sur « Nécessite une approbation ».

Deux oui de l'utilisateur, un PASS des règles. Pas de oui, pas d'ordre.

${CLAUDE_SKILL_DIR} ci-dessous est le dossier de ce skill (là où se trouve ce SKILL.md).

python3 "${CLAUDE_SKILL_DIR}/ticket.py" show                     # chaque ticket, PRÊT ou PAS
python3 "${CLAUDE_SKILL_DIR}/ticket.py" approve --index 1 --reply "oui"
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 ne parle jamais à un courtier. Il affiche les tickets, vérifie qu'une réponse est un vrai oui pour cet ordre, construit le ticket de flatten, et tient le journal dans trader/state/broker.json. --now "2026-10-19 10:15" fige l'horloge (heure de New York).

Ce qu'il lit et écrit

fichier	contenu
trader/orders.json	les ordres proposés (trader-budget les écrit ; flatten les remplace)
trader/state/risk.json	les verdicts de trader-risk ; seul un PASS d'aujourd'hui est PRÊT
trader/state/broker.json	chaque oui, non, placé, échoué et exécution, avec la perte max de chaque entrée
trader/portfolio.json	cash et actions, mis à jour par fill et par result --filled-qty
trader/plan.json	l'heure de flat pour flatten

Configuration A : Alpaca (serveur MCP officiel, Claude Desktop)

Le propre serveur d'Alpaca est github.com/alpacahq/alpaca-mcp-server (MIT). Il s'exécute sur l'ordinateur de l'utilisateur dans Claude Desktop. Il n'est pas dans le répertoire des connecteurs Claude. Il trade sur un compte paper sauf indication contraire. Vérifié par rapport à son code source le 2026-10-20 (version 2.4.0).

1. L'utilisateur crée un compte Alpaca et crée des clés API paper trading dans le tableau de bord Alpaca. Les clés paper sont séparées des clés live.
2. L'utilisateur installe uv (il fournit uvx), depuis docs.astral.sh/uv.
3. Dans Claude Desktop : Paramètres > Développeur > Modifier la config. Cela ouvre claude_desktop_config.json (macOS : ~/Library/Application Support/Claude/, Windows : %APPDATA%\Claude\). L'utilisateur ajoute ce bloc (également dans claude_desktop_config.example.json ici) et tape ses propres clés dans le fichier :

{
  "mcpServers": {
    "alpaca": {
      "command": "uvx",
      "args": ["alpaca-mcp-server"],
      "env": {
        "ALPACA_API_KEY": "collez votre clé paper ici, dans ce fichier uniquement",
        "ALPACA_SECRET_KEY": "collez votre secret paper ici, dans ce fichier uniquement",
        "ALPACA_PAPER_TRADE": "true",
        "ALPACA_TOOLSETS": "account,trading,stock-data"
      }
    }
  }
}

Le bloc env transmet les clés au serveur en tant que variables d'environnement. Les clés ne vont jamais dans le chat. Ne les demandez jamais, ne lisez jamais ce fichier dans la conversation, et si l'utilisateur colle une clé quand même, dites-lui de supprimer ce message et de créer de nouvelles clés dans le tableau de bord Alpaca. ALPACA_PAPER_TRADE est déjà true par défaut ; l'écrire le rend visible. ALPACA_TOOLSETS est optionnel et cache les outils dont ils n'ont pas besoin. 4. Redémarrez Claude Desktop. 5. Définissez les permissions des outils. Personnaliser > Connecteurs (Paramètres > Connecteurs dans les anciennes versions), ouvrez alpaca, et pour chaque outil choisissez Toujours autoriser, Nécessite une approbation ou Bloqué :

• place_stock_order : Nécessite une approbation. Jamais Toujours autoriser.
• tout autre outil qui place, modifie, annule ou ferme quoi que ce soit (cancel_order_by_id, replace_order_by_id, close_position, update_account_config) : Nécessite une approbation.
• place_option_order, place_crypto_order, close_all_positions, cancel_all_orders, exercise_options_position, do_not_exercise_options_position : Bloqué sauf si l'utilisateur a une raison et le dit.
• outils en lecture seule (get_account_info, get_all_positions, get_open_position, get_orders, get_clock, get_stock_snapshot, get_stock_latest_quote) : Toujours autoriser est correct.

6. Vérifiez : demandez à Claude les informations du compte Alpaca (lecture seule) et confirmez dans le tableau de bord Alpaca qu'il s'agit du compte paper.

Dans Claude Code au lieu de Claude Desktop, gardez l'outil d'ordre sur ask dans .claude/settings.json : "permissions": {"ask": ["mcp__alpaca__place_stock_order"]}, et ne mettez jamais un outil d'ordre dans allow.

Ordres bracket sur Alpaca. place_stock_order prend take_profit_limit_price et stop_loss_stop_price (et un stop_loss_limit_price optionnel). Quand l'un des deux est présent, le serveur définit order_class sur "bracket" tout seul ; trader-budget l'écrit quand même pour que le ticket l'affiche. Un bracket ne concerne que des actions entières, avec time_in_force day ou gtc. Après le remplissage de l'entrée, le stop-loss et le take-profit attendent chez le courtier sous forme de deux ordres qui s'annulent mutuellement. Ce sont aussi des ordres day, donc ils se terminent à la clôture : une raison de plus pour être flat d'ici là.

Configuration B : Interactive Brokers (connecteur dans le répertoire Claude)

Interactive Brokers publie un connecteur vérifié : claude.ai/directory/interactive-brokers (URL du connecteur https://api.ibkr.com/v1/api/mcp). Ajoutez-le depuis Personnaliser > Connecteurs > Parcourir les connecteurs et connectez-vous à IBKR là-bas, pas dans le chat. Sa fiche indique que Claude peut rédiger des instructions de trading qui sont envoyées au compte IBKR de l'utilisateur pour examen et approbation, et que Claude ne soumet jamais d'ordres directement au marché. Donc avec IBKR, le oui final se produit également dans IBKR. Définissez "broker": "ibkr" dans trader/config.json. Définissez aussi ses outils qui rédigent des ordres sur Nécessite une approbation.

Étapes : l'entrée

1. ticket.py show. Seuls les tickets PRÊTS sont présentés à l'utilisateur. Un ticket qui n'est PAS PRÊT ou BLOQUÉ retourne à /trader-risk.
2. Affichez UN ticket et demandez : « Passer cet ordre ? Répondez oui ou non. » Un ordre par question. Ne proposez jamais « oui pour tous ».
3. Exécutez ticket.py approve --index N --reply "<la réponse de l'utilisateur, mot pour mot>". S'il affiche « Non enregistré », la réponse n'était pas un oui explicite pour cet ordre (par exemple « sûr », « oui pour tous », ou un oui qui nomme une action ou un montant différent). Demandez à nouveau. Ne transformez jamais une réponse en oui vous-même.
4. Seulement après « Oui enregistré », appelez place_stock_order avec exactement le JSON que le ticket a affiché. La carte de Claude apparaît : Autoriser une fois ou Refuser.
5. Enregistrez ce qui s'est passé : ticket.py result --index N --status placed --broker-id <id> --filled-qty Q --filled-price P (le remplissage depuis la réponse ou get_open_position), ou --status denied, ou --status failed avec --note. Un ordre échoué n'est pas réessayé sans une nouvelle vérification et un nouveau oui. Le journal conserve la perte max de l'entrée pour la limite quotidienne de trader-risk.

Étapes : pendant que c'est ouvert, et sortie avant la clôture

• trader-alerts surveille le stop, l'objectif et l'heure de flat (alerts.py add --from-plan). Les propres ordres du bracket s'occupent du stop.
• Quand le stop-loss ou le take-profit se remplit, enregistrez-le : ticket.py fill --symbol TSLA --side sell --qty 8 --price 358.32.
• Avant flat_by (15h55 New York), tout ce qui est encore ouvert est fermé :
  1. Demandez à Alpaca combien d'actions sont détenues : get_open_position (lecture seule).
  2. ticket.py flatten --symbol TSLA --qty 8 écrit une vente au marché pour ces actions dans trader/orders.json.
  3. /trader-risk. Une vente qui ne fait que fermer ce que l'utilisateur détient n'est jamais bloquée par les limites quotidiennes ou la fenêtre d'entrée.
  4. ticket.py show, puis le oui de l'utilisateur pour cet ordre, comme ci-dessus.
  5. Le stop-loss et le take-profit du bracket détiennent toujours ces actions, donc Alpaca rejette une nouvelle vente tant qu'ils ne sont pas annulés : get_orders (statut open, nested true) les montre ; cancel_order_by_id chacun (Nécessite une approbation). Ensuite place_stock_order avec le ticket, puis result.

Exemple : la bande

ORDRE 1 sur 1, compte PAPER, Alpaca
  ACHETER 8 TSLA, marché, valable aujourd'hui
  stop-loss 358.32
  take-profit 370.04
  perte max environ 46,88 $ si le stop se remplit à 358.32 (peut être pire dans un marché rapide)
  raison : breakout de la range d'ouverture sur TSLA : 8 actions, limité à votre perte max de 50 $ par trade (8 x 5,86 = 46,88 $ au stop)
  PRÊT : trader-risk PASS, en attente de votre oui
  Claude appellera place_stock_order avec exactement :
    {"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"}

L'utilisateur répond « oui ». Claude l'enregistre, appelle place_stock_order, et la carte affiche « Claude veut utiliser Place stock order » avec ce JSON et deux boutons : Autoriser une fois, Refuser. Autoriser une fois l'envoie au compte paper. Le pourquoi et le plan restent dans le fichier ; ils ne sont jamais envoyés.

Ce qu'il ne fait jamais

• Ne passe jamais un ordre sans les trois barrières, et jamais deux ordres sur un seul oui.
• Ne passe jamais d'ordres depuis une tâche planifiée ou en arrière-plan : personne n'est là pour dire oui.
• Ne demande, ne lit, ne stocke et ne répète jamais les clés API ou mots de passe.
• Ne bascule jamais ALPACA_PAPER_TRADE ou "paper" en live. C'est l'utilisateur qui le fait lui-même.
• N'appelle jamais close_all_positions, cancel_all_orders, les outils d'options ou de crypto tout seul.
• Ne promet jamais un prix d'exécution : un ordre au marché et un stop se remplissent à ce que le marché donne.

Sécurité

• Éducation et outils, pas de conseil financier. Un PASS est une vérification des règles, pas une recommandation.
• Paper trading par défaut ("paper": true). Passer en live est la décision de l'utilisateur, dans sa propre config.
• Rien dans ce pack ne passe d'ordre sauf trader-broker, et seulement quand les trois conditions sont réunies : trader-risk a validé cet ordre précis aujourd'hui, l'utilisateur a tapé un oui explicite pour cet ordre dans le chat, et l'utilisateur a cliqué sur Autoriser une fois sur la carte de Claude parce que l'outil d'ordre est réglé sur « Nécessite une approbation » (Personnaliser > Connecteurs > permissions des outils). Ne réglez jamais un outil d'ordre sur « Toujours autoriser ».
• Pas d'options, marge, vente à découvert ou effet de levier sauf si la config l'autorise et que l'utilisateur confirme.
• Les clés du courtier résident dans les variables d'environnement ou la config de Claude Desktop, jamais dans le chat.